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