docs: major constitution revision v2.0.0 (shift to AI agent development focus) #3606
Conversation
This adds a comprehensive set of slash commands for Claude Code to streamline development tasks including feature specification, planning, implementation, testing, and code management. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This adds a comprehensive toolkit for feature specification, planning, and implementation tracking with templates, scripts, and memory management for structured development workflows. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
…nt focus) Complete rewrite reflecting the true project focus: LangGraph-based multi-agent system for database design. ERD repositioned as stable production tool. Key changes: - Establishes agent-first architecture as core principle - Defines subgraph modularity as non-negotiable requirement - Adds state-safe workflow design and resilient execution patterns - Updates plan template with concrete constitutional compliance checklist - Clarifies development priority: agents over ERD enhancements 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds a spec-driven workflow via new command docs (.claude/commands/), Bash scripts for setup and validation (.specify/scripts/bash/), and templates (.specify/templates/*). Introduces a project constitution document, planning/specification/tasks/implementation/analyze/clarify workflows, and an agent context updater. No code exports changed; all additions are documentation and scripts. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant Specify as /specify
participant Plan as /plan
participant Tasks as /tasks
participant Implement as /implement
participant Analyze as /analyze
participant Clarify as /clarify
participant Const as /constitution
User->>Specify: Provide feature description (ARGUMENTS)
Specify->>Scripts: create-new-feature.sh (JSON)
Scripts-->>Specify: BRANCH_NAME, SPEC_FILE
User->>Clarify: Run clarification loop (if ambiguities)
Clarify-->>Specify: Updates FEATURE_SPEC (Clarifications section)
User->>Plan: Execute planning workflow
Plan->>Scripts: check-prerequisites.sh (paths)
Plan->>Templates: plan-template.md
Plan-->>User: plan.md, artifacts paths
User->>Tasks: Generate tasks.md
Tasks->>Templates: tasks-template.md
Tasks-->>User: tasks.md (T001, T002, ...)
User->>Implement: Execute by phases (TDD)
Implement-->>User: Status/report
User->>Analyze: Cross-artifact analysis
Analyze-->>User: Findings report (duplication, gaps)
User->>Const: Create/Update constitution
Const->>Memory: .specify/memory/constitution.md
Const-->>User: Sync Impact Report + summary
sequenceDiagram
autonumber
participant Caller as Any Command
participant Check as check-prerequisites.sh
participant Common as common.sh
Caller->>Check: --json [--require-tasks|--include-tasks|--paths-only]
Check->>Common: get_repo_root(), get_current_branch()
Common-->>Check: REPO_ROOT, CURRENT_BRANCH, HAS_GIT
Check->>Common: get_feature_paths()
Common-->>Check: FEATURE_DIR, FEATURE_SPEC, IMPL_PLAN, TASKS, AVAILABLE_DOCS
Check-->>Caller: JSON payload (paths + validations)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests
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 |
|
Updates to Preview Branch (spec-kit-2) ↗︎
Tasks are run on every commit but only new migration files are pushed.
View logs for this Workflow Run ↗︎. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.specify/templates/plan-template.md (1)
236-238: Constitution version mismatch with PR objectiveFooter says “Based on Constitution v2.1.1” while PR title states v2.0.0. Align the version or reference “current”.
-*Based on Constitution v2.1.1 - See `/memory/constitution.md`* +*Based on Constitution v2.0.0 - See `/memory/constitution.md`* +# Or: +# *Based on current Constitution - See `/memory/constitution.md`*
🧹 Nitpick comments (45)
.specify/templates/agent-file-template.md (1)
9-11: Specify a language for the fenced code blockLine 9 currently opens an untyped code fence, which triggers markdownlint MD040 and can break downstream tooling that expects a language hint. Please mark this snippet as plain text.
Based on static analysis.
-``` +```text [ACTUAL STRUCTURE FROM PLANS]</blockquote></details> <details> <summary>.specify/templates/spec-template.md (2)</summary><blockquote> `9-26`: **Add a language hint to the execution-flow fence** Line 9 starts a raw fenced block without a language tag, violating markdownlint MD040 and causing the same lint failure any time this template is rendered. Use `text` (or another appropriate identifier) to keep the fence lint-clean while preserving formatting. Based on static analysis. ```diff -``` +```text 1. Parse user description from Input → If empty: ERROR "No feature description provided" ... 8. Return: SUCCESS (spec ready for planning)--- `87-108`: **Convert emphasized pseudo-headings to plain text** Lines 88 and 106 rely on italicized sentences as headings, which trips markdownlint MD036 and can confuse renderers. Please restate them as regular text (bold works) to satisfy the rule while keeping emphasis. Based on static analysis. ```diff -## Review & Acceptance Checklist -*GATE: Automated checks run during main() execution* +## Review & Acceptance Checklist +**Gate:** Automated checks run during main() execution ... -## Execution Status -*Updated by main() during processing* +## Execution Status +**Updated by main() during processing**.specify/scripts/bash/create-new-feature.sh (2)
3-3: Harden script failure modesConsider adding set -u and pipefail for stricter error handling.
-set -e +set -euo pipefail
74-78: Optional: Avoid failing when branch already existsGracefully switch if the branch exists.
-if [ "$HAS_GIT" = true ]; then - git checkout -b "$BRANCH_NAME" +if [ "$HAS_GIT" = true ]; then + if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then + git checkout "$BRANCH_NAME" + else + git checkout -b "$BRANCH_NAME" + fi.specify/templates/tasks-template.md (5)
6-34: Add fenced code languages for markdownlint (MD040)Label code fences to pass linting.
-``` +```text ... -``` +```
50-56: Use a heading instead of emphasis (MD036)Replace emphasized line with a proper heading.
-**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation** +### Critical: Write tests first, they MUST fail before implementation
86-93: Add fenced code languages for markdownlint (MD040)Label the Parallel Example code block.
-``` +```text ... -``` +```
101-101: Use a heading instead of emphasis (MD036)Promote the “Applied during main() execution” note to a heading.
-*Applied during main() execution* +### Applied during main() execution
120-120: Use a heading instead of emphasis (MD036)Promote the “GATE” note to a heading.
-*GATE: Checked by main() before returning* +### Gate: Checked by main() before returning.specify/scripts/bash/check-prerequisites.sh (2)
22-22: Harden script failure modesAdd -u and pipefail.
-set -e +set -euo pipefail
141-151: Robust JSON array assemblyCurrent printf join is fine since values are fixed, but a safer pattern avoids trailing commas without relying on slice.
- if [[ ${#docs[@]} -eq 0 ]]; then - json_docs="[]" - else - json_docs=$(printf '"%s",' "${docs[@]}") - json_docs="[${json_docs%,}]" - fi + json_docs="[]" + if [[ ${#docs[@]} -gt 0 ]]; then + sep="" + json_docs="[" + for d in "${docs[@]}"; do + json_docs="${json_docs}${sep}\"${d}\"" + sep="," + done + json_docs="${json_docs}]" + fi.specify/templates/plan-template.md (9)
7-27: Add fenced code language (MD040)Label the flow block to satisfy markdownlint.
-``` +```text ... -``` +```
73-81: Add fenced code language (MD040)Label the directory tree block.
-``` +```text ... -``` +```
90-124: Add fenced code language (MD040)Label the options tree block.
-``` +```text ... -``` +```
136-142: Add fenced code language (MD040)Label the code block under Phase 0.
- ``` + ```text For each unknown in Technical Context: Task: "Research {unknown} for {feature context}" For each technology choice: Task: "Find best practices for {tech} in {domain}" - ``` + ```
151-151: Use a heading instead of emphasis (MD036)Promote the note to a heading.
-*Prerequisites: research.md complete* +### Prerequisites: research.md complete
184-201: Use headings instead of emphasis (MD036)Promote the section notes to headings.
-*This section describes what the /tasks command will do - DO NOT execute during /plan* +### Scope note +This section describes what the /tasks command will do - DO NOT execute during /plan
204-209: Use headings instead of emphasis (MD036)Promote out-of-scope notice to headings for lint compliance.
-*These phases are beyond the scope of the /plan command* +### Out of scope +These phases are beyond the scope of the /plan command
211-217: Use headings instead of emphasis (MD036)Promote the note to a heading.
-*Fill ONLY if Constitution Check has violations that must be justified* +### When to fill +Fill ONLY if Constitution Check has violations that must be justified
220-229: Use headings instead of emphasis (MD036)Promote the note to a heading.
-*This checklist is updated during execution flow* +### Update cadence +This checklist is updated during execution flow.specify/scripts/bash/update-agent-context.sh (4)
299-303: Avoid declare-and-assign with command substitution (SC2155)Split declaration from assignment to avoid masking return values.
- local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g') - local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g') - local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g') + local escaped_lang + escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g') + local escaped_framework + escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g') + local escaped_branch + escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
371-378: Avoid declare-and-assign with command substitution (SC2155)Split tech_stack computation.
- local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK") + local tech_stack + tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
431-432: Remove unused variable (SC2034)changes_entries_added is set but never used.
- local changes_entries_added=false + # removed unused changes_entries_added
41-46: Redundant set -e before set -u/pipefailYou already set -e at line 41; the next block can be consolidated.
-set -e - -# Enable strict error handling -set -u -set -o pipefail +# Enable strict error handling +set -euo pipefail.specify/scripts/bash/common.sh (5)
10-12: Avoid declare-and-assign with command substitution (SC2155)Split declaration/assignment.
- local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - (cd "$script_dir/../../.." && pwd) + local script_dir + script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + (cd "$script_dir/../../.." && pwd)
30-33: Avoid declare-and-assign with command substitution (SC2155)Split repo_root.
- local repo_root=$(get_repo_root) + local repo_root + repo_root=$(get_repo_root)
39-43: Avoid declare-and-assign with command substitution (SC2155)Split number assignment; also guard empty.
- if [[ "$dirname" =~ ^([0-9]{3})- ]]; then - local number=${BASH_REMATCH[1]} - number=$((10#$number)) + if [[ "$dirname" =~ ^([0-9]{3})- ]]; then + local number + number=${BASH_REMATCH[1]} + number=$((10#$number))
87-96: Avoid declare-and-assign with command substitution (SC2155) and quote eval callersSplit locals for readability; get_feature_paths callers should eval with quotes (fix in callers already suggested).
- local repo_root=$(get_repo_root) - local current_branch=$(get_current_branch) + local repo_root + repo_root=$(get_repo_root) + local current_branch + current_branch=$(get_current_branch) local has_git_repo="false" @@ - local feature_dir=$(get_feature_dir "$repo_root" "$current_branch") + local feature_dir + feature_dir=$(get_feature_dir "$repo_root" "$current_branch")
113-113: Robust non-empty dir checkAvoid parsing ls; use find for empty dir detection.
-check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo " ✓ $2" || echo " ✗ $2"; } +check_dir() { [[ -d "$1" && -n "$(find "$1" -mindepth 1 -print -quit 2>/dev/null)" ]] && echo " ✓ $2" || echo " ✗ $2"; }.claude/commands/analyze.md (4)
26-29: Be robust to heading variance across teamsSpecs/plans often vary heading names. Add a fallback to semantic matching when canonical headings aren’t present to avoid false “missing section” errors.
Apply:
-2. Load artifacts: - - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present). - - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints. +2. Load artifacts: + - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present). + - If headings differ (e.g., “Objectives” vs “Overview”, “NFRs” vs “Non-Functional Requirements”), fall back to semantic matching on content. + - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints.
66-73: Add deterministic ID scheme to avoid churn across runsStable IDs prevent noisy diffs when rows reorder. Encode a short hash in the ID.
Apply:
6. Produce a Markdown report (no file writes) with sections: @@ - | ID | Category | Severity | Location(s) | Summary | Recommendation | + | ID | Category | Severity | Location(s) | Summary | Recommendation | @@ - (Add one row per finding; generate stable IDs prefixed by category initial.) + (Add one row per finding; generate stable IDs prefixed by category initial.) + ID format: <CategoryPrefix>-<kebab-slug>-<sha1-8> computed from normalized finding summary for determinism.
94-99: Clarify determinism guarantees and overflow handlingSpell out overflow behavior to keep output predictable and re-runnable.
Apply:
- - KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts. - - LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note. + - KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts. + - LIMIT total findings in the main table to 50; overflow items are grouped by category with counts and top 3 examples per category.
101-102: Surface user arguments earlier in reportEchoing context at the end can be missed. Recommend adding an “Inputs” preface in the report header.
Proposed addition near the report header:
+At the top of the report, include: + +Inputs +- User Arguments: $ARGUMENTS (verbatim).claude/commands/plan.md (3)
13-15: Define the explicit override mechanism for missing clarificationsDocument how users express “proceed without clarification” to avoid ambiguity in automation.
Apply:
- - BEFORE proceeding, inspect FEATURE_SPEC for a `## Clarifications` section with at least one `Session` subheading. If missing or clearly ambiguous areas remain (vague adjectives, unresolved critical choices), PAUSE and instruct the user to run `/clarify` first to reduce rework. Only continue if: (a) Clarifications exist OR (b) an explicit user override is provided (e.g., "proceed without clarification"). Do not attempt to fabricate clarifications yourself. + - BEFORE proceeding, inspect FEATURE_SPEC for a `## Clarifications` section with at least one `Session` subheading. If missing or clearly ambiguous areas remain (vague adjectives, unresolved critical choices), PAUSE and instruct the user to run `/clarify` first to reduce rework. Only continue if: (a) Clarifications exist OR (b) an explicit user override is provided via $ARGUMENTS (e.g., `--override proceed_without_clarification=true`). Do not attempt to fabricate clarifications yourself.
36-39: Validate artifacts are non-empty and minimally structuredArtifacts being present but empty degrades downstream flows. Add simple content checks.
Apply:
5. Verify execution completed: - Check Progress Tracking shows all phases complete - - Ensure all required artifacts were generated + - Ensure all required artifacts were generated and non-empty (≥ 10 lines) with required headings: + * research.md: “Background”, “Decisions” + * data-model.md: “Entities”, “Relationships” + * tasks.md: “Phases”, task checklist items - Confirm no ERROR states in execution
41-44: Absolute paths: include symlink resolution to avoid duplicatesRecommend realpath-style normalization to prevent path mismatches across environments.
Add: “Normalize all absolute paths by resolving symlinks before use.”
.claude/commands/implement.md (3)
27-33: Parallelism guardrails: clarify file-level exclusivityYou note “file-based coordination,” but specify a concrete rule to avoid concurrent writes to the same file.
Apply:
- - **File-based coordination**: Tasks affecting the same files must run sequentially + - **File-based coordination**: Tasks affecting the same files must run sequentially; enforce single-writer per file by grouping tasks by path and serializing each group.
41-48: Marking tasks done: use atomic writes to prevent corruptionWhen editing tasks.md, write to a temp file and rename to avoid partial writes.
Apply:
- - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file. + - **IMPORTANT** For completed tasks, mark the task off as [X] in tasks.md using an atomic write (write to a temp file, fsync, then rename) to prevent corruption during concurrent operations.
49-56: Add completion SLOs and a dry-run modeHelpful in CI and long-running implementations: allow validation without writes.
Add:
- “Support a --dry-run mode: parse, plan, and report without writing or executing tasks.”
- “Emit timing metrics per phase and overall elapsed time.”
.specify/memory/constitution.md (5)
41-47: Clarify retry policy layering to avoid double-retries“No retry policies on subgraph nodes” can be misread. Make it explicit that retries live inside subgraphs only.
Apply:
- Subgraph integration via `graph.addNode("agentName", subgraph)` -- No retry policies on subgraph nodes (handled internally) +- Configure retries within each subgraph node internally; do not layer external retries on the same node at the orchestration level to avoid duplication.
55-59: Avoid blanket “No intermediate state storage” which conflicts with error traceabilityRefine to allow minimal structured traces and error context retention.
Apply:
- - No intermediate state storage for AI responses (memory optimization) + - Avoid unnecessary long-term storage of raw AI responses; retain minimal structured traces and error context required for debugging and audit.
75-80: Decouple performance targets from specific model brandingTie SLOs to measurable targets and keep model IDs configurable.
Apply:
-- Sub-second agent routing decisions (GPT-5-nano) +- Router SLO: p95 routing decision latency ≤ 1s (model configurable; e.g., small “router” model)
83-89: Model naming: avoid hard-coding future/brand-specific modelsUse configurable identifiers to prevent vendor lock and future drift.
Apply:
-- **AI Models**: GPT-5 for complex reasoning, GPT-5-nano for routing +- **AI Models**: Default large reasoning model and small router model; model IDs are configurable via environment (e.g., LIAM_MODEL_REASONING, LIAM_MODEL_ROUTER)
29-33: Define concrete backoff parameters with jitter“Exponential backoff” needs parameters for interoperability.
Apply:
- Maximum 3 retry attempts per node with exponential backoff. Graceful fallback mechanisms required for all critical paths. + Maximum 3 retry attempts per node with exponential backoff and jitter (e.g., base 200ms, factor 2, full jitter, capped at 2s). Graceful fallback mechanisms required for all critical paths.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (17)
.claude/commands/analyze.md(1 hunks).claude/commands/clarify.md(1 hunks).claude/commands/constitution.md(1 hunks).claude/commands/implement.md(1 hunks).claude/commands/plan.md(1 hunks).claude/commands/specify.md(1 hunks).claude/commands/tasks.md(1 hunks).specify/memory/constitution.md(1 hunks).specify/scripts/bash/check-prerequisites.sh(1 hunks).specify/scripts/bash/common.sh(1 hunks).specify/scripts/bash/create-new-feature.sh(1 hunks).specify/scripts/bash/setup-plan.sh(1 hunks).specify/scripts/bash/update-agent-context.sh(1 hunks).specify/templates/agent-file-template.md(1 hunks).specify/templates/plan-template.md(1 hunks).specify/templates/spec-template.md(1 hunks).specify/templates/tasks-template.md(1 hunks)
🧰 Additional context used
🧬 Code graph analysis (3)
.specify/scripts/bash/setup-plan.sh (1)
.specify/scripts/bash/common.sh (2)
get_feature_paths(86-110)check_feature_branch(65-82)
.specify/scripts/bash/update-agent-context.sh (1)
.specify/scripts/bash/common.sh (1)
get_feature_paths(86-110)
.specify/scripts/bash/check-prerequisites.sh (1)
.specify/scripts/bash/common.sh (4)
get_feature_paths(86-110)check_feature_branch(65-82)check_file(112-112)check_dir(113-113)
🪛 Shellcheck (0.11.0)
.specify/scripts/bash/common.sh
[warning] 10-10: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 30-30: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 39-39: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 87-87: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 88-88: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 95-95: Declare and assign separately to avoid masking return values.
(SC2155)
.specify/scripts/bash/setup-plan.sh
[warning] 31-31: Quote this to prevent word splitting.
(SC2046)
.specify/scripts/bash/update-agent-context.sh
[warning] 56-56: Quote this to prevent word splitting.
(SC2046)
[warning] 299-299: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 300-300: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 301-301: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 371-371: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 431-431: changes_entries_added appears unused. Verify use (or export if used externally).
(SC2034)
.specify/scripts/bash/check-prerequisites.sh
[warning] 82-82: Quote this to prevent word splitting.
(SC2046)
🪛 markdownlint-cli2 (0.18.1)
.specify/templates/agent-file-template.md
9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
.specify/templates/tasks-template.md
7-7: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
51-51: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
86-86: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
101-101: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
120-120: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
.specify/templates/plan-template.md
8-8: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
73-73: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
90-90: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
136-136: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
151-151: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
184-184: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
204-204: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
211-211: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
220-220: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
.specify/templates/spec-template.md
9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
88-88: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
106-106: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Supabase Preview
- GitHub Check: security-review
🔇 Additional comments (5)
.claude/commands/specify.md (1)
15-21: LGTM: Clear single-source-of-truth flowThe command correctly delegates branch/spec creation to the script and preserves absolute paths. No changes needed.
.claude/commands/tasks.md (1)
1-63: LGTM: Clear, template-driven generation flowThe steps align with prerequisites and template use; paths are absolute and artifact-conditional. No changes needed.
.claude/commands/clarify.md (1)
24-75: Thorough coverage taxonomyThe expanded ambiguity taxonomy gives the clarifier a precise, prioritized checklist, which should materially improve the quality of follow-up questions and updates.
.claude/commands/plan.md (1)
21-23: Reference valid:.specify/memory/constitution.mdexists and is at version 2.0.0..claude/commands/analyze.md (1)
19-23: No issues with preflight script contract
.specify/scripts/bash/check-prerequisites.shsupports--json,--require-tasks, and--include-tasks, and emits bothFEATURE_DIRandAVAILABLE_DOCSin its JSON output.
| - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required. | ||
| - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed. |
There was a problem hiding this comment.
Fix incorrect command directory reference
Step 4 tells the operator to read .specify/templates/commands/*.md, but those command docs actually live in .claude/commands/*.md per this PR. The current path doesn’t exist, so anyone following the workflow will fail the propagation check. Please point the checklist at the real command directory.
- - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+ - Read each command file in `.claude/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.📝 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.
| - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required. | |
| - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed. | |
| - Read each command file in `.claude/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required. | |
| - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed. |
🤖 Prompt for AI Agents
In .claude/commands/constitution.md around lines 39 to 40, the checklist
references the wrong command directory `.specify/templates/commands/*.md`;
update that path to the actual location `.claude/commands/*.md` (and ensure the
parenthetical note “including this one” still applies) so the propagation check
points to existing command docs.
| ### LangGraph Implementation | ||
| - Use `StateGraphBuilder` with typed annotations for all workflows | ||
| - Implement conditional routing with Command pattern for explicit control flow | ||
| - Subgraph integration via `graph.addNode("agentName", subgraph)` | ||
| - No retry policies on subgraph nodes (handled internally) |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
🧩 Analysis chain
LangGraph API names: verify StateGraphBuilder and graph.addNode match actual TS API
API drift could cause confusion; adjust terminology to the concrete API names used by LangGraph TS.
🌐 Web query:
Does the LangGraph TypeScript API expose a `StateGraphBuilder` and an `addNode` method on a `graph` instance? Provide the official references.
💡 Result:
Short answer: Yes.
- The TypeScript API exposes the StateGraph class (used as the graph/builder) and it provides an addNode method. See the LangChain docs showing StateGraph usage and .addNode examples. [1]
- The official API reference documents the StateGraph class and lists addNode among its methods. [2]
References:
[1] LangChain LangGraph docs — "Use the graph API" (shows StateGraph and .addNode usage).
[2] LangGraph TypeScript API reference — StateGraph class (methods include addNode).
Replace StateGraphBuilder with StateGraph
The TypeScript API uses StateGraph (not StateGraphBuilder); update the docs in .specify/memory/constitution.md (lines 41–45).
🤖 Prompt for AI Agents
.specify/memory/constitution.md around lines 41 to 45: the docs mention and show
`StateGraphBuilder` but the TypeScript API uses `StateGraph`; update the text
and any example snippets in this block to use `StateGraph` instead of
`StateGraphBuilder`, preserve the note about typed annotations for workflows and
conditional routing, and ensure the subgraph integration line remains accurate
(e.g., `graph.addNode("agentName", subgraph)`) while removing or replacing any
references to `StateGraphBuilder`.
| ## Governance | ||
|
|
||
| All agent implementations must demonstrate domain expertise and reliable execution patterns. Workflow changes require validation of end-to-end scenarios. No agent modifications without corresponding test updates. | ||
|
|
||
| Agent development takes priority over ERD enhancements - ERD is a stable, production tool while agents are pre-release and require focused development effort. | ||
|
|
||
| Constitution violations in agent logic block all releases. Multi-agent system reliability is non-negotiable due to the complexity of database design workflows. | ||
|
|
||
| Pull requests must include agent integration testing and workflow validation scenarios. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add Security, Privacy, and Observability governance
The constitution should mandate PII handling, secrets, RBAC, and telemetry to support production use.
Apply:
## Governance
@@
Pull requests must include agent integration testing and workflow validation scenarios.
+
+### Security & Privacy (NON-NEGOTIABLE)
+- Secrets management via vault or environment injection; no secrets in code or logs.
+- PII handling: classify data, redact logs, and enforce least privilege RBAC.
+- Data retention: define and enforce retention windows for intermediate artifacts.
+- Supply chain: pin dependencies and monitor advisories; rotate API keys regularly.
+
+### Observability
+- Emit structured logs, traces, and metrics (per-node latency, retries, failures).
+- Expose SLOs (availability, p95 latencies) and alerting thresholds.
+- Persist minimal execution traces to support audit and reproducibility.📝 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.
| ## Governance | |
| All agent implementations must demonstrate domain expertise and reliable execution patterns. Workflow changes require validation of end-to-end scenarios. No agent modifications without corresponding test updates. | |
| Agent development takes priority over ERD enhancements - ERD is a stable, production tool while agents are pre-release and require focused development effort. | |
| Constitution violations in agent logic block all releases. Multi-agent system reliability is non-negotiable due to the complexity of database design workflows. | |
| Pull requests must include agent integration testing and workflow validation scenarios. | |
| ## Governance | |
| All agent implementations must demonstrate domain expertise and reliable execution patterns. Workflow changes require validation of end-to-end scenarios. No agent modifications without corresponding test updates. | |
| Agent development takes priority over ERD enhancements - ERD is a stable, production tool while agents are pre-release and require focused development effort. | |
| Constitution violations in agent logic block all releases. Multi-agent system reliability is non-negotiable due to the complexity of database design workflows. | |
| Pull requests must include agent integration testing and workflow validation scenarios. | |
| ### Security & Privacy (NON-NEGOTIABLE) | |
| - Secrets management via vault or environment injection; no secrets in code or logs. | |
| - PII handling: classify data, redact logs, and enforce least privilege RBAC. | |
| - Data retention: define and enforce retention windows for intermediate artifacts. | |
| - Supply chain: pin dependencies and monitor advisories; rotate API keys regularly. | |
| ### Observability | |
| - Emit structured logs, traces, and metrics (per-node latency, retries, failures). | |
| - Expose SLOs (availability, p95 latencies) and alerting thresholds. | |
| - Persist minimal execution traces to support audit and reproducibility. |
🤖 Prompt for AI Agents
In .specify/memory/constitution.md around lines 95 to 104, add a Governance
subsection that mandates Security, Privacy, and Observability: define PII
handling rules (classification, minimization, retention, encryption at rest/in
transit, redaction in logs), secrets management (no hardcoded secrets, use
vaults/secret stores, rotation policy), RBAC requirements (least-privilege
roles, approval process for new agent permissions, audit trails), and
telemetry/observability expectations (structured logs, scrubbed PII,
metrics/alerting, distributed tracing and retention/retention policy). For each
item include required owner(s), compliance checks/tests to run during PRs, and a
short enforcement statement that violations block release until remediation and
tests are added.
| eval $(get_feature_paths) | ||
| check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1 |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Quote command substitution in eval (SC2046)
Prevents word splitting.
-eval $(get_feature_paths)
+eval "$(get_feature_paths)"📝 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.
| eval $(get_feature_paths) | |
| check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1 | |
| # .specify/scripts/bash/check-prerequisites.sh | |
| eval "$(get_feature_paths)" | |
| check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1 |
🧰 Tools
🪛 Shellcheck (0.11.0)
[warning] 82-82: Quote this to prevent word splitting.
(SC2046)
🤖 Prompt for AI Agents
.specify/scripts/bash/check-prerequisites.sh around lines 82 to 83: the eval
uses unquoted command substitution which can cause word splitting; change the
call to use quoted command substitution—replace eval $(get_feature_paths) with
eval "$(get_feature_paths)" so the output is treated as a single string and
prevents word splitting.
| BRANCH_NAME=$(echo "$FEATURE_DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//') | ||
| WORDS=$(echo "$BRANCH_NAME" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//') | ||
| BRANCH_NAME="${FEATURE_NUM}-${WORDS}" | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Guard against empty slug from non-alphanumerics
If the sanitized slug becomes empty (e.g., input like "!!!"), BRANCH_NAME ends with a trailing dash. Add a fallback.
BRANCH_NAME=$(echo "$FEATURE_DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
WORDS=$(echo "$BRANCH_NAME" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//')
-BRANCH_NAME="${FEATURE_NUM}-${WORDS}"
+if [ -z "$WORDS" ]; then
+ WORDS="feature"
+fi
+BRANCH_NAME="${FEATURE_NUM}-${WORDS}"🤖 Prompt for AI Agents
In .specify/scripts/bash/create-new-feature.sh around lines 70-73, the sanitized
slug can be empty for inputs like "!!!", causing BRANCH_NAME to end with a
trailing dash; fix by checking if WORDS is empty after the sanitization pipeline
and if so assign a safe fallback (e.g., "untitled" or a sanitized
FEATURE_NUM-based token), then build BRANCH_NAME="${FEATURE_NUM}-${WORDS}";
ensure you also strip any leading/trailing dashes from the final BRANCH_NAME as
a last step so no trailing dash remains.
| source "$SCRIPT_DIR/common.sh" | ||
|
|
||
| # Get all paths and variables from common functions | ||
| eval $(get_feature_paths) |
There was a problem hiding this comment.
Quote the eval to avoid word splitting failures
eval $(get_feature_paths) (Line 31) will break when any returned value contains spaces—eval sees multiple tokens and the variable assignment fails. Wrap the command substitution in quotes so Bash treats the payload as one string.
-eval $(get_feature_paths)
+eval "$(get_feature_paths)"📝 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.
| eval $(get_feature_paths) | |
| eval "$(get_feature_paths)" |
🧰 Tools
🪛 Shellcheck (0.11.0)
[warning] 31-31: Quote this to prevent word splitting.
(SC2046)
🤖 Prompt for AI Agents
In .specify/scripts/bash/setup-plan.sh around line 31, the call eval
$(get_feature_paths) can fail when get_feature_paths outputs tokens containing
spaces; wrap the command substitution in double quotes so the entire output is
treated as a single string by eval (i.e., replace with eval
"$(get_feature_paths)"), ensuring the variable assignments produced by the
subshell are preserved even when values contain spaces.
| eval $(get_feature_paths) | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Quote command substitution in eval (SC2046)
Prevents word splitting.
-eval $(get_feature_paths)
+eval "$(get_feature_paths)"📝 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.
| eval $(get_feature_paths) | |
| eval "$(get_feature_paths)" |
🧰 Tools
🪛 Shellcheck (0.11.0)
[warning] 56-56: Quote this to prevent word splitting.
(SC2046)
🤖 Prompt for AI Agents
In .specify/scripts/bash/update-agent-context.sh around lines 56-57, the eval
uses unquoted command substitution which can cause word splitting; update it to
quote the substitution (use eval "$(get_feature_paths)") so the output is
treated as a single string and tokens with spaces are preserved; if
get_feature_paths can emit multiple commands or contains arbitrary whitespace,
ensure it properly escapes or consider returning an array or writing to a
temporary file and sourcing that file instead.
Issue
Why is this change needed?
This change implements a structured development workflow based on GitHub's spec-kit framework to support systematic feature development for our LangGraph-based multi-agent system.
Key implementations using spec-kit:
/specify,/clarify,/plan,/tasks,/implement,/analyze,/constitution) following spec-kit patterns for feature lifecycle management.specify/scripts/bash/for:check-prerequisites.sh- Validates feature branch and artifact requirementscreate-new-feature.sh- Initializes new feature branches with spec filessetup-plan.sh- Prepares planning environment and artifact directoriesspec-template.md)plan-template.md)tasks-template.md)The spec-kit framework provides the structured foundation needed for developing specialized autonomous agents with clear responsibilities, state-safe workflows, and systematic feature delivery processes.