Expansion of spec-kit rules

[miroslavpojer]

Release Notes:

• Added connection to project md files.
• Added new rules expected in current code.

Summary by CodeRabbit

• Documentation
  • Updated governance constitution to v1.6.0 with expanded principles, including performance budgeting and API usage, readability/testability, structured error handling, static typing, TODO governance, security/token handling, and documentation-rule synchronization.
  • Introduced clearer testing and workflow gates (e.g., performance budgets, TODO checks, documentation sync).
  • Refreshed plan and spec templates with numbered principles (P1–P17) for clearer alignment.
  • Expanded tasks template: added typing/TODO/performance guidelines, reorganized phases, renumbered tasks, and provided new sample tasks across setup and user story phases.

[coderabbitai]

Walkthrough

Documentation-only updates across constitution and templates: version bump to 1.6.0, added/expanded principles (P7, P8, P9, P11–P17), and synchronized templates (plan, spec, tasks) with new governance items, performance budgeting, typing discipline, TODO governance, security handling, and documentation-rule synchronization.

Changes

Cohort / File(s)	Summary of changes
Constitution v1.6.0 update \.specify/memory/constitution.md	Version updated to 1.6.0; revised Principle 7 to combine API usage and performance budgeting; added/expanded Principles 8–9, 11–17; formalized testing/workflow gates, TODO governance, performance budget checks, and documentation-rule synchronization; updated governance metadata and history.
Plan template alignment with new principles \.specify/templates/plan-template.md	Converted dash bullets to explicit P1–P17 items; added requirements for performance budgeting, typing, error handling, test mirroring, branch naming, security, and doc-rule sync; structural/ordering changes only.
Spec template additions \.specify/templates/spec-template.md	Appended new Constitution Alignment items: P7 (Performance Budget & API Usage), P14 (Static Typing), P15 (TODO Governance), P16 (Security), P17 (Doc-Rule Sync); content-only.
Tasks template restructuring \.specify/templates/tasks-template.md	Added path conventions for typing/TODO/perf; expanded and renumbered tasks (T003–T007, etc.); introduced phased sample tasks; included performance scaffolding, typing, linting, TODO checks, and security/perf notes; documentation-only reorganization.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Dev as Developer
  participant Repo as Repository
  participant CI as CI Pipeline
  participant Lint as Lint/Format
  participant Type as Typing Check
  participant TODO as TODO Governance
  participant Perf as Perf Budget & API Rate Check
  participant DocSync as Doc-Rule Sync

  Dev->>Repo: Push/PR
  Repo-->>CI: Trigger workflow
  CI->>Lint: Run linters/formatters
  Lint-->>CI: Pass/Fail
  alt Lint failed
    CI-->>Repo: Status: Fail
  else Lint passed
    CI->>Type: Enforce static typing
    Type-->>CI: Pass/Fail
    alt Typing failed
      CI-->>Repo: Status: Fail
    else Typing passed
      CI->>TODO: Validate TODO governance
      TODO-->>CI: Pass/Fail
      alt TODO failed
        CI-->>Repo: Status: Fail
      else TODO passed
        CI->>Perf: Check performance budgets & rate limits
        Perf-->>CI: Pass/Warn/Fail
        alt Perf failed
          CI-->>Repo: Status: Fail
        else Continue
          CI->>DocSync: Verify doc-derived rules synced
          DocSync-->>CI: Pass/Fail
          CI-->>Repo: Status: Pass/Fail
        end
      end
    end
  end
  note over CI,Repo: New/expanded gates: Typing, TODO governance, Perf budget/API usage, Doc-Rule sync

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

I twitch my whiskers at version one-six-oh,
New rules burrow deep where governance must grow.
With budgets, types, and TODOs kept in sight,
Our CI garden nibbles wrongs to right.
I thump approval—docs aligned and neat,
Hop, hop—compliance tastes like clover sweet.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The provided description does not follow the repository’s required template because it omits the summary header, the pre-submission checklist, the additional context section, and the issue linkage, leaving out essential structure and details.	Please update the description to include the PR Summary at the top, complete the checklist items, add any relevant additional context, and link to the related issue using “Fixes #issue_number” to align with the repository template.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title “Expansion of spec-kit rules” is concise and directly reflects the primary change of adding and updating rules across the spec-kit documentation without extraneous detail, making it clear to reviewers what the pull request accomplishes.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/improve-spec-kit-files-add-more-limitations-related-to-project

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ece8f9b and c8016fd.

📒 Files selected for processing (4)

