chore: add wave-based orchestration and context protection to feature skill (#480)

This commit is contained in:
Carlos Florêncio
2026-03-28 21:54:13 +00:00
committed by GitHub
parent 8651e96097
commit bb3d417fba
3 changed files with 62 additions and 21 deletions
+52 -11
View File
@@ -40,21 +40,62 @@ Systematic feature development: understand the problem, explore the codebase, de
## Phase 4: Implement with TDD
Follow `/tdd` strictly. Decide how to execute based on task independence:
**You are the coordinator.** Your job is to hold the big picture (requirements, design, file structure, wave progress) and delegate implementation to subagents. Protect your context:
**Independent tasks** (separate files/packages, no shared state): dispatch a subagent per task. Each gets a fresh context with the task description, relevant file paths from Phase 3, and codebase conventions from Phase 2. This prevents context pollution and keeps each task focused.
- **Prefer subagents over inline work.** Every task you implement inline fills your context with code details and tool outputs. Delegate to subagents whenever possible — they get fresh context and return only a summary.
- **Keep coupled tasks small.** If you must implement inline (coupled tasks), keep each task focused and short. Don't read entire files unnecessarily — read only what you need to verify the subagent's work or wire things together.
- **Don't debug in the coordinator.** If a subagent's task fails quality gates, dispatch a new subagent to fix it rather than debugging inline. Pass the failure details and let the fresh subagent investigate.
- **Track progress, not details.** For each completed task, note: what was done, which files changed, commit hash. Don't carry the implementation details forward.
**Coupled tasks** (shared types, sequential data flow, integration work): implement inline in the current session to maintain shared context.
### 4a. Decompose into tasks
For each behavior or component:
1. **RED** — write a failing test (unit, or E2E via `/e2e` for user-facing flows)
2. **GREEN** — write the minimum code to pass
3. **REFACTOR** — clean up while staying green
4. Follow codebase conventions from Phase 2
5. Build incrementally — one behavior at a time, tests passing at every step
Using the file structure map from Phase 3, break the implementation into discrete tasks. Each task should:
- Touch a specific set of files
- Have a clear done condition (test passes, API works, component renders)
- Be classifiable as independent or coupled
**When things go wrong during implementation:**
- **Bugs or missing validation discovered:** fix inline, add a test, continue
### 4b. Group into waves
Subagents share the same worktree, so parallelism is constrained by build boundaries:
- **Backend (Go)**: packages compile independently — different packages can run in parallel subagents
- **Frontend (Next.js)**: single build — only ONE subagent can work on frontend at a time
- **E2E tests**: need full build — only after both backend and frontend changes are done
- **Coupled tasks** (shared types, sequential data flow): must run sequentially regardless
Group tasks into waves. Example:
```text
Wave 1 (parallel): [Backend API handler (subagent), Frontend component + hook (subagent)]
Wave 2 (sequential): [Wire frontend to API, integration test]
Wave 3: [E2E test for the full flow]
```
Max parallelism: 1 frontend subagent + 1-2 backend subagents (if working on independent packages). For small features with 1-3 tasks, skip wave grouping and implement sequentially.
### 4c. Execute wave by wave
For each wave, follow `/tdd` strictly (RED-GREEN-REFACTOR):
**Independent tasks in the wave**: dispatch one subagent per task. Each gets fresh context with:
- Task description and acceptance criteria
- Relevant file paths from Phase 3
- Codebase conventions from Phase 2
- Instruction to follow `/tdd`
**Coupled tasks** (e.g., wiring frontend to backend, integration glue): implement inline but keep it minimal — only the glue code, not full feature implementation.
Wait for all tasks in the wave to complete before moving to the next wave.
### 4d. Quality gate after each wave
After each wave completes:
- Backend: `cd apps/backend && go test ./internal/path/...` (changed packages only)
- Frontend: `cd apps && pnpm --filter @kandev/web typecheck && pnpm --filter @kandev/web test`
- If tests fail, fix before proceeding to the next wave
- E2E tests only in the final wave or Phase 5 (QA)
### 4e. Stop conditions
- **Bugs or missing validation discovered during a subagent's task:** the subagent fixes it inline. If the bug surfaces after a wave completes (quality gate failure), dispatch a new subagent to fix it — don't debug in the coordinator.
- **Blocker (missing dependency, unclear requirement, test fails repeatedly):** stop and ask the user
- **Fix requires architectural change (new DB table, new service layer, switching libraries):** stop and ask — don't make structural decisions silently
- **3 failed fix attempts on the same issue:** stop, question the approach, ask the user
+3 -7
View File
@@ -3,6 +3,8 @@ name: pr
description: Commit, push, and create a PR. Default is ready-for-review with auto-fixup. Use --draft to skip review/fixup.
---
# PR
## Context
- Current git status: !`git status`
@@ -31,13 +33,7 @@ Commit, push, and create a pull request.
4. **Create the PR.** Use `--draft` flag if the user requested draft mode, otherwise create as ready-for-review.
**PR title** must follow Conventional Commits format (CI validates this via `pr-title.yml`, and it becomes the squash-merge commit used for release notes):
- Format: `type(scope): lowercase description` or `type: lowercase description`
- Allowed types: `feat`, `fix`, `perf`, `refactor`, `docs`, `chore`, `ci`, `test`
- Subject starts with a lowercase letter
- Keep under 72 characters
- Add `!` after type for breaking changes: `feat!: remove legacy API`
- Examples: `feat(ui): add task filter dialog`, `fix: prevent duplicate session on reconnect`
**PR title** must follow Conventional Commits format (see `/commit` for full rules). CI validates via `pr-title.yml` — the PR title becomes the squash-merge commit used for release notes.
**PR body** must follow the project's pull request template:
- **Summary** (required): 1–2 sentences of prose, no heading. Lead with the problem/goal, end with the outcome. Say WHY, not what.
+7 -3
View File
@@ -3,6 +3,8 @@ name: push
description: Commit and push to the current branch. Use --fixup to also wait for CI/CodeRabbit and fix issues.
---
# Push
## Context
- Current branch: !`git branch --show-current`
@@ -22,12 +24,14 @@ Commit any pending changes and push to the remote branch.
1. **Uncommitted changes:** If there are dirty or staged changes, run `/commit` first (it runs `/verify` internally).
2. **Push** the current branch:
2. **Safety check:** Verify the current branch is NOT `main` or `master`. If it is, stop and ask the user — direct pushes to the default branch should go through a PR.
3. **Push** the current branch:
```bash
git push
```
If the branch has no upstream, use `git push -u origin <branch>`.
3. **Report** the pushed commit hash and branch.
4. **Report** the pushed commit hash and branch.
4. **If `--fixup`:** Run `/pr-fixup` to wait for CI checks and CodeRabbit review, fix any failures or valid comments, and push.
5. **If `--fixup`:** Run `/pr-fixup` to wait for CI checks and CodeRabbit review, fix any failures or valid comments, and push.