zhongwei/gh-vaayne-cc-plugins-plugins-specs-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:04:09 +08:00
commit ef5efab3d9
8 changed files with 538 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
commands/commit.md Normal file
View File

@@ -0,0 +1,20 @@
# Git Commit
Commit small, focused changes with descriptive messages that include emoji and details. Use conventional commit format with appropriate emoji prefixes (e.g., ✨ feat:, 🐛 fix:, ♻️ refactor:, 📝 docs:).
## Steps:
1. Run `git status` to see staged changes
2. Generate commit message following conventional commit format
3. Execute `git commit -m` with the commit message
## Example Commit Types:
- ✨ feat: New features
- 🐛 fix: Bug fixes
- 📝 docs: Documentation changes
- ♻️ refactor: Code restructuring
- 🧑‍💻 chore: Tooling and maintenance
- 🎨 style: Code formatting, missing semicolons, etc.
- ⚡️ perf: Performance improvements
- ✅ test: Adding or correcting tests

192
commands/impl.md Normal file
View File

@@ -0,0 +1,192 @@
---
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.

109
commands/plan.md Normal file
View File

@@ -0,0 +1,109 @@
---
description: Collaborative planning workflow with Codex review before implementation
allowed-tools: Read(*), Write(*), Edit(*), Glob(*), Grep(*), Task, TodoWrite
---
# Feature Planning with Codex Review
You are facilitating a collaborative planning workflow that produces an approved implementation plan before any code is written.
## Quickstart Flow
| Phase | What you do | Exit criteria |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| 1. Requirements Discussion | Interpret the request, ask targeted questions, refine scope with the user. | User explicitly approves your summary ("OK", "ready", etc.). |
| 2. Plan Creation | Draft the implementation plan covering overview, technical approach, steps, testing, and considerations. | Plan addresses every agreed requirement and is internally consistent. |
| 3. Codex Review | Send the full plan to `codex-analyzer`, integrate its feedback, repeat if needed (≤3 rounds). | Codex confirms the plan is solid and feedback is incorporated. |
| 4. Plan Documentation | Save `plan.md` and `tasks.md` into `.agents/sessions/{YYYY-MM-DD-feature}/`, seed todos, and confirm next steps. | Session folder exists with up-to-date docs and TODOs. |
### Approval Gates
- **Gate A (end of Phase 1):** Summarize the requirements and ask, _"Do I understand correctly? Should I proceed to create the plan?"_ Stop until the user says yes.
- **Gate B (end of Phase 3):** Confirm with Codex feedback addressed and user satisfied before writing files.
### On-Run Checklist
- [ ] Requirements clarified, including scope boundaries and success criteria.
- [ ] Known constraints, integrations, and risks captured.
- [ ] Plan sections populated (overview → testing → considerations).
- [ ] Codex feedback captured, decisions documented.
- [ ] Session folder created with `plan.md` and `tasks.md`.
## Detailed Reference
### Phase 1 – Requirements Discussion
**Goal:** Reach a shared understanding of what to build before writing the plan.
**Steps:**
1. State your initial interpretation of the feature request.
2. Ask clarifying questions about functionality, user goals, constraints, success metrics, integrations, and out-of-scope items.
3. Iterate: reflect the user’s answers, tighten your understanding, and ask follow-ups where fuzzy.
4. Summarize the final requirements and run Approval Gate A.
**Guidelines:** Be concise but thorough, don’t assume missing details, and surface potential risks early.
### Phase 2 – Plan Creation
Produce a plan that is ready for implementation. Include:
1. **Overview** – Feature summary, goals, success criteria, and key requirements.
2. **Technical Approach** – Architecture, design decisions, tooling, component breakdown, data models, APIs, and integration notes.
3. **Implementation Steps** – Ordered tasks with dependencies, estimated effort, and risk callouts.
4. **Testing Strategy** – Unit/integration tests, edge cases, validation, and error handling.
5. **Considerations** – Security, performance, scalability, maintenance, documentation, and open questions.
Quality bar checklist:
- [ ] Every requirement from Phase 1 is addressed explicitly.
- [ ] Tasks are actionable and logically ordered.
- [ ] Rationale for key decisions is documented.
- [ ] Testing and edge cases are spelled out.
- [ ] Risks and mitigations are captured.
### Phase 3 – Codex Review & Refinement
1. Submit the full plan to the Task tool using the `codex-analyzer` agent (`codex --cd "{repo}" exec "agent codex-analyzer: …"`).
2. Request feedback on completeness, technical soundness, security/performance implications, and risk areas.
3. Integrate Codex feedback; clarify or adjust sections as needed.
4. Iterate (maximum of three passes) until Codex indicates the plan is comprehensive and ready.
**Best Practices:**
- Always send the entire plan, not a summary.
- Be explicit about the angle of review (security, performance, edge cases, etc.).
- Note Codex recommendations in the plan so decisions remain traceable.
### Phase 4 – Plan Documentation
1. Create the session directory at `.agents/sessions/{YYYY-MM-DD-feature-name}/`.
2. Save the finalized plan as `plan.md` and seed `tasks.md` with the implementation steps (checkbox list, owners/notes optional).
3. Confirm the session path with the user, summarize next steps, and remind them that `/specs-dev:impl` consumes this directory.
## Additional Guidance
### File Organization
- Sessions live under `.agents/sessions/`. Use YYYY-MM-DD and kebab-case feature names.
- `plan.md` and `tasks.md` stay authoritative; update them whenever requirements change.
### Communication Tips
- Keep the user in the loop—summaries after each major clarification help avoid rework.
- Surface uncertainties immediately; it’s cheaper to resolve them before plan creation.
- Encourage the user to treat Codex feedback as blocking until addressed.
### Troubleshooting
- **User keeps revising requirements:** Spend more time in Phase 1 capturing complete context; update the summary until the user signs off.
- **Codex feedback feels generic:** Provide sharper prompts outlining stack, modules, and risk areas.
- **Plan drifts high-level:** Add explicit file names, interface descriptions, data contracts, and test outlines to anchor the plan.
- **Session directory missing:** Ensure Phase 4 runs and paths are correct; recreate if necessary before invoking `/specs-dev:impl`.
### Tips for Excellent Plans
1. Patience in Phase 1 pays off—better questions reduce redo loops later.
2. Don’t rush the plan; specificity makes `/specs-dev:impl` straightforward.
3. Trust Codex feedback and document the adjustments you make.
4. Keep tasks bite-sized so future commits stay clean and reviewable.