Spec Driven Development Enforcement#521
Merged
kingargyle merged 3 commits intodevelopfrom Feb 16, 2026
Merged
Conversation
Contributor
WalkthroughAdded a Phased Spec-Driven Development (SDD) protocol and supporting artifacts: a SPEC_WRITER persona, a TASK_SPEC template, and an sdd_implementation plan. Agent guidance in AGENTS.md and COMMUNICATION.md was updated to require phased specs and a complexity threshold for multi-file or architectural tasks. Changes
Sequence Diagram(s)sequenceDiagram
rect rgba(100,150,250,0.5)
participant User
end
rect rgba(150,200,100,0.5)
participant SpecWriter
end
rect rgba(250,200,100,0.5)
participant Agent
end
rect rgba(200,100,150,0.5)
participant HumanApprover
end
User->>SpecWriter: Request complex change / provide context
SpecWriter->>User: Ask clarifying questions (if needed)
SpecWriter->>Agent: Produce Phased GSD Spec (Goal, Steps, Deliverables)
Agent->>HumanApprover: Execute Phase 1 tasks, create verification artifacts
HumanApprover-->>Agent: Approve or request revisions (gate)
Agent->>HumanApprover: Execute subsequent phases per spec until final validation
HumanApprover-->>User: Final approval / deliverables
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts (beta)
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. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #521 +/- ##
==========================================
Coverage 53.21% 53.21%
Complexity 518 518
==========================================
Files 69 69
Lines 2302 2302
Branches 329 329
==========================================
Hits 1225 1225
Misses 911 911
Partials 166 166
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
Before applying any fix, first verify the finding against the current code and
decide whether a code change is actually needed. If the finding is not valid or
no change is required, do not modify code for that item and briefly explain why
it was skipped.
In `@AGENTS.md`:
- Line 46: Standardize the SPEC_WRITER.md reference in AGENTS.md: replace the
abbreviated reference '@SPEC_WRITER.md' with the full relative path
'@./prompts/agents/SPEC_WRITER.md' (or vice versa if you prefer the short form)
so all mentions of SPEC_WRITER.md use the same syntax; search for both
'@./prompts/agents/SPEC_WRITER.md' and '@SPEC_WRITER.md' in AGENTS.md and make
them identical, preserving existing link behavior and formatting.
In `@prompts/agents/COMMUNICATION.md`:
- Line 3: Update the "Complexity Threshold" line in COMMUNICATION.md to include
an explicit path to the SDD Protocol document (replace "see SDD Protocol" with a
concrete reference like "see SDD Protocol (docs/SDD_PROTOCOL.md)" or the
project's canonical path used in AGENTS.md); edit the phrase containing
"Complexity Threshold" so it matches AGENTS.md's referencing style and ensure
the link or path points to the SDD Protocol file name or section so readers can
navigate directly.
In `@prompts/agents/SPEC_WRITER.md`:
- Line 9: Update the file reference in prompts/agents/SPEC_WRITER.md to match
the project's documented convention used in AGENTS.md by replacing the
backticked relative path `prompts/templates/TASK_SPEC.md` with the prefixed form
`@./prompts/templates/TASK_SPEC.md`; locate the string in the line containing
"GENERATE a Phased GSD Spec" and make the substitution so documentation
references are consistent across files.
In `@prompts/plans/sdd_implementation_v1.md`:
- Around line 69-95: The embedded TASK_SPEC.md template in
prompts/plans/sdd_implementation_v1.md duplicates the canonical template and
risks drift; remove the inline markdown block under "Task 1.4: Create
`TASK_SPEC.md` Template" and replace it with a short reference pointing to the
single source of truth prompts/templates/TASK_SPEC.md (e.g., "See
prompts/templates/TASK_SPEC.md for template structure"), keeping the task
description and links intact and ensuring the checklist item (Task 1.4) still
clearly instructs to create/verify the template.
- Around line 2-3: The document's filename sdd_implementation_v1.md conflicts
with the internal metadata "Version: 1.6.0"; reconcile them by either updating
the metadata Version field to "1.0.0" (or "1.0.0" style you use for initial
releases) or renaming the file to match the declared version (e.g.,
sdd_implementation_v1.6.0.md); ensure the chosen change is applied consistently
and update any references to this file/version elsewhere if present.
🧹 Nitpick comments (4)
🤖 Fix all nitpicks with AI agents
Before applying any fix, first verify the finding against the current code and decide whether a code change is actually needed. If the finding is not valid or no change is required, do not modify code for that item and briefly explain why it was skipped. In `@AGENTS.md`: - Line 46: Standardize the SPEC_WRITER.md reference in AGENTS.md: replace the abbreviated reference '@SPEC_WRITER.md' with the full relative path '@./prompts/agents/SPEC_WRITER.md' (or vice versa if you prefer the short form) so all mentions of SPEC_WRITER.md use the same syntax; search for both '@./prompts/agents/SPEC_WRITER.md' and '@SPEC_WRITER.md' in AGENTS.md and make them identical, preserving existing link behavior and formatting. In `@prompts/agents/COMMUNICATION.md`: - Line 3: Update the "Complexity Threshold" line in COMMUNICATION.md to include an explicit path to the SDD Protocol document (replace "see SDD Protocol" with a concrete reference like "see SDD Protocol (docs/SDD_PROTOCOL.md)" or the project's canonical path used in AGENTS.md); edit the phrase containing "Complexity Threshold" so it matches AGENTS.md's referencing style and ensure the link or path points to the SDD Protocol file name or section so readers can navigate directly. In `@prompts/agents/SPEC_WRITER.md`: - Line 9: Update the file reference in prompts/agents/SPEC_WRITER.md to match the project's documented convention used in AGENTS.md by replacing the backticked relative path `prompts/templates/TASK_SPEC.md` with the prefixed form `@./prompts/templates/TASK_SPEC.md`; locate the string in the line containing "GENERATE a Phased GSD Spec" and make the substitution so documentation references are consistent across files. In `@prompts/plans/sdd_implementation_v1.md`: - Around line 2-3: The document's filename sdd_implementation_v1.md conflicts with the internal metadata "Version: 1.6.0"; reconcile them by either updating the metadata Version field to "1.0.0" (or "1.0.0" style you use for initial releases) or renaming the file to match the declared version (e.g., sdd_implementation_v1.6.0.md); ensure the chosen change is applied consistently and update any references to this file/version elsewhere if present.prompts/plans/sdd_implementation_v1.md (1)
2-3: Version number appears inconsistent with filename.The filename
sdd_implementation_v1.mdsuggests this is version 1, but the document metadata specifiesVersion: 1.6.0. Consider either updating the version to1.0.0for a first release or adjusting the filename to reflect the 1.6.0 version if that's intentional.🤖 Prompt for AI Agents
Before applying any fix, first verify the finding against the current code and decide whether a code change is actually needed. If the finding is not valid or no change is required, do not modify code for that item and briefly explain why it was skipped. In `@prompts/plans/sdd_implementation_v1.md` around lines 2 - 3, The document's filename sdd_implementation_v1.md conflicts with the internal metadata "Version: 1.6.0"; reconcile them by either updating the metadata Version field to "1.0.0" (or "1.0.0" style you use for initial releases) or renaming the file to match the declared version (e.g., sdd_implementation_v1.6.0.md); ensure the chosen change is applied consistently and update any references to this file/version elsewhere if present.prompts/agents/COMMUNICATION.md (1)
3-3: Add explicit reference to the SDD Protocol documentation.The line mentions "see SDD Protocol" but doesn't specify where to find it. For better navigation and consistency with AGENTS.md's referencing style, consider adding an explicit path reference.
📖 Proposed improvement
-- **Complexity Threshold**: Any task affecting more than 2 files, involving architectural changes, or adding new libraries REQUIRES a Phased GSD Spec (see SDD Protocol). +- **Complexity Threshold**: Any task affecting more than 2 files, involving architectural changes, or adding new libraries REQUIRES a Phased GSD Spec (see @./AGENTS.md#phased-spec-driven-development-sdd or @./prompts/plans/sdd_implementation_v1.md).🤖 Prompt for AI Agents
Before applying any fix, first verify the finding against the current code and decide whether a code change is actually needed. If the finding is not valid or no change is required, do not modify code for that item and briefly explain why it was skipped. In `@prompts/agents/COMMUNICATION.md` at line 3, Update the "Complexity Threshold" line in COMMUNICATION.md to include an explicit path to the SDD Protocol document (replace "see SDD Protocol" with a concrete reference like "see SDD Protocol (docs/SDD_PROTOCOL.md)" or the project's canonical path used in AGENTS.md); edit the phrase containing "Complexity Threshold" so it matches AGENTS.md's referencing style and ensure the link or path points to the SDD Protocol file name or section so readers can navigate directly.AGENTS.md (1)
46-46: Inconsistent file reference syntax within the same document.Line 15 references the SPEC_WRITER.md file as
@./prompts/agents/SPEC_WRITER.md(full relative path), while line 46 uses@SPEC_WRITER.md(abbreviated). For consistency and clarity, consider using the same reference format throughout the document.🔧 Proposed fix for consistency
-3. **Complexity**: Does it require a Phased GSD Spec? (See `@SPEC_WRITER.md`) +3. **Complexity**: Does it require a Phased GSD Spec? (See @./prompts/agents/SPEC_WRITER.md)🤖 Prompt for AI Agents
Before applying any fix, first verify the finding against the current code and decide whether a code change is actually needed. If the finding is not valid or no change is required, do not modify code for that item and briefly explain why it was skipped. In `@AGENTS.md` at line 46, Standardize the SPEC_WRITER.md reference in AGENTS.md: replace the abbreviated reference '@SPEC_WRITER.md' with the full relative path '@./prompts/agents/SPEC_WRITER.md' (or vice versa if you prefer the short form) so all mentions of SPEC_WRITER.md use the same syntax; search for both '@./prompts/agents/SPEC_WRITER.md' and '@SPEC_WRITER.md' in AGENTS.md and make them identical, preserving existing link behavior and formatting.prompts/agents/SPEC_WRITER.md (1)
9-9: Consider standardizing file reference syntax across the documentation.This file uses backticks with relative paths (e.g.,
prompts/templates/TASK_SPEC.md), while AGENTS.md uses the@./prefix (e.g.,@./prompts/templates/TASK_SPEC.md). Standardizing the reference syntax across all documentation files would improve consistency and reduce potential confusion.🤖 Prompt for AI Agents
Before applying any fix, first verify the finding against the current code and decide whether a code change is actually needed. If the finding is not valid or no change is required, do not modify code for that item and briefly explain why it was skipped. In `@prompts/agents/SPEC_WRITER.md` at line 9, Update the file reference in prompts/agents/SPEC_WRITER.md to match the project's documented convention used in AGENTS.md by replacing the backticked relative path `prompts/templates/TASK_SPEC.md` with the prefixed form `@./prompts/templates/TASK_SPEC.md`; locate the string in the line containing "GENERATE a Phased GSD Spec" and make the substitution so documentation references are consistent across files.
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/plans/sdd_implementation_v1.md`:
- Around line 114-116: Update the Task 2.2 file list so the platform name is
capitalized: in the bullet under "Task 2.2: Generate Agent-Specific
Configuration Files" replace the lowercase "github" reference with "GitHub"
(e.g., change the item to reference GitHub `.github/copilot-instructions.md` or
prefix the path with "GitHub: `.github/copilot-instructions.md`), ensuring the
platform name "GitHub" is used instead of "github" in the file list.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Creates a prompt to help wire up a project to enforce a Spec Driven Development methodolgy when requirements are uniquely vague.
Summary by CodeRabbit