Autospec Implement

autospec-implement

This Agent Skill is generated from autospec.implement. When the user invokes "$autospec-implement" or "/autospec.implement", load and follow these instructions directly. Treat the text after the skill or command name as "$ARGUMENTS". Do not route back through "autospec implement"; this skill is the prompt for the stage.

Project specs directory: ./specs

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Execution Boundaries (CRITICAL)

Pre-computed Context

The following paths have been pre-computed and are available for use:

• FEATURE_DIR: {{.FeatureDir}}
• TASKS_FILE: {{.TasksFile}}
• CONSTITUTION_FILE: {{if .ConstitutionFile}}{{.ConstitutionFile}}{{else}}not found{{end}}
• IS_GIT_REPO: {{.IsGitRepo}}

Outline

1. Phase Context Metadata (CRITICAL - Token Optimization):

   Check if --context-file was used. If so, parse the _context_meta section FIRST before any other file reads.

   _context_meta Fields:

   • phase_artifacts_bundled: true - Indicates that spec.yaml, plan.yaml, and tasks.yaml (phase-filtered) are already bundled in this context file
   • bundled_artifacts - Lists the artifacts included, such as ["spec.yaml", "plan.yaml", "tasks.yaml (phase-filtered)", "constitution.yaml"]
   • has_governance - Boolean indicating whether project governance is bundled in the governance: section
     • If true: Use the bundled governance: data as the constitution/governance source of truth
     • If false: No constitution was bundled; do not search for a governance file during context-file execution
   • governance_file - Path to the constitution file when governance is bundled
   • has_checklists - Boolean indicating whether a checklists/ directory exists for this feature
     • If false: DO NOT check for, scan, or read from the checklists directory - it doesn't exist, skip step 3 entirely
     • If true: Checklists directory exists, proceed to step 3
   • skip_reads - Explicit list of file paths that are already bundled and MUST NOT be read separately

   CRITICAL INSTRUCTION:

   DO NOT read files listed in skip_reads when _context_meta.phase_artifacts_bundled is true.
   DO NOT check for checklists directory when _context_meta.has_checklists is false.
   DO NOT separately read _context_meta.governance_file when it appears in skip_reads; use the bundled governance section instead.

   Example _context_meta section:

   _context_meta:
     phase_artifacts_bundled: true
     bundled_artifacts:
       - spec.yaml
       - plan.yaml
       - tasks.yaml (phase-filtered)
       - constitution.yaml
     has_governance: true
     governance_file: .autospec/constitution.yaml
     has_checklists: false
     skip_reads:
       - specs/my-feature/spec.yaml
       - specs/my-feature/plan.yaml
       - specs/my-feature/tasks.yaml
       - .autospec/constitution.yaml

2. Check checklists status (SKIP if _context_meta.has_checklists: false):

   • Scan all *.yaml checklist files in the checklists/ directory

   • For each checklist YAML file, parse and count:

     • Total items: All items across all categories (categories[].items[])
     • Passed items: Items where status: "pass"
     • Failed/Pending items: Items where status: "fail" or status: "pending"

   • Create a status table:

     | Checklist     | Total | Passed | Not Passed | Status |
     |---------------|-------|--------|------------|--------|
     | ux.yaml       | 12    | 12     | 0          | PASS   |
     | api.yaml      | 8     | 5      | 3          | FAIL   |
     | security.yaml | 6     | 6      | 0          | PASS   |

   • Calculate overall status:

     • PASS: All checklists have 0 items with status: "fail" or status: "pending"
     • FAIL: One or more checklists have items not in status: "pass"

   • If any checklist is incomplete:

     • Display the table with incomplete item counts
     • STOP and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
     • Wait for user response before continuing
     • If user says "no" or "wait" or "stop", halt execution
     • If user says "yes" or "proceed" or "continue", proceed to step 4

   • If all checklists are complete:

     • Display the table showing all checklists passed
     • Automatically proceed to step 4

3. Load and analyze the implementation context (if NOT using --context-file):

   Note: If you are using --context-file, the spec, plan, tasks, and possibly governance are already loaded from the context file. Skip reading files listed in _context_meta.skip_reads and use the bundled data from the spec:, plan:, tasks:, and governance: sections of the context file instead.

   {{if .ConstitutionFile}}- REQUIRED GOVERNANCE: Read {{.ConstitutionFile}} for project principles, non-negotiable constraints, quality standards, and validation requirements before modifying code. Treat these governance rules as binding during implementation.{{else}}- GOVERNANCE: No constitution file was detected in a supported path. Continue using spec, plan, tasks, and local agent instructions.{{end}}

   • REQUIRED: Read tasks.yaml for the complete task list and execution plan
   • REQUIRED: Read plan.yaml for:
     • technical_context: tech stack, dependencies, constraints
     • data_model: entities and relationships
     • api_contracts: API specifications
     • research_findings: technical decisions and rationale
     • project_structure: file organization
   • REQUIRED: Read spec.yaml for:
     • user_stories: acceptance scenarios
     • requirements: functional and non-functional
     • success_criteria: measurable outcomes

