detached c1e4d71

Initial commit from Specify template

commit
c1e4d71302d6d380e39d53491e2d58ab9da44aac
author
bamen · · 2025-09-09 04:55 UTC
parent
none (root commit)
signature
unsigned
15 files · +1283 -0
Unified
UnifiedSplit
A .claude/commands/plan.md +37 -0
@@ -0,0 +1,37 @@
1+
2+Plan how to implement the specified feature.
3+
4+This is the second step in the Spec-Driven Development lifecycle.
5+
6+Given the implementation details provided as an argument, do this:
7+
8+1. Run `scripts/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
9+2. Read and analyze the feature specification to understand:
10+ - The feature requirements and user stories
11+ - Functional and non-functional requirements
12+ - Success criteria and acceptance criteria
13+ - Any technical constraints or dependencies mentioned
14+
15+3. Read the constitution at `/memory/constitution.md` to understand constitutional requirements.
16+
17+4. Execute the implementation plan template:
18+ - Load `/templates/plan-template.md` (already copied to IMPL_PLAN path)
19+ - Set Input path to FEATURE_SPEC
20+ - Run the Execution Flow (main) function steps 1-10
21+ - The template is self-contained and executable
22+ - Follow error handling and gate checks as specified
23+ - Let the template guide artifact generation in $SPECS_DIR:
24+ * Phase 0 generates research.md
25+ * Phase 1 generates data-model.md, contracts/, quickstart.md
26+ * Phase 2 generates tasks.md
27+ - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
28+ - Update Progress Tracking as you complete each phase
29+
30+5. Verify execution completed:
31+ - Check Progress Tracking shows all phases complete
32+ - Ensure all required artifacts were generated
33+ - Confirm no ERROR states in execution
34+
35+6. Report results with branch name, file paths, and generated artifacts.
36+
37+Use absolute paths with the repository root for all file operations to avoid path issues.
@@ -0,0 +1,37 @@
1+
2+Plan how to implement the specified feature.
3+
4+This is the second step in the Spec-Driven Development lifecycle.
5+
6+Given the implementation details provided as an argument, do this:
7+
8+1. Run `scripts/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
9+2. Read and analyze the feature specification to understand:
10+ - The feature requirements and user stories
11+ - Functional and non-functional requirements
12+ - Success criteria and acceptance criteria
13+ - Any technical constraints or dependencies mentioned
14+
15+3. Read the constitution at `/memory/constitution.md` to understand constitutional requirements.
16+
17+4. Execute the implementation plan template:
18+ - Load `/templates/plan-template.md` (already copied to IMPL_PLAN path)
19+ - Set Input path to FEATURE_SPEC
20+ - Run the Execution Flow (main) function steps 1-10
21+ - The template is self-contained and executable
22+ - Follow error handling and gate checks as specified
23+ - Let the template guide artifact generation in $SPECS_DIR:
24+ * Phase 0 generates research.md
25+ * Phase 1 generates data-model.md, contracts/, quickstart.md
26+ * Phase 2 generates tasks.md
27+ - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
28+ - Update Progress Tracking as you complete each phase
29+
30+5. Verify execution completed:
31+ - Check Progress Tracking shows all phases complete
32+ - Ensure all required artifacts were generated
33+ - Confirm no ERROR states in execution
34+
35+6. Report results with branch name, file paths, and generated artifacts.
36+
37+Use absolute paths with the repository root for all file operations to avoid path issues.
A .claude/commands/specify.md +13 -0
@@ -0,0 +1,13 @@
1+
2+Start a new feature by creating a specification and feature branch.
3+
4+This is the first step in the Spec-Driven Development lifecycle.
5+
6+Given the feature description provided as an argument, do this:
7+
8+1. Run the script `scripts/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
9+2. Load `templates/spec-template.md` to understand required sections.
10+3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
11+4. Report completion with branch name, spec file path, and readiness for the next phase.
12+
13+Note: The script creates and checks out the new branch and initializes the spec file before writing.
@@ -0,0 +1,13 @@
1+
2+Start a new feature by creating a specification and feature branch.
3+
4+This is the first step in the Spec-Driven Development lifecycle.
5+
6+Given the feature description provided as an argument, do this:
7+
8+1. Run the script `scripts/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
9+2. Load `templates/spec-template.md` to understand required sections.
10+3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
11+4. Report completion with branch name, spec file path, and readiness for the next phase.
12+
13+Note: The script creates and checks out the new branch and initializes the spec file before writing.
A .claude/commands/tasks.md +59 -0
@@ -0,0 +1,59 @@
1+
2+Break down the plan into executable tasks.
3+
4+This is the third step in the Spec-Driven Development lifecycle.
5+
6+Given the context provided as an argument, do this:
7+
8+1. Run `scripts/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
9+2. Load and analyze available design documents:
10+ - Always read plan.md for tech stack and libraries
11+ - IF EXISTS: Read data-model.md for entities
12+ - IF EXISTS: Read contracts/ for API endpoints
13+ - IF EXISTS: Read research.md for technical decisions
14+ - IF EXISTS: Read quickstart.md for test scenarios
15+
16+ Note: Not all projects have all documents. For example:
17+ - CLI tools might not have contracts/
18+ - Simple libraries might not need data-model.md
19+ - Generate tasks based on what's available
20+
21+3. Generate tasks following the template:
22+ - Use `/templates/tasks-template.md` as the base
23+ - Replace example tasks with actual tasks based on:
24+ * **Setup tasks**: Project init, dependencies, linting
25+ * **Test tasks [P]**: One per contract, one per integration scenario
26+ * **Core tasks**: One per entity, service, CLI command, endpoint
27+ * **Integration tasks**: DB connections, middleware, logging
28+ * **Polish tasks [P]**: Unit tests, performance, docs
29+
30+4. Task generation rules:
31+ - Each contract file → contract test task marked [P]
32+ - Each entity in data-model → model creation task marked [P]
33+ - Each endpoint → implementation task (not parallel if shared files)
34+ - Each user story → integration test marked [P]
35+ - Different files = can be parallel [P]
36+ - Same file = sequential (no [P])
37+
38+5. Order tasks by dependencies:
39+ - Setup before everything
40+ - Tests before implementation (TDD)
41+ - Models before services
42+ - Services before endpoints
43+ - Core before integration
44+ - Everything before polish
45+
46+6. Include parallel execution examples:
47+ - Group [P] tasks that can run together
48+ - Show actual Task agent commands
49+
50+7. Create FEATURE_DIR/tasks.md with:
51+ - Correct feature name from implementation plan
52+ - Numbered tasks (T001, T002, etc.)
53+ - Clear file paths for each task
54+ - Dependency notes
55+ - Parallel execution guidance
56+
57+Context for task generation: $ARGUMENTS
58+
59+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
@@ -0,0 +1,59 @@
1+
2+Break down the plan into executable tasks.
3+
4+This is the third step in the Spec-Driven Development lifecycle.
5+
6+Given the context provided as an argument, do this:
7+
8+1. Run `scripts/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
9+2. Load and analyze available design documents:
10+ - Always read plan.md for tech stack and libraries
11+ - IF EXISTS: Read data-model.md for entities
12+ - IF EXISTS: Read contracts/ for API endpoints
13+ - IF EXISTS: Read research.md for technical decisions
14+ - IF EXISTS: Read quickstart.md for test scenarios
15+
16+ Note: Not all projects have all documents. For example:
17+ - CLI tools might not have contracts/
18+ - Simple libraries might not need data-model.md
19+ - Generate tasks based on what's available
20+
21+3. Generate tasks following the template:
22+ - Use `/templates/tasks-template.md` as the base
23+ - Replace example tasks with actual tasks based on:
24+ * **Setup tasks**: Project init, dependencies, linting
25+ * **Test tasks [P]**: One per contract, one per integration scenario
26+ * **Core tasks**: One per entity, service, CLI command, endpoint
27+ * **Integration tasks**: DB connections, middleware, logging
28+ * **Polish tasks [P]**: Unit tests, performance, docs
29+
30+4. Task generation rules:
31+ - Each contract file → contract test task marked [P]
32+ - Each entity in data-model → model creation task marked [P]
33+ - Each endpoint → implementation task (not parallel if shared files)
34+ - Each user story → integration test marked [P]
35+ - Different files = can be parallel [P]
36+ - Same file = sequential (no [P])
37+
38+5. Order tasks by dependencies:
39+ - Setup before everything
40+ - Tests before implementation (TDD)
41+ - Models before services
42+ - Services before endpoints
43+ - Core before integration
44+ - Everything before polish
45+
46+6. Include parallel execution examples:
47+ - Group [P] tasks that can run together
48+ - Show actual Task agent commands
49+
50+7. Create FEATURE_DIR/tasks.md with:
51+ - Correct feature name from implementation plan
52+ - Numbered tasks (T001, T002, etc.)
53+ - Clear file paths for each task
54+ - Dependency notes
55+ - Parallel execution guidance
56+
57+Context for task generation: $ARGUMENTS
58+
59+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
A memory/constitution.md +50 -0
@@ -0,0 +1,50 @@
1+# [PROJECT_NAME] Constitution
2+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
3+
4+## Core Principles
5+
6+### [PRINCIPLE_1_NAME]
7+<!-- Example: I. Library-First -->
8+[PRINCIPLE_1_DESCRIPTION]
9+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
10+
11+### [PRINCIPLE_2_NAME]
12+<!-- Example: II. CLI Interface -->
13+[PRINCIPLE_2_DESCRIPTION]
14+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
15+
16+### [PRINCIPLE_3_NAME]
17+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
18+[PRINCIPLE_3_DESCRIPTION]
19+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
20+
21+### [PRINCIPLE_4_NAME]
22+<!-- Example: IV. Integration Testing -->
23+[PRINCIPLE_4_DESCRIPTION]
24+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
25+
26+### [PRINCIPLE_5_NAME]
27+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
28+[PRINCIPLE_5_DESCRIPTION]
29+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
30+
31+## [SECTION_2_NAME]
32+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
33+
34+[SECTION_2_CONTENT]
35+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
36+
37+## [SECTION_3_NAME]
38+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
39+
40+[SECTION_3_CONTENT]
41+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
42+
43+## Governance
44+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
45+
46+[GOVERNANCE_RULES]
47+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
48+
49+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
50+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->⏎̸
@@ -0,0 +1,50 @@
1+# [PROJECT_NAME] Constitution
2+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
3+
4+## Core Principles
5+
6+### [PRINCIPLE_1_NAME]
7+<!-- Example: I. Library-First -->
8+[PRINCIPLE_1_DESCRIPTION]
9+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
10+
11+### [PRINCIPLE_2_NAME]
12+<!-- Example: II. CLI Interface -->
13+[PRINCIPLE_2_DESCRIPTION]
14+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
15+
16+### [PRINCIPLE_3_NAME]
17+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
18+[PRINCIPLE_3_DESCRIPTION]
19+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
20+
21+### [PRINCIPLE_4_NAME]
22+<!-- Example: IV. Integration Testing -->
23+[PRINCIPLE_4_DESCRIPTION]
24+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
25+
26+### [PRINCIPLE_5_NAME]
27+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
28+[PRINCIPLE_5_DESCRIPTION]
29+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
30+
31+## [SECTION_2_NAME]
32+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
33+
34+[SECTION_2_CONTENT]
35+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
36+
37+## [SECTION_3_NAME]
38+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
39+
40+[SECTION_3_CONTENT]
41+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
42+
43+## Governance
44+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
45+
46+[GOVERNANCE_RULES]
47+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
48+
49+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
50+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->⏎̸
A memory/constitution_update_checklist.md +85 -0
@@ -0,0 +1,85 @@
1+# Constitution Update Checklist
2+
3+When amending the constitution (`/memory/constitution.md`), ensure all dependent documents are updated to maintain consistency.
4+
5+## Templates to Update
6+
7+### When adding/modifying ANY article:
8+- [ ] `/templates/plan-template.md` - Update Constitution Check section
9+- [ ] `/templates/spec-template.md` - Update if requirements/scope affected
10+- [ ] `/templates/tasks-template.md` - Update if new task types needed
11+- [ ] `/.claude/commands/plan.md` - Update if planning process changes
12+- [ ] `/.claude/commands/tasks.md` - Update if task generation affected
13+- [ ] `/CLAUDE.md` - Update runtime development guidelines
14+
15+### Article-specific updates:
16+
17+#### Article I (Library-First):
18+- [ ] Ensure templates emphasize library creation
19+- [ ] Update CLI command examples
20+- [ ] Add llms.txt documentation requirements
21+
22+#### Article II (CLI Interface):
23+- [ ] Update CLI flag requirements in templates
24+- [ ] Add text I/O protocol reminders
25+
26+#### Article III (Test-First):
27+- [ ] Update test order in all templates
28+- [ ] Emphasize TDD requirements
29+- [ ] Add test approval gates
30+
31+#### Article IV (Integration Testing):
32+- [ ] List integration test triggers
33+- [ ] Update test type priorities
34+- [ ] Add real dependency requirements
35+
36+#### Article V (Observability):
37+- [ ] Add logging requirements to templates
38+- [ ] Include multi-tier log streaming
39+- [ ] Update performance monitoring sections
40+
41+#### Article VI (Versioning):
42+- [ ] Add version increment reminders
43+- [ ] Include breaking change procedures
44+- [ ] Update migration requirements
45+
46+#### Article VII (Simplicity):
47+- [ ] Update project count limits
48+- [ ] Add pattern prohibition examples
49+- [ ] Include YAGNI reminders
50+
51+## Validation Steps
52+
53+1. **Before committing constitution changes:**
54+ - [ ] All templates reference new requirements
55+ - [ ] Examples updated to match new rules
56+ - [ ] No contradictions between documents
57+
58+2. **After updating templates:**
59+ - [ ] Run through a sample implementation plan
60+ - [ ] Verify all constitution requirements addressed
61+ - [ ] Check that templates are self-contained (readable without constitution)
62+
63+3. **Version tracking:**
64+ - [ ] Update constitution version number
65+ - [ ] Note version in template footers
66+ - [ ] Add amendment to constitution history
67+
68+## Common Misses
69+
70+Watch for these often-forgotten updates:
71+- Command documentation (`/commands/*.md`)
72+- Checklist items in templates
73+- Example code/commands
74+- Domain-specific variations (web vs mobile vs CLI)
75+- Cross-references between documents
76+
77+## Template Sync Status
78+
79+Last sync check: 2025-07-16
80+- Constitution version: 2.1.1
81+- Templates aligned: ❌ (missing versioning, observability details)
82+
83+---
84+
85+*This checklist ensures the constitution's principles are consistently applied across all project documentation.*⏎̸
@@ -0,0 +1,85 @@
1+# Constitution Update Checklist
2+
3+When amending the constitution (`/memory/constitution.md`), ensure all dependent documents are updated to maintain consistency.
4+
5+## Templates to Update
6+
7+### When adding/modifying ANY article:
8+- [ ] `/templates/plan-template.md` - Update Constitution Check section
9+- [ ] `/templates/spec-template.md` - Update if requirements/scope affected
10+- [ ] `/templates/tasks-template.md` - Update if new task types needed
11+- [ ] `/.claude/commands/plan.md` - Update if planning process changes
12+- [ ] `/.claude/commands/tasks.md` - Update if task generation affected
13+- [ ] `/CLAUDE.md` - Update runtime development guidelines
14+
15+### Article-specific updates:
16+
17+#### Article I (Library-First):
18+- [ ] Ensure templates emphasize library creation
19+- [ ] Update CLI command examples
20+- [ ] Add llms.txt documentation requirements
21+
22+#### Article II (CLI Interface):
23+- [ ] Update CLI flag requirements in templates
24+- [ ] Add text I/O protocol reminders
25+
26+#### Article III (Test-First):
27+- [ ] Update test order in all templates
28+- [ ] Emphasize TDD requirements
29+- [ ] Add test approval gates
30+
31+#### Article IV (Integration Testing):
32+- [ ] List integration test triggers
33+- [ ] Update test type priorities
34+- [ ] Add real dependency requirements
35+
36+#### Article V (Observability):
37+- [ ] Add logging requirements to templates
38+- [ ] Include multi-tier log streaming
39+- [ ] Update performance monitoring sections
40+
41+#### Article VI (Versioning):
42+- [ ] Add version increment reminders
43+- [ ] Include breaking change procedures
44+- [ ] Update migration requirements
45+
46+#### Article VII (Simplicity):
47+- [ ] Update project count limits
48+- [ ] Add pattern prohibition examples
49+- [ ] Include YAGNI reminders
50+
51+## Validation Steps
52+
53+1. **Before committing constitution changes:**
54+ - [ ] All templates reference new requirements
55+ - [ ] Examples updated to match new rules
56+ - [ ] No contradictions between documents
57+
58+2. **After updating templates:**
59+ - [ ] Run through a sample implementation plan
60+ - [ ] Verify all constitution requirements addressed
61+ - [ ] Check that templates are self-contained (readable without constitution)
62+
63+3. **Version tracking:**
64+ - [ ] Update constitution version number
65+ - [ ] Note version in template footers
66+ - [ ] Add amendment to constitution history
67+
68+## Common Misses
69+
70+Watch for these often-forgotten updates:
71+- Command documentation (`/commands/*.md`)
72+- Checklist items in templates
73+- Example code/commands
74+- Domain-specific variations (web vs mobile vs CLI)
75+- Cross-references between documents
76+
77+## Template Sync Status
78+
79+Last sync check: 2025-07-16
80+- Constitution version: 2.1.1
81+- Templates aligned: ❌ (missing versioning, observability details)
82+
83+---
84+
85+*This checklist ensures the constitution's principles are consistently applied across all project documentation.*⏎̸
A scripts/check-task-prerequisites.sh +62 -0
@@ -0,0 +1,62 @@
1+#!/usr/bin/env bash
2+# Check that implementation plan exists and find optional design documents
3+# Usage: ./check-task-prerequisites.sh [--json]
4+
5+set -e
6+
7+JSON_MODE=false
8+for arg in "$@"; do
9+ case "$arg" in
10+ --json) JSON_MODE=true ;;
11+ --help|-h) echo "Usage: $0 [--json]"; exit 0 ;;
12+ esac
13+done
14+
15+# Source common functions
16+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
17+source "$SCRIPT_DIR/common.sh"
18+
19+# Get all paths
20+eval $(get_feature_paths)
21+
22+# Check if on feature branch
23+check_feature_branch "$CURRENT_BRANCH" || exit 1
24+
25+# Check if feature directory exists
26+if [[ ! -d "$FEATURE_DIR" ]]; then
27+ echo "ERROR: Feature directory not found: $FEATURE_DIR"
28+ echo "Run /specify first to create the feature structure."
29+ exit 1
30+fi
31+
32+# Check for implementation plan (required)
33+if [[ ! -f "$IMPL_PLAN" ]]; then
34+ echo "ERROR: plan.md not found in $FEATURE_DIR"
35+ echo "Run /plan first to create the plan."
36+ exit 1
37+fi
38+
39+if $JSON_MODE; then
40+ # Build JSON array of available docs that actually exist
41+ docs=()
42+ [[ -f "$RESEARCH" ]] && docs+=("research.md")
43+ [[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
44+ ([[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]) && docs+=("contracts/")
45+ [[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
46+ # join array into JSON
47+ json_docs=$(printf '"%s",' "${docs[@]}")
48+ json_docs="[${json_docs%,}]"
49+ printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
50+else
51+ # List available design documents (optional)
52+ echo "FEATURE_DIR:$FEATURE_DIR"
53+ echo "AVAILABLE_DOCS:"
54+
55+ # Use common check functions
56+ check_file "$RESEARCH" "research.md"
57+ check_file "$DATA_MODEL" "data-model.md"
58+ check_dir "$CONTRACTS_DIR" "contracts/"
59+ check_file "$QUICKSTART" "quickstart.md"
60+fi
61+
62+# Always succeed - task generation should work with whatever docs are available⏎̸
@@ -0,0 +1,62 @@
1+#!/usr/bin/env bash
2+# Check that implementation plan exists and find optional design documents
3+# Usage: ./check-task-prerequisites.sh [--json]
4+
5+set -e
6+
7+JSON_MODE=false
8+for arg in "$@"; do
9+ case "$arg" in
10+ --json) JSON_MODE=true ;;
11+ --help|-h) echo "Usage: $0 [--json]"; exit 0 ;;
12+ esac
13+done
14+
15+# Source common functions
16+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
17+source "$SCRIPT_DIR/common.sh"
18+
19+# Get all paths
20+eval $(get_feature_paths)
21+
22+# Check if on feature branch
23+check_feature_branch "$CURRENT_BRANCH" || exit 1
24+
25+# Check if feature directory exists
26+if [[ ! -d "$FEATURE_DIR" ]]; then
27+ echo "ERROR: Feature directory not found: $FEATURE_DIR"
28+ echo "Run /specify first to create the feature structure."
29+ exit 1
30+fi
31+
32+# Check for implementation plan (required)
33+if [[ ! -f "$IMPL_PLAN" ]]; then
34+ echo "ERROR: plan.md not found in $FEATURE_DIR"
35+ echo "Run /plan first to create the plan."
36+ exit 1
37+fi
38+
39+if $JSON_MODE; then
40+ # Build JSON array of available docs that actually exist
41+ docs=()
42+ [[ -f "$RESEARCH" ]] && docs+=("research.md")
43+ [[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
44+ ([[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]) && docs+=("contracts/")
45+ [[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
46+ # join array into JSON
47+ json_docs=$(printf '"%s",' "${docs[@]}")
48+ json_docs="[${json_docs%,}]"
49+ printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
50+else
51+ # List available design documents (optional)
52+ echo "FEATURE_DIR:$FEATURE_DIR"
53+ echo "AVAILABLE_DOCS:"
54+
55+ # Use common check functions
56+ check_file "$RESEARCH" "research.md"
57+ check_file "$DATA_MODEL" "data-model.md"
58+ check_dir "$CONTRACTS_DIR" "contracts/"
59+ check_file "$QUICKSTART" "quickstart.md"
60+fi
61+
62+# Always succeed - task generation should work with whatever docs are available⏎̸
A scripts/common.sh +77 -0
@@ -0,0 +1,77 @@
1+#!/usr/bin/env bash
2+# Common functions and variables for all scripts
3+
4+# Get repository root
5+get_repo_root() {
6+ git rev-parse --show-toplevel
7+}
8+
9+# Get current branch
10+get_current_branch() {
11+ git rev-parse --abbrev-ref HEAD
12+}
13+
14+# Check if current branch is a feature branch
15+# Returns 0 if valid, 1 if not
16+check_feature_branch() {
17+ local branch="$1"
18+ if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
19+ echo "ERROR: Not on a feature branch. Current branch: $branch"
20+ echo "Feature branches should be named like: 001-feature-name"
21+ return 1
22+ fi
23+ return 0
24+}
25+
26+# Get feature directory path
27+get_feature_dir() {
28+ local repo_root="$1"
29+ local branch="$2"
30+ echo "$repo_root/specs/$branch"
31+}
32+
33+# Get all standard paths for a feature
34+# Usage: eval $(get_feature_paths)
35+# Sets: REPO_ROOT, CURRENT_BRANCH, FEATURE_DIR, FEATURE_SPEC, IMPL_PLAN, TASKS
36+get_feature_paths() {
37+ local repo_root=$(get_repo_root)
38+ local current_branch=$(get_current_branch)
39+ local feature_dir=$(get_feature_dir "$repo_root" "$current_branch")
40+
41+ echo "REPO_ROOT='$repo_root'"
42+ echo "CURRENT_BRANCH='$current_branch'"
43+ echo "FEATURE_DIR='$feature_dir'"
44+ echo "FEATURE_SPEC='$feature_dir/spec.md'"
45+ echo "IMPL_PLAN='$feature_dir/plan.md'"
46+ echo "TASKS='$feature_dir/tasks.md'"
47+ echo "RESEARCH='$feature_dir/research.md'"
48+ echo "DATA_MODEL='$feature_dir/data-model.md'"
49+ echo "QUICKSTART='$feature_dir/quickstart.md'"
50+ echo "CONTRACTS_DIR='$feature_dir/contracts'"
51+}
52+
53+# Check if a file exists and report
54+check_file() {
55+ local file="$1"
56+ local description="$2"
57+ if [[ -f "$file" ]]; then
58+ echo " ✓ $description"
59+ return 0
60+ else
61+ echo " ✗ $description"
62+ return 1
63+ fi
64+}
65+
66+# Check if a directory exists and has files
67+check_dir() {
68+ local dir="$1"
69+ local description="$2"
70+ if [[ -d "$dir" ]] && [[ -n "$(ls -A "$dir" 2>/dev/null)" ]]; then
71+ echo " ✓ $description"
72+ return 0
73+ else
74+ echo " ✗ $description"
75+ return 1
76+ fi
77+}⏎̸
@@ -0,0 +1,77 @@
1+#!/usr/bin/env bash
2+# Common functions and variables for all scripts
3+
4+# Get repository root
5+get_repo_root() {
6+ git rev-parse --show-toplevel
7+}
8+
9+# Get current branch
10+get_current_branch() {
11+ git rev-parse --abbrev-ref HEAD
12+}
13+
14+# Check if current branch is a feature branch
15+# Returns 0 if valid, 1 if not
16+check_feature_branch() {
17+ local branch="$1"
18+ if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
19+ echo "ERROR: Not on a feature branch. Current branch: $branch"
20+ echo "Feature branches should be named like: 001-feature-name"
21+ return 1
22+ fi
23+ return 0
24+}
25+
26+# Get feature directory path
27+get_feature_dir() {
28+ local repo_root="$1"
29+ local branch="$2"
30+ echo "$repo_root/specs/$branch"
31+}
32+
33+# Get all standard paths for a feature
34+# Usage: eval $(get_feature_paths)
35+# Sets: REPO_ROOT, CURRENT_BRANCH, FEATURE_DIR, FEATURE_SPEC, IMPL_PLAN, TASKS
36+get_feature_paths() {
37+ local repo_root=$(get_repo_root)
38+ local current_branch=$(get_current_branch)
39+ local feature_dir=$(get_feature_dir "$repo_root" "$current_branch")
40+
41+ echo "REPO_ROOT='$repo_root'"
42+ echo "CURRENT_BRANCH='$current_branch'"
43+ echo "FEATURE_DIR='$feature_dir'"
44+ echo "FEATURE_SPEC='$feature_dir/spec.md'"
45+ echo "IMPL_PLAN='$feature_dir/plan.md'"
46+ echo "TASKS='$feature_dir/tasks.md'"
47+ echo "RESEARCH='$feature_dir/research.md'"
48+ echo "DATA_MODEL='$feature_dir/data-model.md'"
49+ echo "QUICKSTART='$feature_dir/quickstart.md'"
50+ echo "CONTRACTS_DIR='$feature_dir/contracts'"
51+}
52+
53+# Check if a file exists and report
54+check_file() {
55+ local file="$1"
56+ local description="$2"
57+ if [[ -f "$file" ]]; then
58+ echo " ✓ $description"
59+ return 0
60+ else
61+ echo " ✗ $description"
62+ return 1
63+ fi
64+}
65+
66+# Check if a directory exists and has files
67+check_dir() {
68+ local dir="$1"
69+ local description="$2"
70+ if [[ -d "$dir" ]] && [[ -n "$(ls -A "$dir" 2>/dev/null)" ]]; then
71+ echo " ✓ $description"
72+ return 0
73+ else
74+ echo " ✗ $description"
75+ return 1
76+ fi
77+}⏎̸
A scripts/create-new-feature.sh +96 -0
@@ -0,0 +1,96 @@
1+#!/usr/bin/env bash
2+# Create a new feature with branch, directory structure, and template
3+# Usage: ./create-new-feature.sh "feature description"
4+# ./create-new-feature.sh --json "feature description"
5+
6+set -e
7+
8+JSON_MODE=false
9+
10+# Collect non-flag args
11+ARGS=()
12+for arg in "$@"; do
13+ case "$arg" in
14+ --json)
15+ JSON_MODE=true
16+ ;;
17+ --help|-h)
18+ echo "Usage: $0 [--json] <feature_description>"; exit 0 ;;
19+ *)
20+ ARGS+=("$arg") ;;
21+ esac
22+done
23+
24+FEATURE_DESCRIPTION="${ARGS[*]}"
25+if [ -z "$FEATURE_DESCRIPTION" ]; then
26+ echo "Usage: $0 [--json] <feature_description>" >&2
27+ exit 1
28+fi
29+
30+# Get repository root
31+REPO_ROOT=$(git rev-parse --show-toplevel)
32+SPECS_DIR="$REPO_ROOT/specs"
33+
34+# Create specs directory if it doesn't exist
35+mkdir -p "$SPECS_DIR"
36+
37+# Find the highest numbered feature directory
38+HIGHEST=0
39+if [ -d "$SPECS_DIR" ]; then
40+ for dir in "$SPECS_DIR"/*; do
41+ if [ -d "$dir" ]; then
42+ dirname=$(basename "$dir")
43+ number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
44+ number=$((10#$number))
45+ if [ "$number" -gt "$HIGHEST" ]; then
46+ HIGHEST=$number
47+ fi
48+ fi
49+ done
50+fi
51+
52+# Generate next feature number with zero padding
53+NEXT=$((HIGHEST + 1))
54+FEATURE_NUM=$(printf "%03d" "$NEXT")
55+
56+# Create branch name from description
57+BRANCH_NAME=$(echo "$FEATURE_DESCRIPTION" | \
58+ tr '[:upper:]' '[:lower:]' | \
59+ sed 's/[^a-z0-9]/-/g' | \
60+ sed 's/-\+/-/g' | \
61+ sed 's/^-//' | \
62+ sed 's/-$//')
63+
64+# Extract 2-3 meaningful words
65+WORDS=$(echo "$BRANCH_NAME" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//')
66+
67+# Final branch name
68+BRANCH_NAME="${FEATURE_NUM}-${WORDS}"
69+
70+# Create and switch to new branch
71+git checkout -b "$BRANCH_NAME"
72+
73+# Create feature directory
74+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
75+mkdir -p "$FEATURE_DIR"
76+
77+# Copy template if it exists
78+TEMPLATE="$REPO_ROOT/templates/spec-template.md"
79+SPEC_FILE="$FEATURE_DIR/spec.md"
80+
81+if [ -f "$TEMPLATE" ]; then
82+ cp "$TEMPLATE" "$SPEC_FILE"
83+else
84+ echo "Warning: Template not found at $TEMPLATE" >&2
85+ touch "$SPEC_FILE"
86+fi
87+
88+if $JSON_MODE; then
89+ printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' \
90+ "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
91+else
92+ # Output results for the LLM to use (legacy key: value format)
93+ echo "BRANCH_NAME: $BRANCH_NAME"
94+ echo "SPEC_FILE: $SPEC_FILE"
95+ echo "FEATURE_NUM: $FEATURE_NUM"
96+fi⏎̸
@@ -0,0 +1,96 @@
1+#!/usr/bin/env bash
2+# Create a new feature with branch, directory structure, and template
3+# Usage: ./create-new-feature.sh "feature description"
4+# ./create-new-feature.sh --json "feature description"
5+
6+set -e
7+
8+JSON_MODE=false
9+
10+# Collect non-flag args
11+ARGS=()
12+for arg in "$@"; do
13+ case "$arg" in
14+ --json)
15+ JSON_MODE=true
16+ ;;
17+ --help|-h)
18+ echo "Usage: $0 [--json] <feature_description>"; exit 0 ;;
19+ *)
20+ ARGS+=("$arg") ;;
21+ esac
22+done
23+
24+FEATURE_DESCRIPTION="${ARGS[*]}"
25+if [ -z "$FEATURE_DESCRIPTION" ]; then
26+ echo "Usage: $0 [--json] <feature_description>" >&2
27+ exit 1
28+fi
29+
30+# Get repository root
31+REPO_ROOT=$(git rev-parse --show-toplevel)
32+SPECS_DIR="$REPO_ROOT/specs"
33+
34+# Create specs directory if it doesn't exist
35+mkdir -p "$SPECS_DIR"
36+
37+# Find the highest numbered feature directory
38+HIGHEST=0
39+if [ -d "$SPECS_DIR" ]; then
40+ for dir in "$SPECS_DIR"/*; do
41+ if [ -d "$dir" ]; then
42+ dirname=$(basename "$dir")
43+ number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
44+ number=$((10#$number))
45+ if [ "$number" -gt "$HIGHEST" ]; then
46+ HIGHEST=$number
47+ fi
48+ fi
49+ done
50+fi
51+
52+# Generate next feature number with zero padding
53+NEXT=$((HIGHEST + 1))
54+FEATURE_NUM=$(printf "%03d" "$NEXT")
55+
56+# Create branch name from description
57+BRANCH_NAME=$(echo "$FEATURE_DESCRIPTION" | \
58+ tr '[:upper:]' '[:lower:]' | \
59+ sed 's/[^a-z0-9]/-/g' | \
60+ sed 's/-\+/-/g' | \
61+ sed 's/^-//' | \
62+ sed 's/-$//')
63+
64+# Extract 2-3 meaningful words
65+WORDS=$(echo "$BRANCH_NAME" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//')
66+
67+# Final branch name
68+BRANCH_NAME="${FEATURE_NUM}-${WORDS}"
69+
70+# Create and switch to new branch
71+git checkout -b "$BRANCH_NAME"
72+
73+# Create feature directory
74+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
75+mkdir -p "$FEATURE_DIR"
76+
77+# Copy template if it exists
78+TEMPLATE="$REPO_ROOT/templates/spec-template.md"
79+SPEC_FILE="$FEATURE_DIR/spec.md"
80+
81+if [ -f "$TEMPLATE" ]; then
82+ cp "$TEMPLATE" "$SPEC_FILE"
83+else
84+ echo "Warning: Template not found at $TEMPLATE" >&2
85+ touch "$SPEC_FILE"
86+fi
87+
88+if $JSON_MODE; then
89+ printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' \
90+ "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
91+else
92+ # Output results for the LLM to use (legacy key: value format)
93+ echo "BRANCH_NAME: $BRANCH_NAME"
94+ echo "SPEC_FILE: $SPEC_FILE"
95+ echo "FEATURE_NUM: $FEATURE_NUM"
96+fi⏎̸
A scripts/get-feature-paths.sh +23 -0
@@ -0,0 +1,23 @@
1+#!/usr/bin/env bash
2+# Get paths for current feature branch without creating anything
3+# Used by commands that need to find existing feature files
4+
5+set -e
6+
7+# Source common functions
8+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
9+source "$SCRIPT_DIR/common.sh"
10+
11+# Get all paths
12+eval $(get_feature_paths)
13+
14+# Check if on feature branch
15+check_feature_branch "$CURRENT_BRANCH" || exit 1
16+
17+# Output paths (don't create anything)
18+echo "REPO_ROOT: $REPO_ROOT"
19+echo "BRANCH: $CURRENT_BRANCH"
20+echo "FEATURE_DIR: $FEATURE_DIR"
21+echo "FEATURE_SPEC: $FEATURE_SPEC"
22+echo "IMPL_PLAN: $IMPL_PLAN"
23+echo "TASKS: $TASKS"⏎̸
@@ -0,0 +1,23 @@
1+#!/usr/bin/env bash
2+# Get paths for current feature branch without creating anything
3+# Used by commands that need to find existing feature files
4+
5+set -e
6+
7+# Source common functions
8+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
9+source "$SCRIPT_DIR/common.sh"
10+
11+# Get all paths
12+eval $(get_feature_paths)
13+
14+# Check if on feature branch
15+check_feature_branch "$CURRENT_BRANCH" || exit 1
16+
17+# Output paths (don't create anything)
18+echo "REPO_ROOT: $REPO_ROOT"
19+echo "BRANCH: $CURRENT_BRANCH"
20+echo "FEATURE_DIR: $FEATURE_DIR"
21+echo "FEATURE_SPEC: $FEATURE_SPEC"
22+echo "IMPL_PLAN: $IMPL_PLAN"
23+echo "TASKS: $TASKS"⏎̸
A scripts/setup-plan.sh +44 -0
@@ -0,0 +1,44 @@
1+#!/usr/bin/env bash
2+# Setup implementation plan structure for current branch
3+# Returns paths needed for implementation plan generation
4+# Usage: ./setup-plan.sh [--json]
5+
6+set -e
7+
8+JSON_MODE=false
9+for arg in "$@"; do
10+ case "$arg" in
11+ --json) JSON_MODE=true ;;
12+ --help|-h) echo "Usage: $0 [--json]"; exit 0 ;;
13+ esac
14+done
15+
16+# Source common functions
17+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
18+source "$SCRIPT_DIR/common.sh"
19+
20+# Get all paths
21+eval $(get_feature_paths)
22+
23+# Check if on feature branch
24+check_feature_branch "$CURRENT_BRANCH" || exit 1
25+
26+# Create specs directory if it doesn't exist
27+mkdir -p "$FEATURE_DIR"
28+
29+# Copy plan template if it exists
30+TEMPLATE="$REPO_ROOT/templates/plan-template.md"
31+if [ -f "$TEMPLATE" ]; then
32+ cp "$TEMPLATE" "$IMPL_PLAN"
33+fi
34+
35+if $JSON_MODE; then
36+ printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s"}\n' \
37+ "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH"
38+else
39+ # Output all paths for LLM use
40+ echo "FEATURE_SPEC: $FEATURE_SPEC"
41+ echo "IMPL_PLAN: $IMPL_PLAN"
42+ echo "SPECS_DIR: $FEATURE_DIR"
43+ echo "BRANCH: $CURRENT_BRANCH"
44+fi⏎̸
@@ -0,0 +1,44 @@
1+#!/usr/bin/env bash
2+# Setup implementation plan structure for current branch
3+# Returns paths needed for implementation plan generation
4+# Usage: ./setup-plan.sh [--json]
5+
6+set -e
7+
8+JSON_MODE=false
9+for arg in "$@"; do
10+ case "$arg" in
11+ --json) JSON_MODE=true ;;
12+ --help|-h) echo "Usage: $0 [--json]"; exit 0 ;;
13+ esac
14+done
15+
16+# Source common functions
17+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
18+source "$SCRIPT_DIR/common.sh"
19+
20+# Get all paths
21+eval $(get_feature_paths)
22+
23+# Check if on feature branch
24+check_feature_branch "$CURRENT_BRANCH" || exit 1
25+
26+# Create specs directory if it doesn't exist
27+mkdir -p "$FEATURE_DIR"
28+
29+# Copy plan template if it exists
30+TEMPLATE="$REPO_ROOT/templates/plan-template.md"
31+if [ -f "$TEMPLATE" ]; then
32+ cp "$TEMPLATE" "$IMPL_PLAN"
33+fi
34+
35+if $JSON_MODE; then
36+ printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s"}\n' \
37+ "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH"
38+else
39+ # Output all paths for LLM use
40+ echo "FEATURE_SPEC: $FEATURE_SPEC"
41+ echo "IMPL_PLAN: $IMPL_PLAN"
42+ echo "SPECS_DIR: $FEATURE_DIR"
43+ echo "BRANCH: $CURRENT_BRANCH"
44+fi⏎̸
A scripts/update-agent-context.sh +234 -0
@@ -0,0 +1,234 @@
1+#!/usr/bin/env bash
2+# Incrementally update agent context files based on new feature plan
3+# Supports: CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md
4+# O(1) operation - only reads current context file and new plan.md
5+
6+set -e
7+
8+REPO_ROOT=$(git rev-parse --show-toplevel)
9+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
10+FEATURE_DIR="$REPO_ROOT/specs/$CURRENT_BRANCH"
11+NEW_PLAN="$FEATURE_DIR/plan.md"
12+
13+# Determine which agent context files to update
14+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
15+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
16+COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"
17+
18+# Allow override via argument
19+AGENT_TYPE="$1"
20+
21+if [ ! -f "$NEW_PLAN" ]; then
22+ echo "ERROR: No plan.md found at $NEW_PLAN"
23+ exit 1
24+fi
25+
26+echo "=== Updating agent context files for feature $CURRENT_BRANCH ==="
27+
28+# Extract tech from new plan
29+NEW_LANG=$(grep "^**Language/Version**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Language\/Version**: //' | grep -v "NEEDS CLARIFICATION" || echo "")
30+NEW_FRAMEWORK=$(grep "^**Primary Dependencies**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Primary Dependencies**: //' | grep -v "NEEDS CLARIFICATION" || echo "")
31+NEW_TESTING=$(grep "^**Testing**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Testing**: //' | grep -v "NEEDS CLARIFICATION" || echo "")
32+NEW_DB=$(grep "^**Storage**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Storage**: //' | grep -v "N/A" | grep -v "NEEDS CLARIFICATION" || echo "")
33+NEW_PROJECT_TYPE=$(grep "^**Project Type**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Project Type**: //' || echo "")
34+
35+# Function to update a single agent context file
36+update_agent_file() {
37+ local target_file="$1"
38+ local agent_name="$2"
39+
40+ echo "Updating $agent_name context file: $target_file"
41+
42+ # Create temp file for new context
43+ local temp_file=$(mktemp)
44+
45+ # If file doesn't exist, create from template
46+ if [ ! -f "$target_file" ]; then
47+ echo "Creating new $agent_name context file..."
48+
49+ # Check if this is the SDD repo itself
50+ if [ -f "$REPO_ROOT/templates/agent-file-template.md" ]; then
51+ cp "$REPO_ROOT/templates/agent-file-template.md" "$temp_file"
52+ else
53+ echo "ERROR: Template not found at $REPO_ROOT/templates/agent-file-template.md"
54+ return 1
55+ fi
56+
57+ # Replace placeholders
58+ sed -i.bak "s/\[PROJECT NAME\]/$(basename $REPO_ROOT)/" "$temp_file"
59+ sed -i.bak "s/\[DATE\]/$(date +%Y-%m-%d)/" "$temp_file"
60+ sed -i.bak "s/\[EXTRACTED FROM ALL PLAN.MD FILES\]/- $NEW_LANG + $NEW_FRAMEWORK ($CURRENT_BRANCH)/" "$temp_file"
61+
62+ # Add project structure based on type
63+ if [[ "$NEW_PROJECT_TYPE" == *"web"* ]]; then
64+ sed -i.bak "s|\[ACTUAL STRUCTURE FROM PLANS\]|backend/\nfrontend/\ntests/|" "$temp_file"
65+ else
66+ sed -i.bak "s|\[ACTUAL STRUCTURE FROM PLANS\]|src/\ntests/|" "$temp_file"
67+ fi
68+
69+ # Add minimal commands
70+ if [[ "$NEW_LANG" == *"Python"* ]]; then
71+ COMMANDS="cd src && pytest && ruff check ."
72+ elif [[ "$NEW_LANG" == *"Rust"* ]]; then
73+ COMMANDS="cargo test && cargo clippy"
74+ elif [[ "$NEW_LANG" == *"JavaScript"* ]] || [[ "$NEW_LANG" == *"TypeScript"* ]]; then
75+ COMMANDS="npm test && npm run lint"
76+ else
77+ COMMANDS="# Add commands for $NEW_LANG"
78+ fi
79+ sed -i.bak "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$COMMANDS|" "$temp_file"
80+
81+ # Add code style
82+ sed -i.bak "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$NEW_LANG: Follow standard conventions|" "$temp_file"
83+
84+ # Add recent changes
85+ sed -i.bak "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|- $CURRENT_BRANCH: Added $NEW_LANG + $NEW_FRAMEWORK|" "$temp_file"
86+
87+ rm "$temp_file.bak"
88+ else
89+ echo "Updating existing $agent_name context file..."
90+
91+ # Extract manual additions
92+ local manual_start=$(grep -n "<!-- MANUAL ADDITIONS START -->" "$target_file" | cut -d: -f1)
93+ local manual_end=$(grep -n "<!-- MANUAL ADDITIONS END -->" "$target_file" | cut -d: -f1)
94+
95+ if [ ! -z "$manual_start" ] && [ ! -z "$manual_end" ]; then
96+ sed -n "${manual_start},${manual_end}p" "$target_file" > /tmp/manual_additions.txt
97+ fi
98+
99+ # Parse existing file and create updated version
100+ python3 - << EOF
101+import re
102+import sys
103+from datetime import datetime
104+
105+# Read existing file
106+with open("$target_file", 'r') as f:
107+ content = f.read()
108+
109+# Check if new tech already exists
110+tech_section = re.search(r'## Active Technologies\n(.*?)\n\n', content, re.DOTALL)
111+if tech_section:
112+ existing_tech = tech_section.group(1)
113+
114+ # Add new tech if not already present
115+ new_additions = []
116+ if "$NEW_LANG" and "$NEW_LANG" not in existing_tech:
117+ new_additions.append(f"- $NEW_LANG + $NEW_FRAMEWORK ($CURRENT_BRANCH)")
118+ if "$NEW_DB" and "$NEW_DB" not in existing_tech and "$NEW_DB" != "N/A":
119+ new_additions.append(f"- $NEW_DB ($CURRENT_BRANCH)")
120+
121+ if new_additions:
122+ updated_tech = existing_tech + "\n" + "\n".join(new_additions)
123+ content = content.replace(tech_section.group(0), f"## Active Technologies\n{updated_tech}\n\n")
124+
125+# Update project structure if needed
126+if "$NEW_PROJECT_TYPE" == "web" and "frontend/" not in content:
127+ struct_section = re.search(r'## Project Structure\n\`\`\`\n(.*?)\n\`\`\`', content, re.DOTALL)
128+ if struct_section:
129+ updated_struct = struct_section.group(1) + "\nfrontend/src/ # Web UI"
130+ content = re.sub(r'(## Project Structure\n\`\`\`\n).*?(\n\`\`\`)',
131+ f'\\1{updated_struct}\\2', content, flags=re.DOTALL)
132+
133+# Add new commands if language is new
134+if "$NEW_LANG" and f"# {NEW_LANG}" not in content:
135+ commands_section = re.search(r'## Commands\n\`\`\`bash\n(.*?)\n\`\`\`', content, re.DOTALL)
136+ if not commands_section:
137+ commands_section = re.search(r'## Commands\n(.*?)\n\n', content, re.DOTALL)
138+
139+ if commands_section:
140+ new_commands = commands_section.group(1)
141+ if "Python" in "$NEW_LANG":
142+ new_commands += "\ncd src && pytest && ruff check ."
143+ elif "Rust" in "$NEW_LANG":
144+ new_commands += "\ncargo test && cargo clippy"
145+ elif "JavaScript" in "$NEW_LANG" or "TypeScript" in "$NEW_LANG":
146+ new_commands += "\nnpm test && npm run lint"
147+
148+ if "```bash" in content:
149+ content = re.sub(r'(## Commands\n\`\`\`bash\n).*?(\n\`\`\`)',
150+ f'\\1{new_commands}\\2', content, flags=re.DOTALL)
151+ else:
152+ content = re.sub(r'(## Commands\n).*?(\n\n)',
153+ f'\\1{new_commands}\\2', content, flags=re.DOTALL)
154+
155+# Update recent changes (keep only last 3)
156+changes_section = re.search(r'## Recent Changes\n(.*?)(\n\n|$)', content, re.DOTALL)
157+if changes_section:
158+ changes = changes_section.group(1).strip().split('\n')
159+ changes.insert(0, f"- $CURRENT_BRANCH: Added $NEW_LANG + $NEW_FRAMEWORK")
160+ # Keep only last 3
161+ changes = changes[:3]
162+ content = re.sub(r'(## Recent Changes\n).*?(\n\n|$)',
163+ f'\\1{chr(10).join(changes)}\\2', content, flags=re.DOTALL)
164+
165+# Update date
166+content = re.sub(r'Last updated: \d{4}-\d{2}-\d{2}',
167+ f'Last updated: {datetime.now().strftime("%Y-%m-%d")}', content)
168+
169+# Write to temp file
170+with open("$temp_file", 'w') as f:
171+ f.write(content)
172+EOF
173+
174+ # Restore manual additions if they exist
175+ if [ -f /tmp/manual_additions.txt ]; then
176+ # Remove old manual section from temp file
177+ sed -i.bak '/<!-- MANUAL ADDITIONS START -->/,/<!-- MANUAL ADDITIONS END -->/d' "$temp_file"
178+ # Append manual additions
179+ cat /tmp/manual_additions.txt >> "$temp_file"
180+ rm /tmp/manual_additions.txt "$temp_file.bak"
181+ fi
182+ fi
183+
184+ # Move temp file to final location
185+ mv "$temp_file" "$target_file"
186+ echo "✅ $agent_name context file updated successfully"
187+}
188+
189+# Update files based on argument or detect existing files
190+case "$AGENT_TYPE" in
191+ "claude")
192+ update_agent_file "$CLAUDE_FILE" "Claude Code"
193+ ;;
194+ "gemini")
195+ update_agent_file "$GEMINI_FILE" "Gemini CLI"
196+ ;;
197+ "copilot")
198+ update_agent_file "$COPILOT_FILE" "GitHub Copilot"
199+ ;;
200+ "")
201+ # Update all existing files
202+ [ -f "$CLAUDE_FILE" ] && update_agent_file "$CLAUDE_FILE" "Claude Code"
203+ [ -f "$GEMINI_FILE" ] && update_agent_file "$GEMINI_FILE" "Gemini CLI"
204+ [ -f "$COPILOT_FILE" ] && update_agent_file "$COPILOT_FILE" "GitHub Copilot"
205+
206+ # If no files exist, create based on current directory or ask user
207+ if [ ! -f "$CLAUDE_FILE" ] && [ ! -f "$GEMINI_FILE" ] && [ ! -f "$COPILOT_FILE" ]; then
208+ echo "No agent context files found. Creating Claude Code context file by default."
209+ update_agent_file "$CLAUDE_FILE" "Claude Code"
210+ fi
211+ ;;
212+ *)
213+ echo "ERROR: Unknown agent type '$AGENT_TYPE'. Use: claude, gemini, copilot, or leave empty for all."
214+ exit 1
215+ ;;
216+esac
217+echo ""
218+echo "Summary of changes:"
219+if [ ! -z "$NEW_LANG" ]; then
220+ echo "- Added language: $NEW_LANG"
221+fi
222+if [ ! -z "$NEW_FRAMEWORK" ]; then
223+ echo "- Added framework: $NEW_FRAMEWORK"
224+fi
225+if [ ! -z "$NEW_DB" ] && [ "$NEW_DB" != "N/A" ]; then
226+ echo "- Added database: $NEW_DB"
227+fi
228+
229+echo ""
230+echo "Usage: $0 [claude|gemini|copilot]"
231+echo " - No argument: Update all existing agent context files"
232+echo " - claude: Update only CLAUDE.md"
233+echo " - gemini: Update only GEMINI.md"
234+echo " - copilot: Update only .github/copilot-instructions.md"⏎̸
@@ -0,0 +1,234 @@
1+#!/usr/bin/env bash
2+# Incrementally update agent context files based on new feature plan
3+# Supports: CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md
4+# O(1) operation - only reads current context file and new plan.md
5+
6+set -e
7+
8+REPO_ROOT=$(git rev-parse --show-toplevel)
9+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
10+FEATURE_DIR="$REPO_ROOT/specs/$CURRENT_BRANCH"
11+NEW_PLAN="$FEATURE_DIR/plan.md"
12+
13+# Determine which agent context files to update
14+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
15+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
16+COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"
17+
18+# Allow override via argument
19+AGENT_TYPE="$1"
20+
21+if [ ! -f "$NEW_PLAN" ]; then
22+ echo "ERROR: No plan.md found at $NEW_PLAN"
23+ exit 1
24+fi
25+
26+echo "=== Updating agent context files for feature $CURRENT_BRANCH ==="
27+
28+# Extract tech from new plan
29+NEW_LANG=$(grep "^**Language/Version**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Language\/Version**: //' | grep -v "NEEDS CLARIFICATION" || echo "")
30+NEW_FRAMEWORK=$(grep "^**Primary Dependencies**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Primary Dependencies**: //' | grep -v "NEEDS CLARIFICATION" || echo "")
31+NEW_TESTING=$(grep "^**Testing**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Testing**: //' | grep -v "NEEDS CLARIFICATION" || echo "")
32+NEW_DB=$(grep "^**Storage**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Storage**: //' | grep -v "N/A" | grep -v "NEEDS CLARIFICATION" || echo "")
33+NEW_PROJECT_TYPE=$(grep "^**Project Type**: " "$NEW_PLAN" 2>/dev/null | head -1 | sed 's/^**Project Type**: //' || echo "")
34+
35+# Function to update a single agent context file
36+update_agent_file() {
37+ local target_file="$1"
38+ local agent_name="$2"
39+
40+ echo "Updating $agent_name context file: $target_file"
41+
42+ # Create temp file for new context
43+ local temp_file=$(mktemp)
44+
45+ # If file doesn't exist, create from template
46+ if [ ! -f "$target_file" ]; then
47+ echo "Creating new $agent_name context file..."
48+
49+ # Check if this is the SDD repo itself
50+ if [ -f "$REPO_ROOT/templates/agent-file-template.md" ]; then
51+ cp "$REPO_ROOT/templates/agent-file-template.md" "$temp_file"
52+ else
53+ echo "ERROR: Template not found at $REPO_ROOT/templates/agent-file-template.md"
54+ return 1
55+ fi
56+
57+ # Replace placeholders
58+ sed -i.bak "s/\[PROJECT NAME\]/$(basename $REPO_ROOT)/" "$temp_file"
59+ sed -i.bak "s/\[DATE\]/$(date +%Y-%m-%d)/" "$temp_file"
60+ sed -i.bak "s/\[EXTRACTED FROM ALL PLAN.MD FILES\]/- $NEW_LANG + $NEW_FRAMEWORK ($CURRENT_BRANCH)/" "$temp_file"
61+
62+ # Add project structure based on type
63+ if [[ "$NEW_PROJECT_TYPE" == *"web"* ]]; then
64+ sed -i.bak "s|\[ACTUAL STRUCTURE FROM PLANS\]|backend/\nfrontend/\ntests/|" "$temp_file"
65+ else
66+ sed -i.bak "s|\[ACTUAL STRUCTURE FROM PLANS\]|src/\ntests/|" "$temp_file"
67+ fi
68+
69+ # Add minimal commands
70+ if [[ "$NEW_LANG" == *"Python"* ]]; then
71+ COMMANDS="cd src && pytest && ruff check ."
72+ elif [[ "$NEW_LANG" == *"Rust"* ]]; then
73+ COMMANDS="cargo test && cargo clippy"
74+ elif [[ "$NEW_LANG" == *"JavaScript"* ]] || [[ "$NEW_LANG" == *"TypeScript"* ]]; then
75+ COMMANDS="npm test && npm run lint"
76+ else
77+ COMMANDS="# Add commands for $NEW_LANG"
78+ fi
79+ sed -i.bak "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$COMMANDS|" "$temp_file"
80+
81+ # Add code style
82+ sed -i.bak "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$NEW_LANG: Follow standard conventions|" "$temp_file"
83+
84+ # Add recent changes
85+ sed -i.bak "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|- $CURRENT_BRANCH: Added $NEW_LANG + $NEW_FRAMEWORK|" "$temp_file"
86+
87+ rm "$temp_file.bak"
88+ else
89+ echo "Updating existing $agent_name context file..."
90+
91+ # Extract manual additions
92+ local manual_start=$(grep -n "<!-- MANUAL ADDITIONS START -->" "$target_file" | cut -d: -f1)
93+ local manual_end=$(grep -n "<!-- MANUAL ADDITIONS END -->" "$target_file" | cut -d: -f1)
94+
95+ if [ ! -z "$manual_start" ] && [ ! -z "$manual_end" ]; then
96+ sed -n "${manual_start},${manual_end}p" "$target_file" > /tmp/manual_additions.txt
97+ fi
98+
99+ # Parse existing file and create updated version
100+ python3 - << EOF
101+import re
102+import sys
103+from datetime import datetime
104+
105+# Read existing file
106+with open("$target_file", 'r') as f:
107+ content = f.read()
108+
109+# Check if new tech already exists
110+tech_section = re.search(r'## Active Technologies\n(.*?)\n\n', content, re.DOTALL)
111+if tech_section:
112+ existing_tech = tech_section.group(1)
113+
114+ # Add new tech if not already present
115+ new_additions = []
116+ if "$NEW_LANG" and "$NEW_LANG" not in existing_tech:
117+ new_additions.append(f"- $NEW_LANG + $NEW_FRAMEWORK ($CURRENT_BRANCH)")
118+ if "$NEW_DB" and "$NEW_DB" not in existing_tech and "$NEW_DB" != "N/A":
119+ new_additions.append(f"- $NEW_DB ($CURRENT_BRANCH)")
120+
121+ if new_additions:
122+ updated_tech = existing_tech + "\n" + "\n".join(new_additions)
123+ content = content.replace(tech_section.group(0), f"## Active Technologies\n{updated_tech}\n\n")
124+
125+# Update project structure if needed
126+if "$NEW_PROJECT_TYPE" == "web" and "frontend/" not in content:
127+ struct_section = re.search(r'## Project Structure\n\`\`\`\n(.*?)\n\`\`\`', content, re.DOTALL)
128+ if struct_section:
129+ updated_struct = struct_section.group(1) + "\nfrontend/src/ # Web UI"
130+ content = re.sub(r'(## Project Structure\n\`\`\`\n).*?(\n\`\`\`)',
131+ f'\\1{updated_struct}\\2', content, flags=re.DOTALL)
132+
133+# Add new commands if language is new
134+if "$NEW_LANG" and f"# {NEW_LANG}" not in content:
135+ commands_section = re.search(r'## Commands\n\`\`\`bash\n(.*?)\n\`\`\`', content, re.DOTALL)
136+ if not commands_section:
137+ commands_section = re.search(r'## Commands\n(.*?)\n\n', content, re.DOTALL)
138+
139+ if commands_section:
140+ new_commands = commands_section.group(1)
141+ if "Python" in "$NEW_LANG":
142+ new_commands += "\ncd src && pytest && ruff check ."
143+ elif "Rust" in "$NEW_LANG":
144+ new_commands += "\ncargo test && cargo clippy"
145+ elif "JavaScript" in "$NEW_LANG" or "TypeScript" in "$NEW_LANG":
146+ new_commands += "\nnpm test && npm run lint"
147+
148+ if "```bash" in content:
149+ content = re.sub(r'(## Commands\n\`\`\`bash\n).*?(\n\`\`\`)',
150+ f'\\1{new_commands}\\2', content, flags=re.DOTALL)
151+ else:
152+ content = re.sub(r'(## Commands\n).*?(\n\n)',
153+ f'\\1{new_commands}\\2', content, flags=re.DOTALL)
154+
155+# Update recent changes (keep only last 3)
156+changes_section = re.search(r'## Recent Changes\n(.*?)(\n\n|$)', content, re.DOTALL)
157+if changes_section:
158+ changes = changes_section.group(1).strip().split('\n')
159+ changes.insert(0, f"- $CURRENT_BRANCH: Added $NEW_LANG + $NEW_FRAMEWORK")
160+ # Keep only last 3
161+ changes = changes[:3]
162+ content = re.sub(r'(## Recent Changes\n).*?(\n\n|$)',
163+ f'\\1{chr(10).join(changes)}\\2', content, flags=re.DOTALL)
164+
165+# Update date
166+content = re.sub(r'Last updated: \d{4}-\d{2}-\d{2}',
167+ f'Last updated: {datetime.now().strftime("%Y-%m-%d")}', content)
168+
169+# Write to temp file
170+with open("$temp_file", 'w') as f:
171+ f.write(content)
172+EOF
173+
174+ # Restore manual additions if they exist
175+ if [ -f /tmp/manual_additions.txt ]; then
176+ # Remove old manual section from temp file
177+ sed -i.bak '/<!-- MANUAL ADDITIONS START -->/,/<!-- MANUAL ADDITIONS END -->/d' "$temp_file"
178+ # Append manual additions
179+ cat /tmp/manual_additions.txt >> "$temp_file"
180+ rm /tmp/manual_additions.txt "$temp_file.bak"
181+ fi
182+ fi
183+
184+ # Move temp file to final location
185+ mv "$temp_file" "$target_file"
186+ echo "✅ $agent_name context file updated successfully"
187+}
188+
189+# Update files based on argument or detect existing files
190+case "$AGENT_TYPE" in
191+ "claude")
192+ update_agent_file "$CLAUDE_FILE" "Claude Code"
193+ ;;
194+ "gemini")
195+ update_agent_file "$GEMINI_FILE" "Gemini CLI"
196+ ;;
197+ "copilot")
198+ update_agent_file "$COPILOT_FILE" "GitHub Copilot"
199+ ;;
200+ "")
201+ # Update all existing files
202+ [ -f "$CLAUDE_FILE" ] && update_agent_file "$CLAUDE_FILE" "Claude Code"
203+ [ -f "$GEMINI_FILE" ] && update_agent_file "$GEMINI_FILE" "Gemini CLI"
204+ [ -f "$COPILOT_FILE" ] && update_agent_file "$COPILOT_FILE" "GitHub Copilot"
205+
206+ # If no files exist, create based on current directory or ask user
207+ if [ ! -f "$CLAUDE_FILE" ] && [ ! -f "$GEMINI_FILE" ] && [ ! -f "$COPILOT_FILE" ]; then
208+ echo "No agent context files found. Creating Claude Code context file by default."
209+ update_agent_file "$CLAUDE_FILE" "Claude Code"
210+ fi
211+ ;;
212+ *)
213+ echo "ERROR: Unknown agent type '$AGENT_TYPE'. Use: claude, gemini, copilot, or leave empty for all."
214+ exit 1
215+ ;;
216+esac
217+echo ""
218+echo "Summary of changes:"
219+if [ ! -z "$NEW_LANG" ]; then
220+ echo "- Added language: $NEW_LANG"
221+fi
222+if [ ! -z "$NEW_FRAMEWORK" ]; then
223+ echo "- Added framework: $NEW_FRAMEWORK"
224+fi
225+if [ ! -z "$NEW_DB" ] && [ "$NEW_DB" != "N/A" ]; then
226+ echo "- Added database: $NEW_DB"
227+fi
228+
229+echo ""
230+echo "Usage: $0 [claude|gemini|copilot]"
231+echo " - No argument: Update all existing agent context files"
232+echo " - claude: Update only CLAUDE.md"
233+echo " - gemini: Update only GEMINI.md"
234+echo " - copilot: Update only .github/copilot-instructions.md"⏎̸
A templates/agent-file-template.md +23 -0
@@ -0,0 +1,23 @@
1+# [PROJECT NAME] Development Guidelines
2+
3+Auto-generated from all feature plans. Last updated: [DATE]
4+
5+## Active Technologies
6+[EXTRACTED FROM ALL PLAN.MD FILES]
7+
8+## Project Structure
9+```
10+[ACTUAL STRUCTURE FROM PLANS]
11+```
12+
13+## Commands
14+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
15+
16+## Code Style
17+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
18+
19+## Recent Changes
20+[LAST 3 FEATURES AND WHAT THEY ADDED]
21+
22+<!-- MANUAL ADDITIONS START -->
23+<!-- MANUAL ADDITIONS END -->⏎̸
@@ -0,0 +1,23 @@
1+# [PROJECT NAME] Development Guidelines
2+
3+Auto-generated from all feature plans. Last updated: [DATE]
4+
5+## Active Technologies
6+[EXTRACTED FROM ALL PLAN.MD FILES]
7+
8+## Project Structure
9+```
10+[ACTUAL STRUCTURE FROM PLANS]
11+```
12+
13+## Commands
14+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
15+
16+## Code Style
17+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
18+
19+## Recent Changes
20+[LAST 3 FEATURES AND WHAT THEY ADDED]
21+
22+<!-- MANUAL ADDITIONS START -->
23+<!-- MANUAL ADDITIONS END -->⏎̸
A templates/plan-template.md +237 -0
@@ -0,0 +1,237 @@
1+# Implementation Plan: [FEATURE]
2+
3+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
4+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
5+
6+## Execution Flow (/plan command scope)
7+```
8+1. Load feature spec from Input path
9+ → If not found: ERROR "No feature spec at {path}"
10+2. Fill Technical Context (scan for NEEDS CLARIFICATION)
11+ → Detect Project Type from context (web=frontend+backend, mobile=app+api)
12+ → Set Structure Decision based on project type
13+3. Evaluate Constitution Check section below
14+ → If violations exist: Document in Complexity Tracking
15+ → If no justification possible: ERROR "Simplify approach first"
16+ → Update Progress Tracking: Initial Constitution Check
17+4. Execute Phase 0 → research.md
18+ → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
19+5. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
20+6. Re-evaluate Constitution Check section
21+ → If new violations: Refactor design, return to Phase 1
22+ → Update Progress Tracking: Post-Design Constitution Check
23+7. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
24+8. STOP - Ready for /tasks command
25+```
26+
27+**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
28+- Phase 2: /tasks command creates tasks.md
29+- Phase 3-4: Implementation execution (manual or via tools)
30+
31+## Summary
32+[Extract from feature spec: primary requirement + technical approach from research]
33+
34+## Technical Context
35+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
36+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
37+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
38+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
39+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
40+**Project Type**: [single/web/mobile - determines source structure]
41+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
42+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
43+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
44+
45+## Constitution Check
46+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
47+
48+**Simplicity**:
49+- Projects: [#] (max 3 - e.g., api, cli, tests)
50+- Using framework directly? (no wrapper classes)
51+- Single data model? (no DTOs unless serialization differs)
52+- Avoiding patterns? (no Repository/UoW without proven need)
53+
54+**Architecture**:
55+- EVERY feature as library? (no direct app code)
56+- Libraries listed: [name + purpose for each]
57+- CLI per library: [commands with --help/--version/--format]
58+- Library docs: llms.txt format planned?
59+
60+**Testing (NON-NEGOTIABLE)**:
61+- RED-GREEN-Refactor cycle enforced? (test MUST fail first)
62+- Git commits show tests before implementation?
63+- Order: Contract→Integration→E2E→Unit strictly followed?
64+- Real dependencies used? (actual DBs, not mocks)
65+- Integration tests for: new libraries, contract changes, shared schemas?
66+- FORBIDDEN: Implementation before test, skipping RED phase
67+
68+**Observability**:
69+- Structured logging included?
70+- Frontend logs → backend? (unified stream)
71+- Error context sufficient?
72+
73+**Versioning**:
74+- Version number assigned? (MAJOR.MINOR.BUILD)
75+- BUILD increments on every change?
76+- Breaking changes handled? (parallel tests, migration plan)
77+
78+## Project Structure
79+
80+### Documentation (this feature)
81+```
82+specs/[###-feature]/
83+├── plan.md # This file (/plan command output)
84+├── research.md # Phase 0 output (/plan command)
85+├── data-model.md # Phase 1 output (/plan command)
86+├── quickstart.md # Phase 1 output (/plan command)
87+├── contracts/ # Phase 1 output (/plan command)
88+└── tasks.md # Phase 2 output (/tasks command - NOT created by /plan)
89+```
90+
91+### Source Code (repository root)
92+```
93+# Option 1: Single project (DEFAULT)
94+src/
95+├── models/
96+├── services/
97+├── cli/
98+└── lib/
99+
100+tests/
101+├── contract/
102+├── integration/
103+└── unit/
104+
105+# Option 2: Web application (when "frontend" + "backend" detected)
106+backend/
107+├── src/
108+│ ├── models/
109+│ ├── services/
110+│ └── api/
111+└── tests/
112+
113+frontend/
114+├── src/
115+│ ├── components/
116+│ ├── pages/
117+│ └── services/
118+└── tests/
119+
120+# Option 3: Mobile + API (when "iOS/Android" detected)
121+api/
122+└── [same as backend above]
123+
124+ios/ or android/
125+└── [platform-specific structure]
126+```
127+
128+**Structure Decision**: [DEFAULT to Option 1 unless Technical Context indicates web/mobile app]
129+
130+## Phase 0: Outline & Research
131+1. **Extract unknowns from Technical Context** above:
132+ - For each NEEDS CLARIFICATION → research task
133+ - For each dependency → best practices task
134+ - For each integration → patterns task
135+
136+2. **Generate and dispatch research agents**:
137+ ```
138+ For each unknown in Technical Context:
139+ Task: "Research {unknown} for {feature context}"
140+ For each technology choice:
141+ Task: "Find best practices for {tech} in {domain}"
142+ ```
143+
144+3. **Consolidate findings** in `research.md` using format:
145+ - Decision: [what was chosen]
146+ - Rationale: [why chosen]
147+ - Alternatives considered: [what else evaluated]
148+
149+**Output**: research.md with all NEEDS CLARIFICATION resolved
150+
151+## Phase 1: Design & Contracts
152+*Prerequisites: research.md complete*
153+
154+1. **Extract entities from feature spec** → `data-model.md`:
155+ - Entity name, fields, relationships
156+ - Validation rules from requirements
157+ - State transitions if applicable
158+
159+2. **Generate API contracts** from functional requirements:
160+ - For each user action → endpoint
161+ - Use standard REST/GraphQL patterns
162+ - Output OpenAPI/GraphQL schema to `/contracts/`
163+
164+3. **Generate contract tests** from contracts:
165+ - One test file per endpoint
166+ - Assert request/response schemas
167+ - Tests must fail (no implementation yet)
168+
169+4. **Extract test scenarios** from user stories:
170+ - Each story → integration test scenario
171+ - Quickstart test = story validation steps
172+
173+5. **Update agent file incrementally** (O(1) operation):
174+ - Run `/scripts/update-agent-context.sh [claude|gemini|copilot]` for your AI assistant
175+ - If exists: Add only NEW tech from current plan
176+ - Preserve manual additions between markers
177+ - Update recent changes (keep last 3)
178+ - Keep under 150 lines for token efficiency
179+ - Output to repository root
180+
181+**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
182+
183+## Phase 2: Task Planning Approach
184+*This section describes what the /tasks command will do - DO NOT execute during /plan*
185+
186+**Task Generation Strategy**:
187+- Load `/templates/tasks-template.md` as base
188+- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
189+- Each contract → contract test task [P]
190+- Each entity → model creation task [P]
191+- Each user story → integration test task
192+- Implementation tasks to make tests pass
193+
194+**Ordering Strategy**:
195+- TDD order: Tests before implementation
196+- Dependency order: Models before services before UI
197+- Mark [P] for parallel execution (independent files)
198+
199+**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md
200+
201+**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
202+
203+## Phase 3+: Future Implementation
204+*These phases are beyond the scope of the /plan command*
205+
206+**Phase 3**: Task execution (/tasks command creates tasks.md)
207+**Phase 4**: Implementation (execute tasks.md following constitutional principles)
208+**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
209+
210+## Complexity Tracking
211+*Fill ONLY if Constitution Check has violations that must be justified*
212+
213+| Violation | Why Needed | Simpler Alternative Rejected Because |
214+|-----------|------------|-------------------------------------|
215+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
216+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
217+
218+
219+## Progress Tracking
220+*This checklist is updated during execution flow*
221+
222+**Phase Status**:
223+- [ ] Phase 0: Research complete (/plan command)
224+- [ ] Phase 1: Design complete (/plan command)
225+- [ ] Phase 2: Task planning complete (/plan command - describe approach only)
226+- [ ] Phase 3: Tasks generated (/tasks command)
227+- [ ] Phase 4: Implementation complete
228+- [ ] Phase 5: Validation passed
229+
230+**Gate Status**:
231+- [ ] Initial Constitution Check: PASS
232+- [ ] Post-Design Constitution Check: PASS
233+- [ ] All NEEDS CLARIFICATION resolved
234+- [ ] Complexity deviations documented
235+
236+---
237+*Based on Constitution v2.1.1 - See `/memory/constitution.md`*⏎̸
@@ -0,0 +1,237 @@
1+# Implementation Plan: [FEATURE]
2+
3+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
4+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
5+
6+## Execution Flow (/plan command scope)
7+```
8+1. Load feature spec from Input path
9+ → If not found: ERROR "No feature spec at {path}"
10+2. Fill Technical Context (scan for NEEDS CLARIFICATION)
11+ → Detect Project Type from context (web=frontend+backend, mobile=app+api)
12+ → Set Structure Decision based on project type
13+3. Evaluate Constitution Check section below
14+ → If violations exist: Document in Complexity Tracking
15+ → If no justification possible: ERROR "Simplify approach first"
16+ → Update Progress Tracking: Initial Constitution Check
17+4. Execute Phase 0 → research.md
18+ → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
19+5. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
20+6. Re-evaluate Constitution Check section
21+ → If new violations: Refactor design, return to Phase 1
22+ → Update Progress Tracking: Post-Design Constitution Check
23+7. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
24+8. STOP - Ready for /tasks command
25+```
26+
27+**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
28+- Phase 2: /tasks command creates tasks.md
29+- Phase 3-4: Implementation execution (manual or via tools)
30+
31+## Summary
32+[Extract from feature spec: primary requirement + technical approach from research]
33+
34+## Technical Context
35+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
36+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
37+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
38+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
39+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
40+**Project Type**: [single/web/mobile - determines source structure]
41+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
42+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
43+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
44+
45+## Constitution Check
46+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
47+
48+**Simplicity**:
49+- Projects: [#] (max 3 - e.g., api, cli, tests)
50+- Using framework directly? (no wrapper classes)
51+- Single data model? (no DTOs unless serialization differs)
52+- Avoiding patterns? (no Repository/UoW without proven need)
53+
54+**Architecture**:
55+- EVERY feature as library? (no direct app code)
56+- Libraries listed: [name + purpose for each]
57+- CLI per library: [commands with --help/--version/--format]
58+- Library docs: llms.txt format planned?
59+
60+**Testing (NON-NEGOTIABLE)**:
61+- RED-GREEN-Refactor cycle enforced? (test MUST fail first)
62+- Git commits show tests before implementation?
63+- Order: Contract→Integration→E2E→Unit strictly followed?
64+- Real dependencies used? (actual DBs, not mocks)
65+- Integration tests for: new libraries, contract changes, shared schemas?
66+- FORBIDDEN: Implementation before test, skipping RED phase
67+
68+**Observability**:
69+- Structured logging included?
70+- Frontend logs → backend? (unified stream)
71+- Error context sufficient?
72+
73+**Versioning**:
74+- Version number assigned? (MAJOR.MINOR.BUILD)
75+- BUILD increments on every change?
76+- Breaking changes handled? (parallel tests, migration plan)
77+
78+## Project Structure
79+
80+### Documentation (this feature)
81+```
82+specs/[###-feature]/
83+├── plan.md # This file (/plan command output)
84+├── research.md # Phase 0 output (/plan command)
85+├── data-model.md # Phase 1 output (/plan command)
86+├── quickstart.md # Phase 1 output (/plan command)
87+├── contracts/ # Phase 1 output (/plan command)
88+└── tasks.md # Phase 2 output (/tasks command - NOT created by /plan)
89+```
90+
91+### Source Code (repository root)
92+```
93+# Option 1: Single project (DEFAULT)
94+src/
95+├── models/
96+├── services/
97+├── cli/
98+└── lib/
99+
100+tests/
101+├── contract/
102+├── integration/
103+└── unit/
104+
105+# Option 2: Web application (when "frontend" + "backend" detected)
106+backend/
107+├── src/
108+│ ├── models/
109+│ ├── services/
110+│ └── api/
111+└── tests/
112+
113+frontend/
114+├── src/
115+│ ├── components/
116+│ ├── pages/
117+│ └── services/
118+└── tests/
119+
120+# Option 3: Mobile + API (when "iOS/Android" detected)
121+api/
122+└── [same as backend above]
123+
124+ios/ or android/
125+└── [platform-specific structure]
126+```
127+
128+**Structure Decision**: [DEFAULT to Option 1 unless Technical Context indicates web/mobile app]
129+
130+## Phase 0: Outline & Research
131+1. **Extract unknowns from Technical Context** above:
132+ - For each NEEDS CLARIFICATION → research task
133+ - For each dependency → best practices task
134+ - For each integration → patterns task
135+
136+2. **Generate and dispatch research agents**:
137+ ```
138+ For each unknown in Technical Context:
139+ Task: "Research {unknown} for {feature context}"
140+ For each technology choice:
141+ Task: "Find best practices for {tech} in {domain}"
142+ ```
143+
144+3. **Consolidate findings** in `research.md` using format:
145+ - Decision: [what was chosen]
146+ - Rationale: [why chosen]
147+ - Alternatives considered: [what else evaluated]
148+
149+**Output**: research.md with all NEEDS CLARIFICATION resolved
150+
151+## Phase 1: Design & Contracts
152+*Prerequisites: research.md complete*
153+
154+1. **Extract entities from feature spec** → `data-model.md`:
155+ - Entity name, fields, relationships
156+ - Validation rules from requirements
157+ - State transitions if applicable
158+
159+2. **Generate API contracts** from functional requirements:
160+ - For each user action → endpoint
161+ - Use standard REST/GraphQL patterns
162+ - Output OpenAPI/GraphQL schema to `/contracts/`
163+
164+3. **Generate contract tests** from contracts:
165+ - One test file per endpoint
166+ - Assert request/response schemas
167+ - Tests must fail (no implementation yet)
168+
169+4. **Extract test scenarios** from user stories:
170+ - Each story → integration test scenario
171+ - Quickstart test = story validation steps
172+
173+5. **Update agent file incrementally** (O(1) operation):
174+ - Run `/scripts/update-agent-context.sh [claude|gemini|copilot]` for your AI assistant
175+ - If exists: Add only NEW tech from current plan
176+ - Preserve manual additions between markers
177+ - Update recent changes (keep last 3)
178+ - Keep under 150 lines for token efficiency
179+ - Output to repository root
180+
181+**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
182+
183+## Phase 2: Task Planning Approach
184+*This section describes what the /tasks command will do - DO NOT execute during /plan*
185+
186+**Task Generation Strategy**:
187+- Load `/templates/tasks-template.md` as base
188+- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
189+- Each contract → contract test task [P]
190+- Each entity → model creation task [P]
191+- Each user story → integration test task
192+- Implementation tasks to make tests pass
193+
194+**Ordering Strategy**:
195+- TDD order: Tests before implementation
196+- Dependency order: Models before services before UI
197+- Mark [P] for parallel execution (independent files)
198+
199+**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md
200+
201+**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
202+
203+## Phase 3+: Future Implementation
204+*These phases are beyond the scope of the /plan command*
205+
206+**Phase 3**: Task execution (/tasks command creates tasks.md)
207+**Phase 4**: Implementation (execute tasks.md following constitutional principles)
208+**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
209+
210+## Complexity Tracking
211+*Fill ONLY if Constitution Check has violations that must be justified*
212+
213+| Violation | Why Needed | Simpler Alternative Rejected Because |
214+|-----------|------------|-------------------------------------|
215+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
216+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
217+
218+
219+## Progress Tracking
220+*This checklist is updated during execution flow*
221+
222+**Phase Status**:
223+- [ ] Phase 0: Research complete (/plan command)
224+- [ ] Phase 1: Design complete (/plan command)
225+- [ ] Phase 2: Task planning complete (/plan command - describe approach only)
226+- [ ] Phase 3: Tasks generated (/tasks command)
227+- [ ] Phase 4: Implementation complete
228+- [ ] Phase 5: Validation passed
229+
230+**Gate Status**:
231+- [ ] Initial Constitution Check: PASS
232+- [ ] Post-Design Constitution Check: PASS
233+- [ ] All NEEDS CLARIFICATION resolved
234+- [ ] Complexity deviations documented
235+
236+---
237+*Based on Constitution v2.1.1 - See `/memory/constitution.md`*⏎̸
A templates/spec-template.md +116 -0
@@ -0,0 +1,116 @@
1+# Feature Specification: [FEATURE NAME]
2+
3+**Feature Branch**: `[###-feature-name]`
4+**Created**: [DATE]
5+**Status**: Draft
6+**Input**: User description: "$ARGUMENTS"
7+
8+## Execution Flow (main)
9+```
10+1. Parse user description from Input
11+ → If empty: ERROR "No feature description provided"
12+2. Extract key concepts from description
13+ → Identify: actors, actions, data, constraints
14+3. For each unclear aspect:
15+ → Mark with [NEEDS CLARIFICATION: specific question]
16+4. Fill User Scenarios & Testing section
17+ → If no clear user flow: ERROR "Cannot determine user scenarios"
18+5. Generate Functional Requirements
19+ → Each requirement must be testable
20+ → Mark ambiguous requirements
21+6. Identify Key Entities (if data involved)
22+7. Run Review Checklist
23+ → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
24+ → If implementation details found: ERROR "Remove tech details"
25+8. Return: SUCCESS (spec ready for planning)
26+```
27+
28+---
29+
30+## ⚡ Quick Guidelines
31+- ✅ Focus on WHAT users need and WHY
32+- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
33+- 👥 Written for business stakeholders, not developers
34+
35+### Section Requirements
36+- **Mandatory sections**: Must be completed for every feature
37+- **Optional sections**: Include only when relevant to the feature
38+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
39+
40+### For AI Generation
41+When creating this spec from a user prompt:
42+1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
43+2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
44+3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
45+4. **Common underspecified areas**:
46+ - User types and permissions
47+ - Data retention/deletion policies
48+ - Performance targets and scale
49+ - Error handling behaviors
50+ - Integration requirements
51+ - Security/compliance needs
52+
53+---
54+
55+## User Scenarios & Testing *(mandatory)*
56+
57+### Primary User Story
58+[Describe the main user journey in plain language]
59+
60+### Acceptance Scenarios
61+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
62+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
63+
64+### Edge Cases
65+- What happens when [boundary condition]?
66+- How does system handle [error scenario]?
67+
68+## Requirements *(mandatory)*
69+
70+### Functional Requirements
71+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
72+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
73+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
74+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
75+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
76+
77+*Example of marking unclear requirements:*
78+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
79+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
80+
81+### Key Entities *(include if feature involves data)*
82+- **[Entity 1]**: [What it represents, key attributes without implementation]
83+- **[Entity 2]**: [What it represents, relationships to other entities]
84+
85+---
86+
87+## Review & Acceptance Checklist
88+*GATE: Automated checks run during main() execution*
89+
90+### Content Quality
91+- [ ] No implementation details (languages, frameworks, APIs)
92+- [ ] Focused on user value and business needs
93+- [ ] Written for non-technical stakeholders
94+- [ ] All mandatory sections completed
95+
96+### Requirement Completeness
97+- [ ] No [NEEDS CLARIFICATION] markers remain
98+- [ ] Requirements are testable and unambiguous
99+- [ ] Success criteria are measurable
100+- [ ] Scope is clearly bounded
101+- [ ] Dependencies and assumptions identified
102+
103+---
104+
105+## Execution Status
106+*Updated by main() during processing*
107+
108+- [ ] User description parsed
109+- [ ] Key concepts extracted
110+- [ ] Ambiguities marked
111+- [ ] User scenarios defined
112+- [ ] Requirements generated
113+- [ ] Entities identified
114+- [ ] Review checklist passed
115+
116+---
@@ -0,0 +1,116 @@
1+# Feature Specification: [FEATURE NAME]
2+
3+**Feature Branch**: `[###-feature-name]`
4+**Created**: [DATE]
5+**Status**: Draft
6+**Input**: User description: "$ARGUMENTS"
7+
8+## Execution Flow (main)
9+```
10+1. Parse user description from Input
11+ → If empty: ERROR "No feature description provided"
12+2. Extract key concepts from description
13+ → Identify: actors, actions, data, constraints
14+3. For each unclear aspect:
15+ → Mark with [NEEDS CLARIFICATION: specific question]
16+4. Fill User Scenarios & Testing section
17+ → If no clear user flow: ERROR "Cannot determine user scenarios"
18+5. Generate Functional Requirements
19+ → Each requirement must be testable
20+ → Mark ambiguous requirements
21+6. Identify Key Entities (if data involved)
22+7. Run Review Checklist
23+ → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
24+ → If implementation details found: ERROR "Remove tech details"
25+8. Return: SUCCESS (spec ready for planning)
26+```
27+
28+---
29+
30+## ⚡ Quick Guidelines
31+- ✅ Focus on WHAT users need and WHY
32+- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
33+- 👥 Written for business stakeholders, not developers
34+
35+### Section Requirements
36+- **Mandatory sections**: Must be completed for every feature
37+- **Optional sections**: Include only when relevant to the feature
38+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
39+
40+### For AI Generation
41+When creating this spec from a user prompt:
42+1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
43+2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
44+3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
45+4. **Common underspecified areas**:
46+ - User types and permissions
47+ - Data retention/deletion policies
48+ - Performance targets and scale
49+ - Error handling behaviors
50+ - Integration requirements
51+ - Security/compliance needs
52+
53+---
54+
55+## User Scenarios & Testing *(mandatory)*
56+
57+### Primary User Story
58+[Describe the main user journey in plain language]
59+
60+### Acceptance Scenarios
61+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
62+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
63+
64+### Edge Cases
65+- What happens when [boundary condition]?
66+- How does system handle [error scenario]?
67+
68+## Requirements *(mandatory)*
69+
70+### Functional Requirements
71+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
72+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
73+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
74+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
75+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
76+
77+*Example of marking unclear requirements:*
78+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
79+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
80+
81+### Key Entities *(include if feature involves data)*
82+- **[Entity 1]**: [What it represents, key attributes without implementation]
83+- **[Entity 2]**: [What it represents, relationships to other entities]
84+
85+---
86+
87+## Review & Acceptance Checklist
88+*GATE: Automated checks run during main() execution*
89+
90+### Content Quality
91+- [ ] No implementation details (languages, frameworks, APIs)
92+- [ ] Focused on user value and business needs
93+- [ ] Written for non-technical stakeholders
94+- [ ] All mandatory sections completed
95+
96+### Requirement Completeness
97+- [ ] No [NEEDS CLARIFICATION] markers remain
98+- [ ] Requirements are testable and unambiguous
99+- [ ] Success criteria are measurable
100+- [ ] Scope is clearly bounded
101+- [ ] Dependencies and assumptions identified
102+
103+---
104+
105+## Execution Status
106+*Updated by main() during processing*
107+
108+- [ ] User description parsed
109+- [ ] Key concepts extracted
110+- [ ] Ambiguities marked
111+- [ ] User scenarios defined
112+- [ ] Requirements generated
113+- [ ] Entities identified
114+- [ ] Review checklist passed
115+
116+---
A templates/tasks-template.md +127 -0
@@ -0,0 +1,127 @@
1+# Tasks: [FEATURE NAME]
2+
3+**Input**: Design documents from `/specs/[###-feature-name]/`
4+**Prerequisites**: plan.md (required), research.md, data-model.md, contracts/
5+
6+## Execution Flow (main)
7+```
8+1. Load plan.md from feature directory
9+ → If not found: ERROR "No implementation plan found"
10+ → Extract: tech stack, libraries, structure
11+2. Load optional design documents:
12+ → data-model.md: Extract entities → model tasks
13+ → contracts/: Each file → contract test task
14+ → research.md: Extract decisions → setup tasks
15+3. Generate tasks by category:
16+ → Setup: project init, dependencies, linting
17+ → Tests: contract tests, integration tests
18+ → Core: models, services, CLI commands
19+ → Integration: DB, middleware, logging
20+ → Polish: unit tests, performance, docs
21+4. Apply task rules:
22+ → Different files = mark [P] for parallel
23+ → Same file = sequential (no [P])
24+ → Tests before implementation (TDD)
25+5. Number tasks sequentially (T001, T002...)
26+6. Generate dependency graph
27+7. Create parallel execution examples
28+8. Validate task completeness:
29+ → All contracts have tests?
30+ → All entities have models?
31+ → All endpoints implemented?
32+9. Return: SUCCESS (tasks ready for execution)
33+```
34+
35+## Format: `[ID] [P?] Description`
36+- **[P]**: Can run in parallel (different files, no dependencies)
37+- Include exact file paths in descriptions
38+
39+## Path Conventions
40+- **Single project**: `src/`, `tests/` at repository root
41+- **Web app**: `backend/src/`, `frontend/src/`
42+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
43+- Paths shown below assume single project - adjust based on plan.md structure
44+
45+## Phase 3.1: Setup
46+- [ ] T001 Create project structure per implementation plan
47+- [ ] T002 Initialize [language] project with [framework] dependencies
48+- [ ] T003 [P] Configure linting and formatting tools
49+
50+## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
51+**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**
52+- [ ] T004 [P] Contract test POST /api/users in tests/contract/test_users_post.py
53+- [ ] T005 [P] Contract test GET /api/users/{id} in tests/contract/test_users_get.py
54+- [ ] T006 [P] Integration test user registration in tests/integration/test_registration.py
55+- [ ] T007 [P] Integration test auth flow in tests/integration/test_auth.py
56+
57+## Phase 3.3: Core Implementation (ONLY after tests are failing)
58+- [ ] T008 [P] User model in src/models/user.py
59+- [ ] T009 [P] UserService CRUD in src/services/user_service.py
60+- [ ] T010 [P] CLI --create-user in src/cli/user_commands.py
61+- [ ] T011 POST /api/users endpoint
62+- [ ] T012 GET /api/users/{id} endpoint
63+- [ ] T013 Input validation
64+- [ ] T014 Error handling and logging
65+
66+## Phase 3.4: Integration
67+- [ ] T015 Connect UserService to DB
68+- [ ] T016 Auth middleware
69+- [ ] T017 Request/response logging
70+- [ ] T018 CORS and security headers
71+
72+## Phase 3.5: Polish
73+- [ ] T019 [P] Unit tests for validation in tests/unit/test_validation.py
74+- [ ] T020 Performance tests (<200ms)
75+- [ ] T021 [P] Update docs/api.md
76+- [ ] T022 Remove duplication
77+- [ ] T023 Run manual-testing.md
78+
79+## Dependencies
80+- Tests (T004-T007) before implementation (T008-T014)
81+- T008 blocks T009, T015
82+- T016 blocks T018
83+- Implementation before polish (T019-T023)
84+
85+## Parallel Example
86+```
87+# Launch T004-T007 together:
88+Task: "Contract test POST /api/users in tests/contract/test_users_post.py"
89+Task: "Contract test GET /api/users/{id} in tests/contract/test_users_get.py"
90+Task: "Integration test registration in tests/integration/test_registration.py"
91+Task: "Integration test auth in tests/integration/test_auth.py"
92+```
93+
94+## Notes
95+- [P] tasks = different files, no dependencies
96+- Verify tests fail before implementing
97+- Commit after each task
98+- Avoid: vague tasks, same file conflicts
99+
100+## Task Generation Rules
101+*Applied during main() execution*
102+
103+1. **From Contracts**:
104+ - Each contract file → contract test task [P]
105+ - Each endpoint → implementation task
106+
107+2. **From Data Model**:
108+ - Each entity → model creation task [P]
109+ - Relationships → service layer tasks
110+
111+3. **From User Stories**:
112+ - Each story → integration test [P]
113+ - Quickstart scenarios → validation tasks
114+
115+4. **Ordering**:
116+ - Setup → Tests → Models → Services → Endpoints → Polish
117+ - Dependencies block parallel execution
118+
119+## Validation Checklist
120+*GATE: Checked by main() before returning*
121+
122+- [ ] All contracts have corresponding tests
123+- [ ] All entities have model tasks
124+- [ ] All tests come before implementation
125+- [ ] Parallel tasks truly independent
126+- [ ] Each task specifies exact file path
127+- [ ] No task modifies same file as another [P] task⏎̸
@@ -0,0 +1,127 @@
1+# Tasks: [FEATURE NAME]
2+
3+**Input**: Design documents from `/specs/[###-feature-name]/`
4+**Prerequisites**: plan.md (required), research.md, data-model.md, contracts/
5+
6+## Execution Flow (main)
7+```
8+1. Load plan.md from feature directory
9+ → If not found: ERROR "No implementation plan found"
10+ → Extract: tech stack, libraries, structure
11+2. Load optional design documents:
12+ → data-model.md: Extract entities → model tasks
13+ → contracts/: Each file → contract test task
14+ → research.md: Extract decisions → setup tasks
15+3. Generate tasks by category:
16+ → Setup: project init, dependencies, linting
17+ → Tests: contract tests, integration tests
18+ → Core: models, services, CLI commands
19+ → Integration: DB, middleware, logging
20+ → Polish: unit tests, performance, docs
21+4. Apply task rules:
22+ → Different files = mark [P] for parallel
23+ → Same file = sequential (no [P])
24+ → Tests before implementation (TDD)
25+5. Number tasks sequentially (T001, T002...)
26+6. Generate dependency graph
27+7. Create parallel execution examples
28+8. Validate task completeness:
29+ → All contracts have tests?
30+ → All entities have models?
31+ → All endpoints implemented?
32+9. Return: SUCCESS (tasks ready for execution)
33+```
34+
35+## Format: `[ID] [P?] Description`
36+- **[P]**: Can run in parallel (different files, no dependencies)
37+- Include exact file paths in descriptions
38+
39+## Path Conventions
40+- **Single project**: `src/`, `tests/` at repository root
41+- **Web app**: `backend/src/`, `frontend/src/`
42+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
43+- Paths shown below assume single project - adjust based on plan.md structure
44+
45+## Phase 3.1: Setup
46+- [ ] T001 Create project structure per implementation plan
47+- [ ] T002 Initialize [language] project with [framework] dependencies
48+- [ ] T003 [P] Configure linting and formatting tools
49+
50+## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
51+**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**
52+- [ ] T004 [P] Contract test POST /api/users in tests/contract/test_users_post.py
53+- [ ] T005 [P] Contract test GET /api/users/{id} in tests/contract/test_users_get.py
54+- [ ] T006 [P] Integration test user registration in tests/integration/test_registration.py
55+- [ ] T007 [P] Integration test auth flow in tests/integration/test_auth.py
56+
57+## Phase 3.3: Core Implementation (ONLY after tests are failing)
58+- [ ] T008 [P] User model in src/models/user.py
59+- [ ] T009 [P] UserService CRUD in src/services/user_service.py
60+- [ ] T010 [P] CLI --create-user in src/cli/user_commands.py
61+- [ ] T011 POST /api/users endpoint
62+- [ ] T012 GET /api/users/{id} endpoint
63+- [ ] T013 Input validation
64+- [ ] T014 Error handling and logging
65+
66+## Phase 3.4: Integration
67+- [ ] T015 Connect UserService to DB
68+- [ ] T016 Auth middleware
69+- [ ] T017 Request/response logging
70+- [ ] T018 CORS and security headers
71+
72+## Phase 3.5: Polish
73+- [ ] T019 [P] Unit tests for validation in tests/unit/test_validation.py
74+- [ ] T020 Performance tests (<200ms)
75+- [ ] T021 [P] Update docs/api.md
76+- [ ] T022 Remove duplication
77+- [ ] T023 Run manual-testing.md
78+
79+## Dependencies
80+- Tests (T004-T007) before implementation (T008-T014)
81+- T008 blocks T009, T015
82+- T016 blocks T018
83+- Implementation before polish (T019-T023)
84+
85+## Parallel Example
86+```
87+# Launch T004-T007 together:
88+Task: "Contract test POST /api/users in tests/contract/test_users_post.py"
89+Task: "Contract test GET /api/users/{id} in tests/contract/test_users_get.py"
90+Task: "Integration test registration in tests/integration/test_registration.py"
91+Task: "Integration test auth in tests/integration/test_auth.py"
92+```
93+
94+## Notes
95+- [P] tasks = different files, no dependencies
96+- Verify tests fail before implementing
97+- Commit after each task
98+- Avoid: vague tasks, same file conflicts
99+
100+## Task Generation Rules
101+*Applied during main() execution*
102+
103+1. **From Contracts**:
104+ - Each contract file → contract test task [P]
105+ - Each endpoint → implementation task
106+
107+2. **From Data Model**:
108+ - Each entity → model creation task [P]
109+ - Relationships → service layer tasks
110+
111+3. **From User Stories**:
112+ - Each story → integration test [P]
113+ - Quickstart scenarios → validation tasks
114+
115+4. **Ordering**:
116+ - Setup → Tests → Models → Services → Endpoints → Polish
117+ - Dependencies block parallel execution
118+
119+## Validation Checklist
120+*GATE: Checked by main() before returning*
121+
122+- [ ] All contracts have corresponding tests
123+- [ ] All entities have model tasks
124+- [ ] All tests come before implementation
125+- [ ] Parallel tasks truly independent
126+- [ ] Each task specifies exact file path
127+- [ ] No task modifies same file as another [P] task⏎̸

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 8

Tags 42

↑↓ moveenter openesc close