gh-vaayne-cc-plugins-plugins-specs-dev/commands/impl.md

description, allowed-tools

description	allowed-tools
Implement feature from spec with iterative codex review and commits	Read(*), Write(*), Edit(*), Glob(*), Grep(*), Task, TodoWrite, Bash

Feature Implementation with Codex Review

You are executing a disciplined implementation workflow that keeps Codex in the loop and lands focused, validated commits.

Quickstart Flow

Phase	What you do	Exit criteria
1. Plan Analysis	Open the provided session directory, read plan.md + tasks.md, understand scope and constraints.	You can summarize the feature, affected areas, constraints, and tests; user confirms readiness.
2. Task Breakdown	Break work into small, independent tasks (1–3 files each), sync TodoWrite and tasks.md.	Ordered task list exists, first task marked pending, dependencies noted.
3. Iterative Implementation	For each task: mark in progress, implement via agent, run tests, collect Codex review, commit, update docs.	All tasks complete, Codex feedback addressed, commits passing.
4. Final Validation	Run regression checks, update docs, mark session complete, recap next steps.	Tests green, docs updated, user approves completion.

Workflow Loop (Phase 3)

1. Update TodoWrite → current task in_progress.
2. Launch implementation agent (task-implementer) with explicit instructions.
3. Run required tests or checks.
4. Request Codex review (codex-analyzer) on the diff or files.
5. Apply feedback, rerun tests.
6. Commit code changes with emoji + conventional message.
7. Document implementation in tasks.md (files changed, approach, gotchas, commit hash).
8. Document deviations in plan.md (only if approach changed or new decisions made).
9. Mark task done in TodoWrite.
10. Move to the next task.

Detailed Reference

Phase 1 – Plan Analysis

Goal: Internalize the session plan before touching code.

Steps:

1. Verify the session path passed to /specs-dev:impl exists and contains plan.md and tasks.md.
2. Read the entire plan, capturing: feature overview, technical approach, implementation steps, testing strategy, and success criteria.
3. Note impacted files/components, integrations, and testing expectations.
4. Summarize the plan back to the user and confirm readiness to proceed.

Checklist:

• Session documents reviewed end-to-end.
• Key components/files identified.
• Constraints, risks, and acceptance criteria captured.
• User approval explicitly received before moving on.

Phase 2 – Task Breakdown

Goal: Create actionable, incremental tasks mapped to the plan.

Steps:

1. Translate the plan’s implementation steps into granular tasks (1–3 files each, independently testable).
2. Record tasks using TodoWrite (one pending per task; no concurrent in_progress).
3. Mirror the same list in tasks.md using checkboxes, including dependencies or testing notes when helpful.
4. Highlight riskier tasks or external dependencies.

Task Template:

• Objective
• Files to touch
• Expected output
• Tests to run

Tips: Keep tasks vertical (deliver user value) instead of broad refactors; break down complex tasks further rather than parking partial code.

Phase 3 – Iterative Implementation

Repeat the cycle for each task:

1. Start – Mark the TodoWrite item in_progress.
2. Implement – Use the Task tool (task-implementer) with a detailed prompt: objective, files, acceptance tests, patterns to follow.
3. Validate – Run unit/integration tests relevant to the change. Document commands you run.
4. Codex Review – Call codex-analyzer with the diff or affected files. Request severity-ranked findings covering bugs, security/performance issues, and regressions.
5. Address Feedback – Apply fixes, rerun tests, and if changes are significant, re-run the review.
6. Commit – Ensure a clean diff, then commit with emoji-prefixed Conventional Commit messages (e.g., ✨ feat: add onboarding API handler). One logical change per commit.
7. Document Implementation – Update tasks.md for this task:
   • Check off the task checkbox
   • Add implementation notes: files changed, one-sentence approach summary, any gotchas discovered
   • Link the commit hash
8. Document Deviations (if applicable) – Update plan.md ONLY if:
   • Implementation approach deviated from the original plan
   • New architectural decision was made
   • Risk or constraint discovered that affects future work
   • Add entry under "Implementation Progress" or "Deviations" section with date, what changed, and why
