193 lines
9.9 KiB
Markdown
193 lines
9.9 KiB
Markdown
---
|
||
description: Implement feature from spec with iterative codex review and commits
|
||
allowed-tools: 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:
|
||
|
||
```markdown
|
||
- [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:
|
||
|
||
```markdown
|
||
## 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.
|