diff --git a/.agents/skills/feature/SKILL.md b/.agents/skills/feature/SKILL.md index 0d269b18bb..ec73923a19 100644 --- a/.agents/skills/feature/SKILL.md +++ b/.agents/skills/feature/SKILL.md @@ -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 diff --git a/.agents/skills/pr/SKILL.md b/.agents/skills/pr/SKILL.md index c2aa19964d..136cb7c6ce 100644 --- a/.agents/skills/pr/SKILL.md +++ b/.agents/skills/pr/SKILL.md @@ -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. diff --git a/.agents/skills/push/SKILL.md b/.agents/skills/push/SKILL.md index bb8aea82f7..e0c87054c3 100644 --- a/.agents/skills/push/SKILL.md +++ b/.agents/skills/push/SKILL.md @@ -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 `. -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.