• .specify/memory/constitution.md (4 hunks)
• .specify/templates/plan-template.md (1 hunks)
• .specify/templates/spec-template.md (1 hunks)
• .specify/templates/tasks-template.md (7 hunks)

🧰 Additional context used

🪛 LanguageTool

.specify/templates/tasks-template.md

[grammar] ~25-~25: There might be a mistake here.
Context: ...DO():` pattern (Principle 15). - Performance: If feature affects mining/d...

(QB_NEW_EN)

---

[grammar] ~26-~26: There might be a mistake here.
Context: ... pattern (Principle 15). - Performance: If feature affects mining/data fetch loops...

(QB_NEW_EN)

---

[grammar] ~26-~26: There might be a mistake here.
Context: ...eature affects mining/data fetch loops, add measurement & API budget validation tas...

(QB_NEW_EN)

---

[grammar] ~34-~34: There might be a mistake here.
Context: ...01 Create any new module directories in release_notes_generator/ - [ ] T002 [P] Ensure mirrored test path s...

(QB_NEW_EN)

---

[grammar] ~35-~35: There might be a mistake here.
Context: ...e for new/relocated tests (Principle 12) - [ ] T003 Verify branch prefix matches re...

(QB_NEW_EN)

---

[grammar] ~36-~36: There might be a mistake here.
Context: ...rinciple 13) or rename before proceeding - [ ] T004 [P] Add initial failing unit te...

(QB_NEW_EN)

---

[grammar] ~37-~37: There might be a mistake here.
Context: ...s/unit/` for new logic (Test‑First gate) - [ ] T005 [P] Configure/verify linting, t...

(QB_NEW_EN)

---

[grammar] ~38-~38: There might be a mistake here.
Context: ... and formatting tools (Principles 1, 14) - [ ] T006 [P] Add TODO pattern linter or ...

(QB_NEW_EN)

---

[grammar] ~39-~39: There might be a mistake here.
Context: ... pattern linter or script (Principle 15) - [ ] T007 [P] Add performance baseline/me...

(QB_NEW_EN)

---

