feat: Enhance custom Spec Driven Development agent guidance.#522
feat: Enhance custom Spec Driven Development agent guidance.#522kingargyle merged 1 commit intodevelopfrom
Conversation
Add a custom content_discovery prompt to review the project for existing architecture guidance that is not currently listed for the project. Implement a memory system of what has been completed and when.
WalkthroughThis PR introduces SDD v2.0, expanding the spec-driven development protocol with enhanced documentation governance, architectural standards, and persistent memory logging. It adds new protocol references, establishes mandatory pre-spec interviews with impact analysis, organizes plans into subdirectories with memory folders, and consolidates project philosophy and technical guidelines across new and updated agent documentation files. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). 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 |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
AGENTS.md (1)
45-45:⚠️ Potential issue | 🟡 MinorUpdate backend naming to match current project standards.
Line 45 still says
(Plex/Emby), but this PR’s governance docs describe Emby/Jellyfin with Plex deprecated. Keeping both statements creates conflicting “source of truth” guidance for agents.Based on learnings, the protocol and checklist are intended to provide a consistent single source of truth before execution.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` at line 45, Update the backend naming in the AGENTS.md line that currently reads "Serenity for Android is a media server client for Android (Plex/Emby)" so it matches the project's governance: replace the parenthetical "(Plex/Emby)" with "(Emby/Jellyfin)" or otherwise indicate Plex is deprecated; edit the sentence in AGENTS.md (the "Serenity for Android..." line) to reflect Emby/Jellyfin as the supported backends and remove the conflicting Plex reference.
🧹 Nitpick comments (5)
prompts/agent_file_dir_tips.md (1)
22-22: Consider simplifying wording.The phrase "keeps the user in control of" could be shortened to "keeps the user controlling" or "gives the user control over" for conciseness.
✨ Optional improvement
-* **Why:** This keeps the user in control of destructive operations and prevents "ghost files" from breaking the build. +* **Why:** This gives the user control over destructive operations and prevents "ghost files" from breaking the build.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/agent_file_dir_tips.md` at line 22, Replace the phrasing "keeps the user in control of destructive operations and prevents 'ghost files' from breaking the build" with a more concise alternative such as "gives the user control over destructive operations and prevents 'ghost files' from breaking the build" (or "keeps the user in control of destructive operations") in prompts/agent_file_dir_tips.md to improve clarity while preserving meaning; update the exact sentence containing "keeps the user in control of" to one of these shorter options.prompts/agents/SPEC_WRITER.md (1)
9-9: Optional wording cleanup for brevity.You can shorten “ensure the proposed plan aligns” to “ensure the plan aligns” for tighter phrasing without changing intent.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/agents/SPEC_WRITER.md` at line 9, In SPEC_WRITER.md, shorten the phrase in the "Pre-Drafting Standard Review" step by replacing "ensure the proposed plan aligns with the project's 'Golden Standards'" with "ensure the plan aligns with the project's 'Golden Standards'" to tighten wording while preserving intent; locate the step header "Pre-Drafting Standard Review" and update the sentence accordingly.prompts/plans/sdd_implementation_v1.md (3)
14-14: Self-reference uses filename, creating maintenance brittleness.The prompt pattern references the specific filename
sdd_implementation_v1.md. If this file is renamed (as suggested for the v2.0.0 version), this reference will become stale. Consider using a more generic reference like "Using the SDD protocol" or a relative path that's easier to maintain.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/plans/sdd_implementation_v1.md` at line 14, The prompt text currently hardcodes the filename "prompts/plans/sdd_implementation_v1.md" (the string in the diff: "Using the protocol in `prompts/plans/sdd_implementation_v1.md`, create a Phased GSD Spec for [Task Description]"), which is brittle; update that prompt to reference a generic identifier such as "the SDD protocol" or a stable relative reference (e.g., "Using the SDD protocol in prompts/plans/SDD_PROTOCOL.md") so renames won't break it; modify the string in the prompt generator or template where that exact quoted text appears to use the new generic phrasing while preserving surrounding structure.
28-28: Memory file naming conventions not explicitly documented.While the example at lines 35-38 shows a numbered prefix pattern (
01_dependency_discovery.md), the protocol doesn't explicitly document naming conventions for memory files. Consider adding guidance on the naming pattern (e.g., numbered prefixes, descriptive names, when to create new files vs. append to existing ones) to ensure consistency across different plans.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/plans/sdd_implementation_v1.md` at line 28, Update the "Discovery Logging" instruction to explicitly document memory file naming conventions: state that files live under prompts/plans/<plan_name>/memory/, use a two-digit numbered prefix for ordering (e.g., 01_dependency_discovery.md), follow with a concise descriptive slug, prefer creating a new file for distinct discoveries or dependencies and append to an existing file only for incremental notes about the same item, and include examples and a brief rule for when to increment the number vs. reuse a file name; reference the "Discovery Logging" line and the example filename `01_dependency_discovery.md` to guide placement.
19-19: "Impact Analysis" lacks explicit definition.The protocol mandates performing an "Impact Analysis" during the collaborative interview but doesn't define what this entails. Consider adding a brief definition or reference to documentation that explains what should be included (e.g., downstream consumers, breaking changes, affected modules).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/plans/sdd_implementation_v1.md` at line 19, Update the "Impact Analysis" item in prompts/plans/sdd_implementation_v1.md to include a concise definition and examples of what to cover: list downstream consumers, affected modules/components, API/contract changes, potential breaking changes, data migrations, deployment windows, and recommended rollback/mitigation steps; reference any existing internal docs or a template (if available) and point to where teams should document dependency owners and estimated blast radius so the collaborative interview always yields actionable impact and risk/rollback information.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@prompts/agent_file_dir_tips.md`:
- Line 3: The sentence "AI agents (like Android Studio Gemini) that have
specialized toolsets but lacks direct terminal/shell access" has a subject-verb
agreement error; change "lacks" to "lack" if treating "AI agents" as plural, or
rephrase to singular for clarity (e.g., "an AI agent, such as Android Studio
Gemini, that has specialized toolsets but lacks direct terminal/shell access");
update the line in prompts/agent_file_dir_tips.md so the noun and verb agree and
the parenthetical example reads clearly.
In `@prompts/plans/context_discovery/context_discovery.md`:
- Line 40: The Phase 2 verification rule that mandates "All files exist in
`prompts/agents/` with 'Mission,' 'Non-Negotiables,' and 'Code Examples'
sections" is too strict; update context_discovery.md to replace this blanket
requirement with per-file acceptance criteria by enumerating expected document
types (e.g., framework index, constitution, protocol) and for each listing which
sections are required (for example: constitution -> Mission + Non-Negotiables,
protocol -> Code Examples + optional Mission, index -> metadata only). Locate
the Phase 2 verification text in context_discovery.md and change the single "All
files..." sentence into a short table or bullets of per-file criteria, and
adjust any associated pass/fail logic language to validate against the per-file
rules rather than a universal checklist.
In `@prompts/plans/protocol_integration/protocol_integration.md`:
- Around line 37-44: Phase 3 is outdated: the TASK_SPEC.md template already has
a "Standards Compliance" section and checklists, so update the Phase 3 block in
protocol_integration.md to reflect that (do not re-add the section).
Specifically, replace the two implementation tasks ("Update
prompts/templates/TASK_SPEC.md..." and "Define a checklist...") with
verification/validation steps that reference the existing Standards Compliance
block in prompts/templates/TASK_SPEC.md (e.g., "Verify TASK_SPEC.md contains
Standards Compliance with Architecture, UI/Leanback, Communication, and Testing
checklists" and "Ensure new specs generated from TASK_SPEC.md include those
checklist items"), and remove the [WAIT FOR APPROVAL] footnote or clarify it as
needed; reference TASK_SPEC.md and the "Standards Compliance" section when
editing.
In `@prompts/plans/sdd_implementation_v1.md`:
- Line 3: The file sdd_implementation_v1.md contains a header "Version: 2.0.0"
which conflicts with the v1 filename; rename the file to match the declared
version (e.g., sdd_implementation_v2.md) or choose a version-agnostic name like
sdd_implementation.md, and update any references or links to
sdd_implementation_v1.md to the new name so tooling and users resolve the
correct document; ensure the "Version: 2.0.0" header remains accurate for the
chosen filename.
In `@prompts/plans/update_sdd_protocol/update_sdd_protocol.md`:
- Around line 36-47: The final deliverables list omits the updated AGENTS.md
referenced in Task 2.2; update the deliverables by adding "Updated
prompts/agents/AGENTS.md" (or the symbolic name AGENTS.md) to the Final
Deliverables section and ensure the plan's checklist/protocol explicitly
includes verifiable completion criteria for that artifact (e.g., update the
Verification block to include a simulation test or checklist entry that confirms
AGENTS.md points to the updated protocol version and pathing rules).
---
Outside diff comments:
In `@AGENTS.md`:
- Line 45: Update the backend naming in the AGENTS.md line that currently reads
"Serenity for Android is a media server client for Android (Plex/Emby)" so it
matches the project's governance: replace the parenthetical "(Plex/Emby)" with
"(Emby/Jellyfin)" or otherwise indicate Plex is deprecated; edit the sentence in
AGENTS.md (the "Serenity for Android..." line) to reflect Emby/Jellyfin as the
supported backends and remove the conflicting Plex reference.
---
Nitpick comments:
In `@prompts/agent_file_dir_tips.md`:
- Line 22: Replace the phrasing "keeps the user in control of destructive
operations and prevents 'ghost files' from breaking the build" with a more
concise alternative such as "gives the user control over destructive operations
and prevents 'ghost files' from breaking the build" (or "keeps the user in
control of destructive operations") in prompts/agent_file_dir_tips.md to improve
clarity while preserving meaning; update the exact sentence containing "keeps
the user in control of" to one of these shorter options.
In `@prompts/agents/SPEC_WRITER.md`:
- Line 9: In SPEC_WRITER.md, shorten the phrase in the "Pre-Drafting Standard
Review" step by replacing "ensure the proposed plan aligns with the project's
'Golden Standards'" with "ensure the plan aligns with the project's 'Golden
Standards'" to tighten wording while preserving intent; locate the step header
"Pre-Drafting Standard Review" and update the sentence accordingly.
In `@prompts/plans/sdd_implementation_v1.md`:
- Line 14: The prompt text currently hardcodes the filename
"prompts/plans/sdd_implementation_v1.md" (the string in the diff: "Using the
protocol in `prompts/plans/sdd_implementation_v1.md`, create a Phased GSD Spec
for [Task Description]"), which is brittle; update that prompt to reference a
generic identifier such as "the SDD protocol" or a stable relative reference
(e.g., "Using the SDD protocol in prompts/plans/SDD_PROTOCOL.md") so renames
won't break it; modify the string in the prompt generator or template where that
exact quoted text appears to use the new generic phrasing while preserving
surrounding structure.
- Line 28: Update the "Discovery Logging" instruction to explicitly document
memory file naming conventions: state that files live under
prompts/plans/<plan_name>/memory/, use a two-digit numbered prefix for ordering
(e.g., 01_dependency_discovery.md), follow with a concise descriptive slug,
prefer creating a new file for distinct discoveries or dependencies and append
to an existing file only for incremental notes about the same item, and include
examples and a brief rule for when to increment the number vs. reuse a file
name; reference the "Discovery Logging" line and the example filename
`01_dependency_discovery.md` to guide placement.
- Line 19: Update the "Impact Analysis" item in
prompts/plans/sdd_implementation_v1.md to include a concise definition and
examples of what to cover: list downstream consumers, affected
modules/components, API/contract changes, potential breaking changes, data
migrations, deployment windows, and recommended rollback/mitigation steps;
reference any existing internal docs or a template (if available) and point to
where teams should document dependency owners and estimated blast radius so the
collaborative interview always yields actionable impact and risk/rollback
information.
ℹ️ Review info
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (21)
AGENTS.mdprompts/agent_file_dir_tips.mdprompts/agents/COMMUNICATION.mdprompts/agents/FRAMEWORKS.mdprompts/agents/SPEC_WRITER.mdprompts/agents/TESTING.mdprompts/agents/TOOLING_CONSTRAINTS.mdprompts/agents/architecture.mdprompts/agents/communication-protocol.mdprompts/agents/constitution.mdprompts/agents/ui-standards.mdprompts/plans/context_discovery/.gitkeepprompts/plans/context_discovery/context_discovery.mdprompts/plans/context_discovery/memory/.gitkeepprompts/plans/context_discovery/memory/discovery_log.mdprompts/plans/protocol_integration/memory/.gitkeepprompts/plans/protocol_integration/protocol_integration.mdprompts/plans/sdd_implementation_v1.mdprompts/plans/update_sdd_protocol/memory/.gitkeepprompts/plans/update_sdd_protocol/update_sdd_protocol.mdprompts/templates/TASK_SPEC.md
| @@ -0,0 +1,56 @@ | |||
| # AI Agent Tooling & File System Tips | |||
|
|
|||
| This guide provides strategies for working with AI agents (like Android Studio Gemini) that have specialized toolsets but lacks direct terminal/shell access. Use these tips when writing Phased GSD Specs to ensure compatibility across different agent environments. | |||
There was a problem hiding this comment.
Fix subject-verb agreement.
The phrase "AI agents (like Android Studio Gemini) that have specialized toolsets but lacks" has inconsistent verb agreement. Since "AI agents" is plural but the parenthetical "(like Android Studio Gemini)" suggests a singular example, and "lacks" is singular, this creates confusion.
📝 Proposed fix
Option 1 (treat as plural):
-This guide provides strategies for working with AI agents (like Android Studio Gemini) that have specialized toolsets but lacks direct terminal/shell access.
+This guide provides strategies for working with AI agents (like Android Studio Gemini) that have specialized toolsets but lack direct terminal/shell access.Option 2 (rephrase for clarity):
-This guide provides strategies for working with AI agents (like Android Studio Gemini) that have specialized toolsets but lacks direct terminal/shell access.
+This guide provides strategies for working with AI agents (like Android Studio Gemini) that have specialized toolsets but lack direct terminal/shell access.📝 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.
| This guide provides strategies for working with AI agents (like Android Studio Gemini) that have specialized toolsets but lacks direct terminal/shell access. Use these tips when writing Phased GSD Specs to ensure compatibility across different agent environments. | |
| This guide provides strategies for working with AI agents (like Android Studio Gemini) that have specialized toolsets but lack direct terminal/shell access. Use these tips when writing Phased GSD Specs to ensure compatibility across different agent environments. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/agent_file_dir_tips.md` at line 3, The sentence "AI agents (like
Android Studio Gemini) that have specialized toolsets but lacks direct
terminal/shell access" has a subject-verb agreement error; change "lacks" to
"lack" if treating "AI agents" as plural, or rephrase to singular for clarity
(e.g., "an AI agent, such as Android Studio Gemini, that has specialized
toolsets but lacks direct terminal/shell access"); update the line in
prompts/agent_file_dir_tips.md so the noun and verb agree and the parenthetical
example reads clearly.
| - [ ] Task 5: Create/Update `prompts/agents/constitution.md` with the project philosophy. | ||
|
|
||
| ### Verification | ||
| - All files exist in `prompts/agents/` with "Mission," "Non-Negotiables," and "Code Examples" sections. |
There was a problem hiding this comment.
Phase 2 verification criterion is over-constrained and likely invalid.
Requiring all files to contain “Mission,” “Non-Negotiables,” and “Code Examples” doesn’t fit document intent (e.g., framework index vs constitution vs protocol), so completion can be marked failed for the wrong reason. Define per-file acceptance criteria instead.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/plans/context_discovery/context_discovery.md` at line 40, The Phase 2
verification rule that mandates "All files exist in `prompts/agents/` with
'Mission,' 'Non-Negotiables,' and 'Code Examples' sections" is too strict;
update context_discovery.md to replace this blanket requirement with per-file
acceptance criteria by enumerating expected document types (e.g., framework
index, constitution, protocol) and for each listing which sections are required
(for example: constitution -> Mission + Non-Negotiables, protocol -> Code
Examples + optional Mission, index -> metadata only). Locate the Phase 2
verification text in context_discovery.md and change the single "All files..."
sentence into a short table or bullets of per-file criteria, and adjust any
associated pass/fail logic language to validate against the per-file rules
rather than a universal checklist.
| ## Phase 3: Template Enhancement (TASK_SPEC) | ||
| ### Tasks | ||
| - [ ] Task 1: Update `prompts/templates/TASK_SPEC.md` to include a "Standards Compliance" block. | ||
| - [ ] Task 2: Define a checklist in the template for Architecture, UI, and Testing standards. | ||
|
|
||
| ### Verification | ||
| - New specs generated from the template will have a clear section for validating against project standards. | ||
| ### [WAIT FOR APPROVAL] |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
rg -n "Standards Compliance" prompts/templates/TASK_SPEC.mdRepository: NineWorlds/serenity-android
Length of output: 97
🏁 Script executed:
sed -n '10,20p' prompts/templates/TASK_SPEC.mdRepository: NineWorlds/serenity-android
Length of output: 566
🏁 Script executed:
sed -n '37,44p' prompts/plans/protocol_integration/protocol_integration.mdRepository: NineWorlds/serenity-android
Length of output: 466
Phase 3 specification is outdated: Standards Compliance section already exists in TASK_SPEC.md.
Lines 39-40 specify Task 1 to "Update prompts/templates/TASK_SPEC.md to include a 'Standards Compliance' block" and Task 2 to "Define a checklist in the template for Architecture, UI, and Testing standards." However, TASK_SPEC.md already contains a Standards Compliance section (line 10) with complete checklists for Architecture, UI/Leanback, Communication, and Testing. Either Phase 3 has already been executed, or this spec should be updated to reflect the current state and clarify the intent (e.g., whether these are verification steps rather than implementation tasks).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/plans/protocol_integration/protocol_integration.md` around lines 37 -
44, Phase 3 is outdated: the TASK_SPEC.md template already has a "Standards
Compliance" section and checklists, so update the Phase 3 block in
protocol_integration.md to reflect that (do not re-add the section).
Specifically, replace the two implementation tasks ("Update
prompts/templates/TASK_SPEC.md..." and "Define a checklist...") with
verification/validation steps that reference the existing Standards Compliance
block in prompts/templates/TASK_SPEC.md (e.g., "Verify TASK_SPEC.md contains
Standards Compliance with Architecture, UI/Leanback, Communication, and Testing
checklists" and "Ensure new specs generated from TASK_SPEC.md include those
checklist items"), and remove the [WAIT FOR APPROVAL] footnote or clarify it as
needed; reference TASK_SPEC.md and the "Standards Compliance" section when
editing.
| # Implementation Plan: Phased Spec-Driven Development (SDD) | ||
| **Status:** PROPOSED | ||
| **Version:** 1.6.2 | ||
| **Version:** 2.0.0 |
There was a problem hiding this comment.
File naming inconsistency with version number.
The file is named sdd_implementation_v1.md but the version is now 2.0.0. This creates confusion for users trying to locate the correct version of the documentation. Consider renaming the file to sdd_implementation_v2.md or using a version-agnostic name like sdd_implementation.md.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/plans/sdd_implementation_v1.md` at line 3, The file
sdd_implementation_v1.md contains a header "Version: 2.0.0" which conflicts with
the v1 filename; rename the file to match the declared version (e.g.,
sdd_implementation_v2.md) or choose a version-agnostic name like
sdd_implementation.md, and update any references or links to
sdd_implementation_v1.md to the new name so tooling and users resolve the
correct document; ensure the "Version: 2.0.0" header remains accurate for the
chosen filename.
| - [ ] **Task 2.2: Update `AGENTS.md`** | ||
| - Point to the updated protocol version and pathing rules. | ||
|
|
||
| ### Verification | ||
| - Simulation test: Ask the agent to "Prepare a plan for X" and verify it proposes a subdirectory structure. | ||
| ### [WAIT FOR APPROVAL] | ||
|
|
||
| ## Final Deliverables | ||
| - Updated `prompts/plans/sdd_implementation_v1.md` | ||
| - Updated `prompts/templates/TASK_SPEC.md` | ||
| - Updated `prompts/agents/SPEC_WRITER.md` | ||
|
|
There was a problem hiding this comment.
Final deliverables are missing a planned artifact.
Task 2.2 includes updating AGENTS.md, but AGENTS.md is absent from Final Deliverables. Add it to keep the plan auditable and phase-complete.
Based on learnings, the checklist/protocol expects explicit, verifiable completion criteria.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/plans/update_sdd_protocol/update_sdd_protocol.md` around lines 36 -
47, The final deliverables list omits the updated AGENTS.md referenced in Task
2.2; update the deliverables by adding "Updated prompts/agents/AGENTS.md" (or
the symbolic name AGENTS.md) to the Final Deliverables section and ensure the
plan's checklist/protocol explicitly includes verifiable completion criteria for
that artifact (e.g., update the Verification block to include a simulation test
or checklist entry that confirms AGENTS.md points to the updated protocol
version and pathing rules).
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #522 +/- ##
==========================================
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:
|
1 participant
Add a custom content_discovery prompt to review the project for existing architecture guidance that is not currently listed for the project.
Implement a memory system of what has been completed and when.
Summary by CodeRabbit
Release Notes
New Features
Documentation