9. Close Task – Set TodoWrite to done. Confirm tasks.md is updated and documentation is complete.

Quality Gates per Task:

• Tests covering the change are added/updated and passing.
• Codex review feedback implemented.
• No TODOs or commented-out code left behind.
• Commit message follows emoji + Conventional Commit format.
• tasks.md updated with implementation notes and commit hash.
• plan.md updated if implementation deviated from original plan or new decisions were made.

Phase 4 – Final Validation

1. Run the agreed regression/acceptance suite (from plan.md).
2. Update plan.md with aggregate insights: overall testing results, final status, known issues, follow-up work, and next steps. Do not repeat per-task details already captured during Phase 3.
3. Verify tasks.md shows all tasks completed with their implementation notes.
4. Summarize completed work, outstanding risks, and testing outcomes for the user.
5. Confirm the session is ready for merge/release.

Completion Checklist:

• All tasks marked complete in both TodoWrite and tasks.md.
• Tests (unit/integration/lint) run and passing.
• No pending Codex feedback or unanswered comments.
• Session docs reflect final state and any next steps.

Reference Material

Agent & Tool Guidance

• Implementation agent: task-implementer (all implementation tasks), or debugger for troubleshooting failing tests.
• Review agent: codex-analyzer; include stack details, modules touched, and request severity-ranked output.
• Todo management: Use TodoWrite to keep one active task. Mirroring status in tasks.md avoids drift.

Documentation Guidelines

Information Architecture:

• TodoWrite: Runtime task status only (in_progress/completed). Ephemeral, session-scoped. Cleared between sessions.
• tasks.md: Tactical implementation record. Persists across sessions. Contains task checklist with implementation notes.
• plan.md: Strategic feature record. Persists across sessions. Contains original plan plus deviations and aggregate insights.

tasks.md Entry Format:

Each completed task should follow this format:

- [x] Task name
  - **Files:** `path/to/file1.ts`, `path/to/file2.ts`
  - **Approach:** Brief 1-sentence description of what was done
  - **Gotchas:** Any surprises, edge cases, or challenges discovered
  - **Commit:** {commit-hash}

plan.md Updates:

Update plan.md during implementation ONLY when:

• Implementation approach deviated from the original plan
• New architectural decision was made
• Risk or constraint emerged that affects future tasks
• External dependency or integration requirements changed

Add entries under an "Implementation Progress" or "Deviations" section:

## Implementation Progress

**[Task Name]** (YYYY-MM-DD):

- **Original plan:** What was originally intended
- **Actual approach:** What was actually done
- **Reason:** Why the change was necessary
- **Impact:** How this affects future tasks (if any)

Rule of Thumb: If it only matters for THIS task → tasks.md. If it affects FUTURE tasks or understanding of the overall feature → plan.md.

Best Practices

• Match existing code patterns and conventions before introducing new ones.
• Keep commits atomic and readable; amend only the latest commit if necessary.
• Keep code commits separate from documentation updates to maintain clean git history.
• Re-run impacted tests after each feedback iteration, not just once at the end.
• Document while context is fresh: update docs immediately after committing, not at the end of the day.

Troubleshooting

• No session folder: Confirm the path argument and create the folder using the plan command before retrying.
• Task too large: Split it into smaller vertical slices; update TodoWrite and tasks.md accordingly.
• Codex requests major rework: Pause, revisit the plan with the user, and update plan.md before continuing.
• Persistent test failures: Switch to the debugger agent or request deeper Codex analysis targeting the failing module.
• Messy commit history: Use git commit --amend for the latest commit only. Avoid rewriting history beyond that without user approval.
• Documentation debt accumulating: If tasks.md hasn't been updated in 3+ completed tasks, pause and catch up before proceeding. Documentation loses value when written too long after implementation.

Communication Tips

• Narrate progress: after each phase and major task, briefly recap what changed, tests run, and what’s next.
• Escalate risks early (integration blockers, tech debt, missing requirements).
• Encourage treating Codex review comments as blocking until resolved.

Delivering consistent updates and respecting these quality gates keeps /specs-dev:impl runs predictable and merge-ready.