[grammar] ~50-~50: There might be a mistake here.
Context: ...ts/unit/test_action_inputs.py` extended) - [ ] T009 [P] Add utilities (if needed) w...

(QB_NEW_EN)

---

[grammar] ~51-~51: There might be a mistake here.
Context: ...ests (tests/unit/test_utils_<name>.py) - [ ] T010 Setup error handling pattern (l...

(QB_NEW_EN)

---

[grammar] ~52-~52: There might be a mistake here.
Context: ...urn) — no cross-module exception leakage - [ ] T011 Dead code removal (list obsolet...

(QB_NEW_EN)

---

[grammar] ~53-~53: There might be a mistake here.
Context: ...ions) + tests ensuring replacement paths - [ ] T012 Security review: confirm no sen...

(QB_NEW_EN)

---

[grammar] ~68-~68: There might be a mistake here.
Context: ...sts/unit/test_.py` (start failing) - [ ] T014 [US1] Update integration test (...

(QB_NEW_EN)

---

[grammar] ~73-~73: There might be a mistake here.
Context: ...nerator/.py` (full typing - P14) - [ ] T016 [US1] Logging additions (INFO l...

(QB_NEW_EN)

---

[grammar] ~74-~74: There might be a mistake here.
Context: ...DEBUG details) without secrets (P5, P16) - [ ] T017 [US1] Ensure deterministic orde...

(QB_NEW_EN)

---

[grammar] ~75-~75: There might be a mistake here.
Context: ... deterministic ordering adjustments (P3) - [ ] T018 [US1] Capture performance metri...

(QB_NEW_EN)

---

[grammar] ~94-~94: There might be a mistake here.
Context: ... existing module (maintain typing - P14) - [ ] T021 [US2] Update records builder en...

(QB_NEW_EN)

---

[grammar] ~95-~95: There might be a mistake here.
Context: ...ensuring no cross-module exceptions (P9) - [ ] T022 [US2] Update/extend performance...

(QB_NEW_EN)

---

[grammar] ~114-~114: There might be a mistake here.
Context: ...- [ ] T024 [US3] Implement functionality - [ ] T025 [US3] Update documentation/comm...

(QB_NEW_EN)

---

[grammar] ~115-~115: There might be a mistake here.
Context: .../comments (concise, logic-focused) (P11) - [ ] T026 [US3] Add/adjust TODOs with iss...

(QB_NEW_EN)

---

[grammar] ~116-~116: There might be a mistake here.
Context: ...adjust TODOs with issue references (P15) - [ ] T027 [US3] Re-run performance snapsh...

(QB_NEW_EN)

---

[grammar] ~127-~127: There might be a mistake here.
Context: ...ptimization / confirm within budget (P7) - [ ] TXXX [P] Additional unit tests (edge...

(QB_NEW_EN)

---

[grammar] ~128-~128: There might be a mistake here.
Context: ...] Additional unit tests (edge cases) in tests/unit/ - [ ] TXXX Security/robustness improvement...

(QB_NEW_EN)

---

[grammar] ~129-~129: There might be a mistake here.
Context: ...X Security/robustness improvements (P16) - [ ] TXXX TODO sweep: ensure all TODOs ha...

(QB_NEW_EN)

.specify/templates/plan-template.md

[grammar] ~33-~33: There might be a mistake here.
Context: ...t items: - Test‑First Reliability (P1): Provide failing unit test list BEFORE implement...

(QB_NEW_EN)

---

[grammar] ~33-~33: There might be a mistake here.
Context: ...ng unit test list BEFORE implementation. - Explicit Configuration Boundaries (P2): ...

(QB_NEW_EN)

---

[grammar] ~36-~36: There might be a mistake here.
Context: ...and fallback behavior if rate limit low. - Lean Python Design (P8): Justify each ne...

(QB_NEW_EN)

.specify/memory/constitution.md

[grammar] ~47-~47: There might be a mistake here.
Context: ...cumented soft performance budget. Rules: - Disable hierarchy expansion when feature...

(QB_NEW_EN)

---

[grammar] ~48-~48: There might be a mistake here.
Context: ... feature off to avoid unnecessary calls. - Avoid redundant fetches (cache IDs once ...

(QB_NEW_EN)

---

[grammar] ~50-~50: There might be a mistake here.
Context: ...ed, PRs processed, remaining rate limit. - Soft API call target: ≤ 3 * (issues + PR...

(QB_NEW_EN)

---

[grammar] ~52-~52: There might be a mistake here.
Context: ...hierarchy mining with a warning (do not fail build). - Performance baselines MUST be...

(QB_NEW_EN)

---

[grammar] ~52-~52: There might be a mistake here.
Context: ...ning with a warning (do not fail build). - Performance baselines MUST be periodical...

(QB_NEW_EN)

---

[grammar] ~102-~102: There might be a mistake here.
Context: ...mixing categories, uppercase, camelCase. - Scope alignment: PR description MUST ali...

(QB_NEW_EN)

---

[grammar] ~110-~110: There might be a mistake here.
Context: ...oad Any disallowed unless interacting with third-party library lacking stubs (just...

(QB_NEW_EN)

---

[grammar] ~110-~110: There might be a mistake here.
Context: ...y library lacking stubs (justify in PR). - Progressive enforcement: expand mypy cov...

(QB_NEW_EN)

---

[grammar] ~123-~123: There might be a mistake here.
Context: ...ent access limited to documented inputs. Rules: - Mask potentially sensitive subs...

(QB_NEW_EN)

---

[grammar] ~130-~130: There might be a mistake here.
Context: ...cumentation‑Derived Rule Synchronization Normative statements (MUST/SHOULD/SHALL/...

(QB_NEW_EN)

---

[grammar] ~131-~131: There might be a mistake here.
Context: ...roject Markdown docs (e.g., README.md, CONTRIBUTING.md, DEVELOPER.md, any `...

(QB_NEW_EN)

---

[grammar] ~132-~132: There might be a mistake here.
Context: ...iled with this constitution & templates. Rules: - Every PR modifying *.md files t...

(QB_NEW_EN)

---

[grammar] ~133-~133: There might be a mistake here.
Context: ...th this constitution & templates. Rules: - Every PR modifying *.md files that adds/...

(QB_NEW_EN)

---

[grammar] ~135-~135: There might be a mistake here.
Context: ...ng Principle X” (explicit reference), OR 2. A Constitution amendment (new/updated pr...

(QB_NEW_EN)

---

[grammar] ~136-~136: There might be a mistake here.
Context: ...on amendment (new/updated principle), OR 3. Justification that wording is purely exp...

(QB_NEW_EN)

---

[grammar] ~137-~137: There might be a mistake here.
Context: ...new rule) using phrase: NON-NORMATIVE in PR description. - If conflict between d...

(QB_NEW_EN)

---

[grammar] ~137-~137: There might be a mistake here.
Context: ...rase: NON-NORMATIVE in PR description. - If conflict between doc text and a princ...

(QB_NEW_EN)

---

[grammar] ~138-~138: There might be a mistake here.
Context: ... either patch docs or amends principles in same PR. - Introduced process steps (e....

(QB_NEW_EN)

---

[grammar] ~138-~138: There might be a mistake here.
Context: ...ch docs or amends principles in same PR. - Introduced process steps (e.g., ��run sc...

(QB_NEW_EN)

---

[grammar] ~139-~139: There might be a mistake here.
Context: ...e PR. - Introduced process steps (e.g., ��run script X before commit”) MUST appear in...

(QB_NEW_EN)

---

[grammar] ~139-~139: There might be a mistake here.
Context: ...vernance or quality gates section, OR (b) tasks template if feature-scoped. - A D...

(QB_NEW_EN)

---

[grammar] ~139-~139: There might be a mistake here.
Context: ...OR (b) tasks template if feature-scoped. - A Doc Rule Scan Script (planned) parses ...

(QB_NEW_EN)

---

[grammar] ~140-~140: There might be a mistake here.
Context: ...|SHOULD|SHALL|REQUIRED)\b` and fails CI unless reconciliation note present. - Template...

(QB_NEW_EN)

---

[grammar] ~140-~140: There might be a mistake here.
Context: ...s CI unless reconciliation note present. - Template Propagation: When new normative...

(QB_NEW_EN)

---

[grammar] ~141-~141: There might be a mistake here.
Context: ...n note present. - Template Propagation: When new normative doc rule is adopted, upda...

(QB_NEW_EN)

---

[grammar] ~141-~141: There might be a mistake here.
Context: ...lets, tasks-template path/quality gates. - Quarterly Audit: Run scan across repo; p...

(QB_NEW_EN)

---

[grammar] ~143-~143: There might be a mistake here.
Context: ...ibutor docs and enforceable governance; ensures single source of truth & predictable au...

(QB_NEW_EN)

---

[grammar] ~147-~147: There might be a mistake here.
Context: ...y & Testing - Test Directory Structure: - tests/unit/: All unit tests (test_<modul...

(QB_NEW_EN)

---

[grammar] ~148-~148: There might be a mistake here.
Context: ... (test_.py) — required location. - tests/integration/: End-to-end tests (in...

(QB_NEW_EN)

---

[style] ~151-~151: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...res/: Optional static data samples. - tests/helpers/ & tests/utils/: Test-only help...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[grammar] ~169-~169: There might be a mistake here.
Context: ...int global score ≥9.5 (no fatal errors). 3. Typing: mypy (0 blocking errors); justif...

(QB_NEW_EN)

---

[grammar] ~174-~174: There might be a mistake here.
Context: ...test run yields identical sample output. 8. Branch Naming: enforced allowed prefix. ...

(QB_NEW_EN)

---

[grammar] ~175-~175: There might be a mistake here.
Context: ... Branch Naming: enforced allowed prefix. 9. TODO Governance: all TODOs issue-linked ...

(QB_NEW_EN)

---

[grammar] ~191-~191: There might be a mistake here.
Context: ...compliance or list justified exceptions. - Versioning (this constitution): Semantic...

(QB_NEW_EN)

---

[grammar] ~193-~193: Use a hyphen to join words.
Context: ... Remove/redefine a principle or backward incompatible process change. - MINOR: ...

(QB_NEW_EN_HYPHEN)

---

[grammar] ~193-~193: There might be a mistake here.
Context: ...or backward incompatible process change. - MINOR: Add new principle/section or mate...

(QB_NEW_EN)

---

[grammar] ~194-~194: There might be a mistake here.
Context: ...incompatible process change. - MINOR: Add new principle/section or materially exp...

(QB_NEW_EN)

---

[grammar] ~194-~194: There might be a mistake here.
Context: ...e/section or materially expand guidance. - PATCH: Clarifications, numbering/order c...

(QB_NEW_EN)

---

[grammar] ~198-~198: There might be a mistake here.
Context: ...ith rationale & impact assessment. 2. Update Sync Impact Report header (include affe...

(QB_NEW_EN)

---

[grammar] ~198-~198: There might be a mistake here.
Context: ...er (include affected templates & TODOs). 3. Bump version according to rule above. ...

(QB_NEW_EN)

---

[grammar] ~201-~201: There might be a mistake here.
Context: ...12, 13, 14, 15, 17 + coverage threshold. - Backward Compatibility: Input names & pl...

(QB_NEW_EN)

---

[grammar] ~202-~202: There might be a mistake here.
Context: ...ty: Input names & placeholder semantics require MAJOR bump if changed. - Enforcement: C...

(QB_NEW_EN)

---

[grammar] ~202-~202: There might be a mistake here.
Context: ...semantics require MAJOR bump if changed. - Enforcement: CI automates formatting, li...

(QB_NEW_EN)

---

[grammar] ~205-~205: There might be a mistake here.
Context: ...025-10-12 | Last Amended: 2025-10-15

(QB_NEW_EN)

.specify/templates/spec-template.md

[grammar] ~13-~13: There might be a mistake here.
Context: ...), and mitigation if nearing rate limit. - Lean Python Design (P8): Prefer function...

(QB_NEW_EN)

---

[grammar] ~19-~19: There might be a mistake here.
Context: ...ic ID). Rename before merge if violated. - Static Typing Discipline (P14): All new ...

(QB_NEW_EN)

---

[grammar] ~21-~21: There might be a mistake here.
Context: ...ODO Debt Governance (P15): Any new TODO includes issue link (format TODO(<issue-id>):)...

(QB_NEW_EN)

---

[grammar] ~21-~21: There might be a mistake here.
Context: ...sue-id>):`); enumerate added TODO items. - Security & Token Handling (P16): Confirm...

(QB_NEW_EN)

🔇 Additional comments (2)

.specify/templates/spec-template.md (1)

13-23: Additions look solid.

New governance bullets are precise, actionable, and align with the surrounding template structure. Nice expansion.

.specify/templates/tasks-template.md (1)

24-26: Clarity on new governance checks looks great.

Explicitly tying typing, TODO hygiene, and performance validation back to the numbered principles keeps the template self-consistent with the updated constitution.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Fix incorrect change log entry.

The sync header claims “Modified principles: None,” but this PR revises existing principles (P7, P8, P9, P11–P16) and adds Principle 17. Leaving the entry as-is breaks the governance audit trail. Update the header to enumerate the modified principles so downstream automation and reviewers don’t get a false signal.

🤖 Prompt for AI Agents

In .specify/memory/constitution.md around line 4, the sync header incorrectly
reads "Modified principles: None" despite changes to existing principles and an
addition; update that header to list the modified principles P7, P8, P9, P11–P16
and note the new Principle 17 (e.g., "Modified principles: P7, P8, P9, P11–P16;
Added: P17") so the audit trail and downstream automation reflect the actual
changes.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Resolve garbled characters in Principle 17.

The text shows “��run script X before commit” instead of a readable quoted phrase. This corrupt encoding will confuse readers and could break any automation parsing the sentence. Replace the garbled characters with the intended quotation marks (e.g., “run script X before commit”).

🧰 Tools

🪛 LanguageTool

[grammar] ~139-~139: There might be a mistake here.
Context: ...e PR. - Introduced process steps (e.g., ��run script X before commit”) MUST appear in...

(QB_NEW_EN)

---

[grammar] ~139-~139: There might be a mistake here.
Context: ...vernance or quality gates section, OR (b) tasks template if feature-scoped. - A D...

(QB_NEW_EN)

---

[grammar] ~139-~139: There might be a mistake here.
Context: ...OR (b) tasks template if feature-scoped. - A Doc Rule Scan Script (planned) parses ...

(QB_NEW_EN)

🤖 Prompt for AI Agents

.specify/memory/constitution.md around line 139: Principle 17 contains garbled
characters “��run script X before commit” — replace the corrupted bytes with
proper Unicode quotation marks and the intended phrase so it reads e.g. “run
script X before commit”; ensure file is saved with UTF-8 encoding and run a
quick scan for other non-UTF-8 replacement characters to avoid similar
corruption elsewhere.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Clarify fallback behavior wording

Line 36 drops the verb in “fallback behavior if rate limit low,” which reads awkwardly. Please add the missing verb for clarity.

-- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and fallback behavior if rate limit low.
+- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and define fallback behavior if rate limits are low.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and fallback behavior if rate limit low.
	- Lean Python Design (P8): Justify each new class; prefer functions for stateless logic.
	- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and define fallback behavior if rate limits are low.
	- Lean Python Design (P8): Justify each new class; prefer functions for stateless logic.

🧰 Tools

🪛 LanguageTool

[grammar] ~36-~36: There might be a mistake here.
Context: ...and fallback behavior if rate limit low. - Lean Python Design (P8): Justify each ne...

(QB_NEW_EN)

🤖 Prompt for AI Agents

In .specify/templates/plan-template.md around lines 36 to 37, the phrase
"fallback behavior if rate limit low" is missing a verb and reads awkwardly;
change it to include the verb (e.g., "fallback behavior if the rate limit is
low" or "fallback behavior if rate limits are low") to make the sentence
grammatically correct and clearer.