From 2befb513a8c0a87c0031b7d721f77305f9e5ac95 Mon Sep 17 00:00:00 2001 From: Rogee Date: Fri, 19 Sep 2025 16:52:53 +0800 Subject: [PATCH] feat: add spec-kit --- .claude/commands/constitution.md | 68 ++++++ .claude/commands/implement.md | 52 +++++ .claude/commands/plan.md | 36 +++ .claude/commands/specify.md | 13 ++ .claude/commands/tasks.md | 58 +++++ .specify/memory/constitution.md | 50 +++++ .../check-implementation-prerequisites.sh | 16 ++ .../scripts/bash/check-task-prerequisites.sh | 15 ++ .specify/scripts/bash/common.sh | 37 +++ .specify/scripts/bash/create-new-feature.sh | 58 +++++ .specify/scripts/bash/get-feature-paths.sh | 7 + .specify/scripts/bash/setup-plan.sh | 17 ++ .specify/scripts/bash/update-agent-context.sh | 66 ++++++ .specify/templates/agent-file-template.md | 23 ++ .specify/templates/plan-template.md | 211 ++++++++++++++++++ .specify/templates/spec-template.md | 116 ++++++++++ .specify/templates/tasks-template.md | 127 +++++++++++ 17 files changed, 970 insertions(+) create mode 100644 .claude/commands/constitution.md create mode 100644 .claude/commands/implement.md create mode 100644 .claude/commands/plan.md create mode 100644 .claude/commands/specify.md create mode 100644 .claude/commands/tasks.md create mode 100644 .specify/memory/constitution.md create mode 100755 .specify/scripts/bash/check-implementation-prerequisites.sh create mode 100755 .specify/scripts/bash/check-task-prerequisites.sh create mode 100755 .specify/scripts/bash/common.sh create mode 100755 .specify/scripts/bash/create-new-feature.sh create mode 100755 .specify/scripts/bash/get-feature-paths.sh create mode 100755 .specify/scripts/bash/setup-plan.sh create mode 100755 .specify/scripts/bash/update-agent-context.sh create mode 100644 .specify/templates/agent-file-template.md create mode 100644 .specify/templates/plan-template.md create mode 100644 .specify/templates/spec-template.md create mode 100644 .specify/templates/tasks-template.md diff --git a/.claude/commands/constitution.md b/.claude/commands/constitution.md new file mode 100644 index 0000000..c5c66d0 --- /dev/null +++ b/.claude/commands/constitution.md @@ -0,0 +1,68 @@ +--- +description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync. +# (No scripts section: constitution edits are manual authoring assisted by the agent) +--- + +You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts. + +Follow this execution flow: + +1. Load the existing constitution template at `.specify/memory/constitution.md`. + - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`. + **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly. + +2. Collect/derive values for placeholders: + - If user input (conversation) supplies a value, use it. + - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded). + - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous. + - `CONSTITUTION_VERSION` must increment according to semantic versioning rules: + * MAJOR: Backward incompatible governance/principle removals or redefinitions. + * MINOR: New principle/section added or materially expanded guidance. + * PATCH: Clarifications, wording, typo fixes, non-semantic refinements. + - If version bump type ambiguous, propose reasoning before finalizing. + +3. Draft the updated constitution content: + - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left). + - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance. + - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious. + - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations. + +4. Consistency propagation checklist (convert prior checklist into active validations): + - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles. + - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints. + - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline). + - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required. + - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed. + +5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update): + - Version change: old → new + - List of modified principles (old title → new title if renamed) + - Added sections + - Removed sections + - Templates requiring updates (✅ updated / ⚠ pending) with file paths + - Follow-up TODOs if any placeholders intentionally deferred. + +6. Validation before final output: + - No remaining unexplained bracket tokens. + - Version line matches report. + - Dates ISO format YYYY-MM-DD. + - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate). + +7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite). + +8. Output a final summary to the user with: + - New version and bump rationale. + - Any files flagged for manual follow-up. + - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`). + +Formatting & Style Requirements: +- Use Markdown headings exactly as in the template (do not demote/promote levels). +- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks. +- Keep a single blank line between sections. +- Avoid trailing whitespace. + +If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps. + +If critical info missing (e.g., ratification date truly unknown), insert `TODO(): explanation` and include in the Sync Impact Report under deferred items. + +Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file. diff --git a/.claude/commands/implement.md b/.claude/commands/implement.md new file mode 100644 index 0000000..705edc2 --- /dev/null +++ b/.claude/commands/implement.md @@ -0,0 +1,52 @@ +--- +description: Execute the implementation plan by processing and executing all tasks defined in tasks.md +--- + +Given the current feature context, do this: + +1. Run `.specify/scripts/bash/check-implementation-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. + +2. Load and analyze the implementation context: + - **REQUIRED**: Read tasks.md for the complete task list and execution plan + - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure + - **IF EXISTS**: Read data-model.md for entities and relationships + - **IF EXISTS**: Read contracts/ for API specifications and test requirements + - **IF EXISTS**: Read research.md for technical decisions and constraints + - **IF EXISTS**: Read quickstart.md for integration scenarios + +3. Parse tasks.md structure and extract: + - **Task phases**: Setup, Tests, Core, Integration, Polish + - **Task dependencies**: Sequential vs parallel execution rules + - **Task details**: ID, description, file paths, parallel markers [P] + - **Execution flow**: Order and dependency requirements + +4. Execute implementation following the task plan: + - **Phase-by-phase execution**: Complete each phase before moving to the next + - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together + - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks + - **File-based coordination**: Tasks affecting the same files must run sequentially + - **Validation checkpoints**: Verify each phase completion before proceeding + +5. Implementation execution rules: + - **Setup first**: Initialize project structure, dependencies, configuration + - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios + - **Core development**: Implement models, services, CLI commands, endpoints + - **Integration work**: Database connections, middleware, logging, external services + - **Polish and validation**: Unit tests, performance optimization, documentation + +6. Progress tracking and error handling: + - Report progress after each completed task + - Halt execution if any non-parallel task fails + - For parallel tasks [P], continue with successful tasks, report failed ones + - Provide clear error messages with context for debugging + - Suggest next steps if implementation cannot proceed + - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file. + +7. Completion validation: + - Verify all required tasks are completed + - Check that implemented features match the original specification + - Validate that tests pass and coverage meets requirements + - Confirm the implementation follows the technical plan + - Report final status with summary of completed work + +Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list. diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md new file mode 100644 index 0000000..cab2071 --- /dev/null +++ b/.claude/commands/plan.md @@ -0,0 +1,36 @@ +--- +description: Execute the implementation planning workflow using the plan template to generate design artifacts. +--- + +Given the implementation details provided as an argument, do this: + +1. Run `.specify/scripts/bash/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 `.specify/memory/constitution.md` to understand constitutional requirements. + +4. Execute the implementation plan template: + - Load `.specify/templates/plan-template.md` (already copied to IMPL_PLAN path) + - Set Input path to FEATURE_SPEC + - Run the Execution Flow (main) function steps 1-9 + - 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..2927a4f --- /dev/null +++ b/.claude/commands/specify.md @@ -0,0 +1,13 @@ +--- +description: Create or update the feature specification from a natural language feature description. +--- + +Given the feature description provided as an argument, do this: + +1. Run the script `.specify/scripts/bash/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. + **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for. +2. Load `.specify/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..83291c9 --- /dev/null +++ b/.claude/commands/tasks.md @@ -0,0 +1,58 @@ +--- +description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts. +--- + +Given the context provided as an argument, do this: + +1. Run `.specify/scripts/bash/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 `.specify/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/.specify/memory/constitution.md b/.specify/memory/constitution.md new file mode 100644 index 0000000..1ed8d77 --- /dev/null +++ b/.specify/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/.specify/scripts/bash/check-implementation-prerequisites.sh b/.specify/scripts/bash/check-implementation-prerequisites.sh new file mode 100755 index 0000000..c660ffa --- /dev/null +++ b/.specify/scripts/bash/check-implementation-prerequisites.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +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 +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/common.sh" +eval $(get_feature_paths) +check_feature_branch "$CURRENT_BRANCH" || exit 1 +if [[ ! -d "$FEATURE_DIR" ]]; then echo "ERROR: Feature directory not found: $FEATURE_DIR"; echo "Run /specify first."; exit 1; fi +if [[ ! -f "$IMPL_PLAN" ]]; then echo "ERROR: plan.md not found in $FEATURE_DIR"; echo "Run /plan first."; exit 1; fi +if [[ ! -f "$TASKS" ]]; then echo "ERROR: tasks.md not found in $FEATURE_DIR"; echo "Run /tasks first."; exit 1; fi +if $JSON_MODE; then + 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"); [[ -f "$TASKS" ]] && docs+=("tasks.md"); + json_docs=$(printf '"%s",' "${docs[@]}"); json_docs="[${json_docs%,}]"; printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs" +else + echo "FEATURE_DIR:$FEATURE_DIR"; echo "AVAILABLE_DOCS:"; check_file "$RESEARCH" "research.md"; check_file "$DATA_MODEL" "data-model.md"; check_dir "$CONTRACTS_DIR" "contracts/"; check_file "$QUICKSTART" "quickstart.md"; check_file "$TASKS" "tasks.md"; fi \ No newline at end of file diff --git a/.specify/scripts/bash/check-task-prerequisites.sh b/.specify/scripts/bash/check-task-prerequisites.sh new file mode 100755 index 0000000..e578f86 --- /dev/null +++ b/.specify/scripts/bash/check-task-prerequisites.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +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 +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/common.sh" +eval $(get_feature_paths) +check_feature_branch "$CURRENT_BRANCH" || exit 1 +if [[ ! -d "$FEATURE_DIR" ]]; then echo "ERROR: Feature directory not found: $FEATURE_DIR"; echo "Run /specify first."; exit 1; fi +if [[ ! -f "$IMPL_PLAN" ]]; then echo "ERROR: plan.md not found in $FEATURE_DIR"; echo "Run /plan first."; exit 1; fi +if $JSON_MODE; then + 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"); + json_docs=$(printf '"%s",' "${docs[@]}"); json_docs="[${json_docs%,}]"; printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs" +else + echo "FEATURE_DIR:$FEATURE_DIR"; echo "AVAILABLE_DOCS:"; check_file "$RESEARCH" "research.md"; check_file "$DATA_MODEL" "data-model.md"; check_dir "$CONTRACTS_DIR" "contracts/"; check_file "$QUICKSTART" "quickstart.md"; fi diff --git a/.specify/scripts/bash/common.sh b/.specify/scripts/bash/common.sh new file mode 100755 index 0000000..582d940 --- /dev/null +++ b/.specify/scripts/bash/common.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# (Moved to scripts/bash/) Common functions and variables for all scripts + +get_repo_root() { git rev-parse --show-toplevel; } +get_current_branch() { git rev-parse --abbrev-ref HEAD; } + +check_feature_branch() { + local branch="$1" + if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then + echo "ERROR: Not on a feature branch. Current branch: $branch" >&2 + echo "Feature branches should be named like: 001-feature-name" >&2 + return 1 + fi; return 0 +} + +get_feature_dir() { echo "$1/specs/$2"; } + +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") + cat </dev/null) ]] && echo " ✓ $2" || echo " ✗ $2"; } diff --git a/.specify/scripts/bash/create-new-feature.sh b/.specify/scripts/bash/create-new-feature.sh new file mode 100755 index 0000000..bc4b406 --- /dev/null +++ b/.specify/scripts/bash/create-new-feature.sh @@ -0,0 +1,58 @@ +#!/usr/bin/env bash +# (Moved to scripts/bash/) Create a new feature with branch, directory structure, and template +set -e + +JSON_MODE=false +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 + +REPO_ROOT=$(git rev-parse --show-toplevel) +SPECS_DIR="$REPO_ROOT/specs" +mkdir -p "$SPECS_DIR" + +HIGHEST=0 +if [ -d "$SPECS_DIR" ]; then + for dir in "$SPECS_DIR"/*; do + [ -d "$dir" ] || continue + dirname=$(basename "$dir") + number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0") + number=$((10#$number)) + if [ "$number" -gt "$HIGHEST" ]; then HIGHEST=$number; fi + done +fi + +NEXT=$((HIGHEST + 1)) +FEATURE_NUM=$(printf "%03d" "$NEXT") + +BRANCH_NAME=$(echo "$FEATURE_DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//') +WORDS=$(echo "$BRANCH_NAME" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//') +BRANCH_NAME="${FEATURE_NUM}-${WORDS}" + +git checkout -b "$BRANCH_NAME" + +FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME" +mkdir -p "$FEATURE_DIR" + +TEMPLATE="$REPO_ROOT/templates/spec-template.md" +SPEC_FILE="$FEATURE_DIR/spec.md" +if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else 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 + echo "BRANCH_NAME: $BRANCH_NAME" + echo "SPEC_FILE: $SPEC_FILE" + echo "FEATURE_NUM: $FEATURE_NUM" +fi diff --git a/.specify/scripts/bash/get-feature-paths.sh b/.specify/scripts/bash/get-feature-paths.sh new file mode 100755 index 0000000..016727d --- /dev/null +++ b/.specify/scripts/bash/get-feature-paths.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +set -e +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/common.sh" +eval $(get_feature_paths) +check_feature_branch "$CURRENT_BRANCH" || exit 1 +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" diff --git a/.specify/scripts/bash/setup-plan.sh b/.specify/scripts/bash/setup-plan.sh new file mode 100755 index 0000000..1da4265 --- /dev/null +++ b/.specify/scripts/bash/setup-plan.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +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 +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/common.sh" +eval $(get_feature_paths) +check_feature_branch "$CURRENT_BRANCH" || exit 1 +mkdir -p "$FEATURE_DIR" +TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md" +[[ -f "$TEMPLATE" ]] && cp "$TEMPLATE" "$IMPL_PLAN" +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 + echo "FEATURE_SPEC: $FEATURE_SPEC"; echo "IMPL_PLAN: $IMPL_PLAN"; echo "SPECS_DIR: $FEATURE_DIR"; echo "BRANCH: $CURRENT_BRANCH" +fi diff --git a/.specify/scripts/bash/update-agent-context.sh b/.specify/scripts/bash/update-agent-context.sh new file mode 100755 index 0000000..a79edd9 --- /dev/null +++ b/.specify/scripts/bash/update-agent-context.sh @@ -0,0 +1,66 @@ +#!/usr/bin/env bash +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" +CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"; GEMINI_FILE="$REPO_ROOT/GEMINI.md"; COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"; CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"; QWEN_FILE="$REPO_ROOT/QWEN.md"; AGENTS_FILE="$REPO_ROOT/AGENTS.md" +AGENT_TYPE="$1" +[ -f "$NEW_PLAN" ] || { echo "ERROR: No plan.md found at $NEW_PLAN"; exit 1; } +echo "=== Updating agent context files for feature $CURRENT_BRANCH ===" +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_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 "") +update_agent_file() { local target_file="$1" agent_name="$2"; echo "Updating $agent_name context file: $target_file"; local temp_file=$(mktemp); if [ ! -f "$target_file" ]; then + echo "Creating new $agent_name context file..."; if [ -f "$REPO_ROOT/.specify/templates/agent-file-template.md" ]; then cp "$REPO_ROOT/.specify/templates/agent-file-template.md" "$temp_file"; else echo "ERROR: Template not found"; return 1; fi; + 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"; + 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; + 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"; + sed -i.bak "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$NEW_LANG: Follow standard conventions|" "$temp_file"; 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..."; manual_start=$(grep -n "" "$target_file" | cut -d: -f1); manual_end=$(grep -n "" "$target_file" | cut -d: -f1); if [ -n "$manual_start" ] && [ -n "$manual_end" ]; then sed -n "${manual_start},${manual_end}p" "$target_file" > /tmp/manual_additions.txt; fi; + python3 - "$target_file" <<'EOF' +import re,sys,datetime +target=sys.argv[1] +with open(target) as f: content=f.read() +NEW_LANG="'$NEW_LANG'";NEW_FRAMEWORK="'$NEW_FRAMEWORK'";CURRENT_BRANCH="'$CURRENT_BRANCH'";NEW_DB="'$NEW_DB'";NEW_PROJECT_TYPE="'$NEW_PROJECT_TYPE'" +# Tech section +m=re.search(r'## Active Technologies\n(.*?)\n\n',content, re.DOTALL) +if m: + existing=m.group(1) + additions=[] + if '$NEW_LANG' and '$NEW_LANG' not in existing: additions.append(f"- $NEW_LANG + $NEW_FRAMEWORK ($CURRENT_BRANCH)") + if '$NEW_DB' and '$NEW_DB' not in existing and '$NEW_DB'!='N/A': additions.append(f"- $NEW_DB ($CURRENT_BRANCH)") + if additions: + new_block=existing+"\n"+"\n".join(additions) + content=content.replace(m.group(0),f"## Active Technologies\n{new_block}\n\n") +# Recent changes +m2=re.search(r'## Recent Changes\n(.*?)(\n\n|$)',content, re.DOTALL) +if m2: + lines=[l for l in m2.group(1).strip().split('\n') if l] + lines.insert(0,f"- $CURRENT_BRANCH: Added $NEW_LANG + $NEW_FRAMEWORK") + lines=lines[:3] + content=re.sub(r'## Recent Changes\n.*?(\n\n|$)', '## Recent Changes\n'+"\n".join(lines)+'\n\n', content, flags=re.DOTALL) +content=re.sub(r'Last updated: \d{4}-\d{2}-\d{2}', 'Last updated: '+datetime.datetime.now().strftime('%Y-%m-%d'), content) +open(target+'.tmp','w').write(content) +EOF + mv "$target_file.tmp" "$target_file"; if [ -f /tmp/manual_additions.txt ]; then sed -i.bak '//,//d' "$target_file"; cat /tmp/manual_additions.txt >> "$target_file"; rm /tmp/manual_additions.txt "$target_file.bak"; fi; +fi; mv "$temp_file" "$target_file" 2>/dev/null || true; echo "✅ $agent_name context file updated successfully"; } +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" ;; + cursor) update_agent_file "$CURSOR_FILE" "Cursor IDE" ;; + qwen) update_agent_file "$QWEN_FILE" "Qwen Code" ;; + opencode) update_agent_file "$AGENTS_FILE" "opencode" ;; + "") [ -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"; \ + [ -f "$CURSOR_FILE" ] && update_agent_file "$CURSOR_FILE" "Cursor IDE"; \ + [ -f "$QWEN_FILE" ] && update_agent_file "$QWEN_FILE" "Qwen Code"; \ + [ -f "$AGENTS_FILE" ] && update_agent_file "$AGENTS_FILE" "opencode"; \ + if [ ! -f "$CLAUDE_FILE" ] && [ ! -f "$GEMINI_FILE" ] && [ ! -f "$COPILOT_FILE" ] && [ ! -f "$CURSOR_FILE" ] && [ ! -f "$QWEN_FILE" ] && [ ! -f "$AGENTS_FILE" ]; then update_agent_file "$CLAUDE_FILE" "Claude Code"; fi ;; + *) echo "ERROR: Unknown agent type '$AGENT_TYPE' (expected claude|gemini|copilot|cursor|qwen|opencode)"; exit 1 ;; +esac +echo; echo "Summary of changes:"; [ -n "$NEW_LANG" ] && echo "- Added language: $NEW_LANG"; [ -n "$NEW_FRAMEWORK" ] && echo "- Added framework: $NEW_FRAMEWORK"; [ -n "$NEW_DB" ] && [ "$NEW_DB" != "N/A" ] && echo "- Added database: $NEW_DB"; echo; echo "Usage: $0 [claude|gemini|copilot|cursor|qwen|opencode]" diff --git a/.specify/templates/agent-file-template.md b/.specify/templates/agent-file-template.md new file mode 100644 index 0000000..2301e0e --- /dev/null +++ b/.specify/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/.specify/templates/plan-template.md b/.specify/templates/plan-template.md new file mode 100644 index 0000000..8429845 --- /dev/null +++ b/.specify/templates/plan-template.md @@ -0,0 +1,211 @@ + +# 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. Fill the Constitution Check section based on the content of the constitution document. +4. 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 +5. Execute Phase 0 → research.md + → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns" +6. 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, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code or `AGENTS.md` for opencode). +7. Re-evaluate Constitution Check section + → If new violations: Refactor design, return to Phase 1 + → Update Progress Tracking: Post-Design Constitution Check +8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md) +9. 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.* + +[Gates determined based on constitution file] + +## 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 `.specify/scripts/bash/update-agent-context.sh claude` 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 `.specify/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`* diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md new file mode 100644 index 0000000..7915e7d --- /dev/null +++ b/.specify/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/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md new file mode 100644 index 0000000..b8a28fa --- /dev/null +++ b/.specify/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