4. Project Setup Verification:

   • REQUIRED: Create/verify ignore files based on actual project setup:

   Detection & Creation Logic:

   • Use {{.IsGitRepo}} to determine if this is a git repository (create/verify .gitignore if true)
   • Check if Dockerfile* exists or Docker in plan.yaml technical_context → create/verify .dockerignore
   • Check if .eslintrc* exists → create/verify .eslintignore
   • Check if eslint.config.* exists → ensure the config's ignores entries cover required patterns
   • Check if .prettierrc* exists → create/verify .prettierignore
   • Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
   • Check if terraform files (*.tf) exist → create/verify .terraformignore
   • Check if .helmignore needed (helm charts present) → create/verify .helmignore

   If ignore file already exists: Verify it contains essential patterns, append missing critical patterns only If ignore file missing: Create with full pattern set for detected technology

   Common Patterns by Technology (from plan.yaml technical_context):

   • Node.js/JavaScript/TypeScript: node_modules/, dist/, build/, *.log, .env*
   • Python: __pycache__/, *.pyc, .venv/, venv/, dist/, *.egg-info/
   • Java: target/, *.class, *.jar, .gradle/, build/
   • C#/.NET: bin/, obj/, *.user, *.suo, packages/
   • Go: *.exe, *.test, vendor/, *.out
   • Ruby: .bundle/, log/, tmp/, *.gem, vendor/bundle/
   • PHP: vendor/, *.log, *.cache, *.env
   • Rust: target/, debug/, release/, *.rs.bk, *.rlib, *.prof*, .idea/, *.log, .env*
   • Kotlin: build/, out/, .gradle/, .idea/, *.class, *.jar, *.iml, *.log, .env*
   • C++: build/, bin/, obj/, out/, *.o, *.so, *.a, *.exe, *.dll, .idea/, *.log, .env*
   • C: build/, bin/, obj/, out/, *.o, *.a, *.so, *.exe, Makefile, config.log, .idea/, *.log, .env*
   • Swift: .build/, DerivedData/, *.swiftpm/, Packages/
   • R: .Rproj.user/, .Rhistory, .RData, .Ruserdata, *.Rproj, packrat/, renv/
   • Universal: .DS_Store, Thumbs.db, *.tmp, *.swp, .vscode/, .idea/

   Tool-Specific Patterns:

   • Docker: node_modules/, .git/, Dockerfile*, .dockerignore, *.log*, .env*, coverage/
   • ESLint: node_modules/, dist/, build/, coverage/, *.min.js
   • Prettier: node_modules/, dist/, build/, coverage/, package-lock.json, yarn.lock, pnpm-lock.yaml
   • Terraform: .terraform/, *.tfstate*, *.tfvars, .terraform.lock.hcl
   • Kubernetes/k8s: *.secret.yaml, secrets/, .kube/, kubeconfig*, *.key, *.crt

5. Parse tasks.yaml structure and extract:

   • Phases: Setup, Foundational, User Story phases, Polish
   • Task dependencies: Sequential vs parallel execution from parallel field
   • Task details: id, title, status, type, file_path, dependencies, acceptance_criteria
   • Execution flow: Phase order and task dependency requirements
   • User story mapping: Which tasks belong to which user stories

6. Execute implementation following the task plan (respect Execution Boundaries above):

   • Respect dependencies: Run sequential tasks in order, parallel tasks can run together
   • Follow TDD approach: Execute test tasks before their corresponding implementation tasks (if tests exist)
   • File-based coordination: Tasks affecting the same files must run sequentially
   • Validation checkpoints: Verify each phase completion before proceeding

7. Implementation execution rules:

   • Governance first: Apply constitution principles and governance constraints to all code, tests, docs, and validation decisions
   • Setup first: Initialize project structure, dependencies, configuration
   • Foundational next: Complete blocking prerequisites before user stories
   • User stories in order: Complete each story phase before the next
   • Tests before code: If test tasks exist, write tests before implementation
   • Polish last: Cross-cutting concerns and refactoring at the end

8. Progress tracking and task status updates:

   CRITICAL: You MUST update task status in tasks.yaml as you work. This is non-negotiable.

   Use the autospec update-task command to update task status:

   autospec update-task <task_id> <status>

   When starting a task:

   autospec update-task T001 InProgress

   When completing a task:

   autospec update-task T001 Completed

   If a task is blocked:

   autospec update-task T001 Blocked

   Valid status values: Pending, InProgress, Completed, Blocked

   Blocking tasks with reasons (preferred method for documenting blockers):

   # Block a task and document why it's blocked
   autospec task block T001 --reason "Waiting for API access from third-party team"
   
   # Update the reason for an already blocked task
   autospec task block T001 --reason "Updated: API approved, waiting for credentials"

   Unblocking tasks:

   # Unblock a task (defaults to Pending status)
   autospec task unblock T001
   
   # Unblock and immediately set to InProgress
   autospec task unblock T001 --status InProgress

   Listing tasks by status:

   # List all tasks
   autospec task list
   
   # List only blocked tasks (shows reasons)
   autospec task list --blocked
   
   # List pending tasks
   autospec task list --pending
   
   # List in-progress tasks
   autospec task list --in-progress
   
   # List completed tasks
   autospec task list --completed
   
   # Combine filters
   autospec task list --blocked --pending

   Implementation workflow for each task:

   1. Mark task as InProgress: autospec update-task T00X InProgress
   2. Implement the task
   3. Verify implementation meets acceptance criteria
   4. Mark task as Completed: autospec update-task T00X Completed
   5. Move to next task

   Handling blocked tasks:

   1. If blocked by external dependency: autospec task block T00X --reason "Reason"
   2. Document the blocker clearly so others understand what needs resolution
   3. When blocker is resolved: autospec task unblock T00X [--status InProgress]
   • Report progress after each completed task
   • Halt execution if any non-parallel task fails
   • For parallel tasks, continue with successful tasks, report failed ones
   • Provide clear error messages with context for debugging
   • Suggest next steps if implementation cannot proceed

9. Validate tasks.yaml after updates: