diff --git a/.agents/agents/qa.md b/.agents/agents/qa.md index c98a49322d..4445689b14 100644 --- a/.agents/agents/qa.md +++ b/.agents/agents/qa.md @@ -12,16 +12,37 @@ Verify that a feature works as intended after implementation. Assume bugs exist Mindset: you are not confirming it works — you are discovering where it breaks. -## Steps +## Before starting: create the pipeline -### 1. Understand the intent +Create these tasks immediately (use your task/todo tracking tool if available): + +1. **Understand the intent** — Read task/PR/commits to understand what was built +2. **Trace the wiring** — Verify the feature is actually connected end-to-end +3. **Test the happy path** — Run the feature as a user would +4. **Try to break it** — Boundary values, error paths, concurrency, auth +5. **Verify test coverage** — Check for missing tests, write them if needed +6. **Report** — Summarize findings with verdict + +Mark each task in_progress when you begin it and completed when you finish it. Do not skip phases — tracing the wiring before testing catches disconnected code early, and testing the happy path before edge cases establishes a working baseline. + +--- + +## Phase 1: Understand the intent + +Mark task 1 as in_progress. Read the task description, PR, or recent commits to understand what was built and what it should do. Identify: - The expected behavior (happy path) - System boundaries (user input, API endpoints, external data) - Integration points (what calls what, data flow end-to-end) -### 2. Trace the wiring +Mark task 1 as completed. + +--- + +## Phase 2: Trace the wiring + +Mark task 2 as in_progress. Before testing behavior, verify the feature is actually connected: - Exports are imported and used (not just defined) @@ -31,14 +52,26 @@ Before testing behavior, verify the feature is actually connected: If something is orphaned or unwired, stop and report it — no point testing disconnected code. -### 3. Test the happy path +Mark task 2 as completed. + +--- + +## Phase 3: Test the happy path + +Mark task 3 as in_progress. Run the feature as a user would. For backend changes, call the API. For frontend changes, trace the UI flow. For both, follow the full path: - Does the basic use case work? - Does the response/output match expectations? - Is the data persisted correctly? -### 4. Try to break it +Mark task 3 as completed. + +--- + +## Phase 4: Try to break it + +Mark task 4 as in_progress. Systematically test these categories (skip what doesn't apply): @@ -61,14 +94,26 @@ Systematically test these categories (skip what doesn't apply): - Can the feature be accessed without proper auth? - Does it respect permission boundaries? -### 5. Verify test coverage +Mark task 4 as completed. + +--- + +## Phase 5: Verify test coverage + +Mark task 5 as in_progress. Check that the implementation has tests covering the behaviors you just verified: - Are the happy path and key error paths tested? -- Are edge cases from step 4 covered? +- Are edge cases from Phase 4 covered? - If tests are missing, write them following TDD (write failing test first, then verify it passes with existing code) -### 6. Report +Mark task 5 as completed. + +--- + +## Phase 6: Report + +Mark task 6 as in_progress. Summarize what was tested and what was found: @@ -82,3 +127,5 @@ Summarize what was tested and what was found: - Behaviors that work but have no automated test **Verdict:** Feature complete / Has issues — fix before merge + +Mark task 6 as completed. diff --git a/.agents/skills/code-review/SKILL.md b/.agents/skills/code-review/SKILL.md index 95beea7c4c..b64b83dc36 100644 --- a/.agents/skills/code-review/SKILL.md +++ b/.agents/skills/code-review/SKILL.md @@ -7,6 +7,10 @@ description: Review changed code for quality, security, and architecture complia Review the current changes in the codebase (Go + Next.js monorepo). Every finding needs a `file_path:line_number` reference, an explanation of *why* it matters, and a concrete fix. +## Available skills + +- **`/tdd`** — Recommend when flagging untested logic. The author can use this to add tests. + ## Steps ### 1. Identify changed files and check scope diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md index c9c35508cc..93fd4c07b7 100644 --- a/.agents/skills/commit/SKILL.md +++ b/.agents/skills/commit/SKILL.md @@ -7,6 +7,10 @@ description: Stage and commit changes using Conventional Commits. Use when there Create a git commit following this project's Conventional Commits convention. These messages are used by git-cliff (`cliff.toml`) to auto-generate changelogs and release notes. PRs are squash-merged, so the PR title becomes the commit on `main` — CI validates it via `pr-title.yml`. +## Available skills and subagents + +- **`verify` subagent** — Run fmt, typecheck, test, and lint. Delegate to this before committing to catch issues early. + ## Format ``` @@ -46,11 +50,11 @@ ci: add PR title linting workflow ## Steps -**Create a todo/task for each step below and mark them as completed as you go.** +**Create a task for each step below and mark them as completed as you go.** 1. Run `git status` and `git diff` to understand all changes 2. Review recent commits with `git log --oneline -10` to match project style -3. Delegate to the **`verify` sub-agent** to run the full verification pipeline (rebase, format, typecheck, test, lint). It will fix any issues it finds. Wait for it to complete before proceeding. +3. Delegate to the `verify` subagent to run the full verification pipeline (rebase, format, typecheck, test, lint). It will fix any issues it finds. Wait for it to complete before proceeding. 4. Stage relevant files (prefer specific files over `git add -A`) 5. Write a commit message following the format above 6. If changes span multiple concerns, consider separate commits diff --git a/.agents/skills/e2e/SKILL.md b/.agents/skills/e2e/SKILL.md index 00f3dd62bf..1ee1b69b2b 100644 --- a/.agents/skills/e2e/SKILL.md +++ b/.agents/skills/e2e/SKILL.md @@ -5,9 +5,16 @@ description: Write and run web E2E tests (Playwright) using TDD — locations, p # E2E Tests -Write E2E tests using `/tdd` (Red-Green-Refactor). Always run the tests you create and watch them fail before implementing. +Write E2E tests using TDD (Red-Green-Refactor). Always run the tests you create and watch them fail before implementing. -**Location:** `apps/web/e2e/` +## Available skills and subagents + +- **`/tdd`** — Follow the Red-Green-Refactor cycle when writing tests. +- **`/verify`** — Run after completing tests to ensure everything passes across the monorepo. + +## Location + +`apps/web/e2e/` ``` apps/web/e2e/ diff --git a/.agents/skills/feature/SKILL.md b/.agents/skills/feature/SKILL.md index 54cc6d035a..6bbd6a0e5a 100644 --- a/.agents/skills/feature/SKILL.md +++ b/.agents/skills/feature/SKILL.md @@ -7,27 +7,69 @@ description: Guided feature development — brainstorm, explore codebase, design Systematic feature development: understand the problem, explore the codebase, design the solution, implement with TDD, verify it works, and review. -**No implementation before design approval.** +## Available skills and subagents + +The following skills and subagents are available in this repo to delegate work to. Use them instead of doing everything inline — they have specialized instructions and keep your context clean: + +- **`/tdd`** — Implement changes using Test-Driven Development (Red-Green-Refactor). Delegate implementation tasks to this. +- **`/e2e`** — Write and run Playwright E2E tests using TDD. Use for the final wave when the full feature needs end-to-end coverage. +- **`qa` subagent** — Verify a feature works after implementation. Actively tries to break it — edge cases, error paths, integration wiring. +- **`verify` subagent** — Run fmt, typecheck, test, and lint across the monorepo, then fix any issues found. +- **`simplify` subagent** — Simplify recently changed code — inline one-off abstractions, remove speculative code, reduce nesting. +- **`code-review` subagent** — Review changed code for quality, security, and architecture compliance. + +--- + +## Before anything else: create the pipeline + +The first thing you do — before reading code, before asking questions, before any exploration — is create a task list for the full pipeline. This is non-negotiable because it keeps you accountable to the process and lets the user see where you are. + +Create these tasks immediately (use your task/todo tracking tool if available): + +1. **Understand the problem** — Clarify requirements, identify constraints, confirm understanding with user +2. **Explore the codebase** — Find similar patterns, relevant architecture, integration points +3. **Design the solution** — Propose approaches with trade-offs, get user approval before implementing +4. **Implement with TDD** — Break into waves, implement test-first, delegate where possible +5. **QA** — Verify the feature works end-to-end, try to break it +6. **Review and finalize** — Simplify, verify, code review, summarize + +Then start with task 1. Mark each task in_progress when you begin it and completed when you finish it. Do not skip ahead — each phase produces context that the next phase needs. Designing without exploring leads to solutions that fight the codebase. Implementing without design approval wastes time on the wrong approach. + +--- ## Phase 1: Understand the problem +Mark task 1 as in_progress. + 1. If the request is vague, ask clarifying questions — one at a time, prefer multiple choice -2. Challenge the premise: is this the right feature, or is the real need something different? +2. **Challenge the premise** — before accepting the feature at face value, ask whether this is the right solution to the underlying problem. For example: "Have you considered X instead?" or "Is the real need Y rather than Z?" This is especially important for vague requests where the user may not have thought through alternatives. Even for clear requests, briefly consider whether a simpler approach exists. 3. Identify: what problem is being solved, who benefits, what are the constraints 4. Summarize understanding and confirm with the user +Mark task 1 as completed. + +--- + ## Phase 2: Explore the codebase -1. Launch 2-3 Explore agents in parallel targeting different aspects: +Mark task 2 as in_progress. + +1. Search the codebase in parallel targeting different aspects: - Similar features and their implementation patterns - Architecture and abstractions in the relevant area - Integration points, data flow, and extension points -2. Read all key files the agents identify +2. Read all key files identified 3. Check `docs/decisions/INDEX.md` for relevant architectural decisions in this area 4. Present a summary of existing patterns and conventions to reuse +Mark task 2 as completed. + +--- + ## Phase 3: Design +Mark task 3 as in_progress. + 1. **Scope check:** If the feature spans multiple independent subsystems, break it into sub-features first. Each should produce working, testable software on its own. 2. Identify remaining ambiguities: edge cases, error handling, scope boundaries, backward compatibility 3. Ask the user to resolve them — do not assume @@ -35,51 +77,56 @@ Systematic feature development: understand the problem, explore the codebase, de - Minimal change (smallest diff, maximum reuse) - Clean architecture (maintainability, elegant abstractions) - Pragmatic balance (speed + quality) -5. **Map the file structure:** Before getting approval, list which files will be created or modified and what each is responsible for. This locks in decomposition decisions. -6. Get explicit user approval on the approach before proceeding +5. **Map the file structure:** List which files will be created or modified and what each is responsible for. This locks in decomposition decisions. +6. **Stop and wait for explicit user approval on the approach before proceeding.** Do not start Phase 4 until the user confirms the design. + +Mark task 3 as completed only after the user approves. + +--- ## Phase 4: Implement with TDD -**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: +Mark task 4 as in_progress. -- **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. +**You are the coordinator.** Your job is to hold the big picture (requirements, design, file structure, wave progress) and delegate implementation. Protect your context: + +- **Delegate over inline work.** Every task you implement inline fills your context with code details and tool outputs. Delegate to sub-tasks 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 work or wire things together. +- **Don't debug in the coordinator.** If a task fails quality gates, dispatch a new sub-task to fix it rather than debugging inline. Pass the failure details and let the fresh context 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. -### 4a. Decompose into tasks +### 4a. Decompose into implementation tasks -Using the file structure map from Phase 3, break the implementation into discrete tasks. Each task should: +Using the file structure map from Phase 3, create sub-tasks for each discrete piece of work. 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 ### 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 +Parallelism is constrained by build boundaries: +- **Backend (Go)**: packages compile independently — different packages can run in parallel +- **Frontend (Next.js)**: single build — only ONE task 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 1 (parallel): [Backend API handler, Frontend component + hook] 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. +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): +For each wave, follow TDD strictly (RED-GREEN-REFACTOR): -**Independent tasks in the wave**: dispatch one subagent per task. Each gets fresh context with: +**Independent tasks in the wave**: delegate each task via `/tdd`. Each gets: - 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. @@ -91,29 +138,45 @@ 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) +- E2E tests only in the final wave (via `/e2e`) or Phase 5 (QA) + +Mark each implementation sub-task as completed as it passes its quality gate. ### 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. +- **Bugs or missing validation discovered during a task:** fix inline. If the bug surfaces after a wave completes (quality gate failure), dispatch a new task 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 +Mark task 4 as completed when all implementation sub-tasks pass their quality gates. + +--- + ## Phase 5: QA -Delegate to the **`qa` sub-agent** to verify the feature works end-to-end. It will: +Mark task 5 as in_progress. + +Delegate to the `qa` subagent to verify the feature works end-to-end. It will: - Trace the wiring (exports used, APIs called, data flows) - Test the happy path - Try to break it (boundary values, error paths, concurrency) - Write tests for any gaps found -## Phase 6: Review +Mark task 5 as completed. -1. Delegate to the **`simplify` sub-agent** to clean up the implementation -2. Delegate to the **`verify` sub-agent** to ensure fmt, typecheck, test, and lint all pass -3. Delegate to the **`code-review` sub-agent** to review the changes +--- + +## Phase 6: Review and finalize + +Mark task 6 as in_progress. + +1. Delegate to the `simplify` subagent to clean up the implementation +2. Delegate to the `verify` subagent to run fmt, typecheck, test, and lint +3. Delegate to the `code-review` subagent to review changes for quality, security, and architecture compliance 4. Fix any blockers, present suggestions to the user 5. Summarize: what was built, key decisions, files modified, suggested next steps -6. If significant architectural decisions were made, record them via `/record decision` -7. Save the feature design to `docs/plans/` via `/record plan` for permanent reference +6. If significant architectural decisions were made, record them +7. Save the feature design to `docs/plans/` for permanent reference + +Mark task 6 as completed. diff --git a/.agents/skills/fix/SKILL.md b/.agents/skills/fix/SKILL.md index 767d205773..3871c2577a 100644 --- a/.agents/skills/fix/SKILL.md +++ b/.agents/skills/fix/SKILL.md @@ -5,11 +5,32 @@ description: Fix bugs and issues — reproduce, find root cause, minimal fix wit # Fix -Systematic bug fixing: reproduce the problem, find the root cause, apply a minimal fix with a regression test. **No fix without root cause investigation first.** +Systematic bug fixing: reproduce the problem, find the root cause, apply a minimal fix with a regression test. -## Steps +## Available skills and subagents -### 1. Reproduce +- **`/tdd`** — Use for implementing the fix with a regression test (Red-Green-Refactor). +- **`/e2e`** — Use when the bug is in a user-facing flow and needs a Playwright regression test. +- **`/verify`** — Run after fixing to ensure nothing else broke. + +--- + +## Before anything else: create the pipeline + +Create these tasks immediately (use your task/todo tracking tool if available): + +1. **Reproduce the bug** — Write a test or find a reliable reproduction case +2. **Find the root cause** — Trace the code path, narrow the scope, state the cause clearly +3. **Fix with TDD** — Minimal fix with regression test, no surrounding refactors +4. **Verify** — Run full verification, check for similar patterns elsewhere + +Then start with task 1. Mark each task in_progress when you begin it and completed when you finish it. Do not skip ahead — fixing without reproducing leads to patches that don't address the real problem. Fixing without understanding the root cause leads to whack-a-mole. + +--- + +## Phase 1: Reproduce + +Mark task 1 as in_progress. Before anything else, reproduce the bug reliably. Pick the right method based on where the bug lives: @@ -21,7 +42,13 @@ Before anything else, reproduce the bug reliably. Pick the right method based on If it can't be reproduced, add logging/assertions to gather more info — don't guess at a fix. Find the minimal reproduction case: strip away everything that isn't needed to trigger the bug. -### 2. Narrow down the cause +Mark task 1 as completed. + +--- + +## Phase 2: Find the root cause + +Mark task 2 as in_progress. Don't guess and patch — systematically narrow the scope: @@ -31,27 +58,41 @@ Don't guess and patch — systematically narrow the scope: **Check history (only if it used to work):** If a feature regressed, use `git bisect` to find the commit that broke it. Skip this for bugs that were always present. -### 3. Confirm root cause - -Before fixing, state the root cause clearly: +**Before proceeding, state the root cause clearly:** - What is the actual cause (not the symptom)? - Why does it happen? (e.g., "empty string bypasses validation and reaches the DB layer") - Under what conditions? (e.g., "only when the input is whitespace-only") -If you can't state this clearly, you haven't found the root cause yet — go back to step 2. +If you can't state this clearly, you haven't found the root cause yet — keep investigating. Present your root cause analysis to the user before fixing. -### 4. Fix with TDD +Mark task 2 as completed. + +--- + +## Phase 3: Fix with TDD + +Mark task 3 as in_progress. Follow `/tdd`: 1. Write a test that reproduces the exact bug — confirm it fails 2. Write the minimal fix — change only what's necessary, don't refactor surrounding code 3. Confirm the test passes and no other tests regress -### 5. Verify +Mark task 3 as completed. -- Run `/verify` to ensure nothing else broke -- Check that the fix addresses the root cause, not just the symptom -- If the same category of bug could occur elsewhere, grep for similar patterns +--- + +## Phase 4: Verify + +Mark task 4 as in_progress. + +1. Run `/verify` to ensure nothing else broke +2. Check that the fix addresses the root cause, not just the symptom +3. If the same category of bug could occur elsewhere, grep for similar patterns and flag them + +Mark task 4 as completed. + +--- ## Stop conditions diff --git a/.agents/skills/pr-fixup/SKILL.md b/.agents/skills/pr-fixup/SKILL.md index 4362973af3..fe1063a2fc 100644 --- a/.agents/skills/pr-fixup/SKILL.md +++ b/.agents/skills/pr-fixup/SKILL.md @@ -7,6 +7,11 @@ description: Wait for CI checks and automated reviews (CodeRabbit, Greptile) on Wait for CI and code review to complete on a pull request, fix any failures or valid comments, then push. +## Available skills and subagents + +- **`verify` subagent** — Run the full verification pipeline (format, typecheck, test, lint) before pushing fixes. +- **`/commit`** — Use for staging and committing fixes with Conventional Commits format. + ## Context - Current branch: !`git branch --show-current` diff --git a/.agents/skills/pr/SKILL.md b/.agents/skills/pr/SKILL.md index 136cb7c6ce..e0ebb1076d 100644 --- a/.agents/skills/pr/SKILL.md +++ b/.agents/skills/pr/SKILL.md @@ -5,6 +5,11 @@ description: Commit, push, and create a PR. Default is ready-for-review with aut # PR +## Available skills + +- **`/commit`** — Stage and commit changes using Conventional Commits. Runs `/verify` internally. +- **`/pr-fixup`** — Wait for CI checks and CodeRabbit review, fix any failures or valid comments, and push. + ## Context - Current git status: !`git status` @@ -17,13 +22,9 @@ description: Commit, push, and create a PR. Default is ready-for-review with aut - `--draft` — create the PR as draft and skip the fixup step. Use when the work is not ready for review. - Default (no flag) — create as ready-for-review and run `/pr-fixup` to wait for CI/CodeRabbit and fix issues. -## Your task +## Steps -Commit, push, and create a pull request. - -### Steps - -**Create a todo/task for each step below and mark them as completed as you go.** +**Create a task for each step below and mark them as completed as you go.** 1. **Uncommitted changes:** If there are dirty or staged changes, run `/commit` first (it runs `/verify` internally). @@ -36,7 +37,7 @@ Commit, push, and create a pull request. **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. + - **Summary** (required): 1-2 sentences of prose, no heading. Lead with the problem/goal, end with the outcome. Say WHY, not what. - **Important Changes** (optional): short bullet list of significant architectural changes. Remove section if not needed. - **Validation** (required): list commands or checks run (e.g. `go test ./...`, `make lint`). - **Diagram** (optional): Mermaid diagram only for non-obvious flows. Remove section if not needed. diff --git a/.agents/skills/push/SKILL.md b/.agents/skills/push/SKILL.md index e0c87054c3..efadd02c98 100644 --- a/.agents/skills/push/SKILL.md +++ b/.agents/skills/push/SKILL.md @@ -5,6 +5,11 @@ description: Commit and push to the current branch. Use --fixup to also wait for # Push +## Available skills + +- **`/commit`** — Stage and commit changes using Conventional Commits. Runs `/verify` internally. +- **`/pr-fixup`** — Wait for CI checks and CodeRabbit review, fix any failures, and push again. + ## Context - Current branch: !`git branch --show-current` diff --git a/.agents/skills/qa/SKILL.md b/.agents/skills/qa/SKILL.md index 5ba4deae1c..4d7e68a531 100644 --- a/.agents/skills/qa/SKILL.md +++ b/.agents/skills/qa/SKILL.md @@ -9,16 +9,44 @@ Verify that a feature works as intended after implementation. Assume bugs exist Mindset: you are not confirming it works — you are discovering where it breaks. -## Steps +## Available skills -### 1. Understand the intent +- **`/tdd`** — Use to write tests for any gaps found during QA. +- **`/e2e`** — Use to write Playwright E2E tests for user-facing flows that lack coverage. + +--- + +## Before starting: create the pipeline + +Create these tasks immediately (use your task/todo tracking tool if available): + +1. **Understand the intent** — Read task/PR/commits to understand what was built +2. **Trace the wiring** — Verify the feature is actually connected end-to-end +3. **Test the happy path** — Run the feature as a user would +4. **Try to break it** — Boundary values, error paths, concurrency, auth +5. **Verify test coverage** — Check for missing tests, write them if needed +6. **Report** — Summarize findings with verdict + +Mark each task in_progress when you begin it and completed when you finish it. + +--- + +## Phase 1: Understand the intent + +Mark task 1 as in_progress. Read the task description, PR, or recent commits to understand what was built and what it should do. Identify: - The expected behavior (happy path) - System boundaries (user input, API endpoints, external data) - Integration points (what calls what, data flow end-to-end) -### 2. Trace the wiring +Mark task 1 as completed. + +--- + +## Phase 2: Trace the wiring + +Mark task 2 as in_progress. Before testing behavior, verify the feature is actually connected: - Exports are imported and used (not just defined) @@ -28,14 +56,26 @@ Before testing behavior, verify the feature is actually connected: If something is orphaned or unwired, stop and report it — no point testing disconnected code. -### 3. Test the happy path +Mark task 2 as completed. + +--- + +## Phase 3: Test the happy path + +Mark task 3 as in_progress. Run the feature as a user would. For backend changes, call the API. For frontend changes, trace the UI flow. For both, follow the full path: - Does the basic use case work? - Does the response/output match expectations? - Is the data persisted correctly? -### 4. Try to break it +Mark task 3 as completed. + +--- + +## Phase 4: Try to break it + +Mark task 4 as in_progress. Systematically test these categories (skip what doesn't apply): @@ -58,14 +98,26 @@ Systematically test these categories (skip what doesn't apply): - Can the feature be accessed without proper auth? - Does it respect permission boundaries? -### 5. Verify test coverage +Mark task 4 as completed. + +--- + +## Phase 5: Verify test coverage + +Mark task 5 as in_progress. Check that the implementation has tests covering the behaviors you just verified: - Are the happy path and key error paths tested? -- Are edge cases from step 4 covered? -- If tests are missing, write them using `/tdd` +- Are edge cases from Phase 4 covered? +- If tests are missing, write them using `/tdd` (or `/e2e` for user-facing flows) -### 6. Report +Mark task 5 as completed. + +--- + +## Phase 6: Report + +Mark task 6 as in_progress. Summarize what was tested and what was found: @@ -79,3 +131,5 @@ Summarize what was tested and what was found: - Behaviors that work but have no automated test **Verdict:** Feature complete / Has issues — fix before merge + +Mark task 6 as completed. diff --git a/.agents/skills/simplify/SKILL.md b/.agents/skills/simplify/SKILL.md index eaf80877f9..15753b6b17 100644 --- a/.agents/skills/simplify/SKILL.md +++ b/.agents/skills/simplify/SKILL.md @@ -9,6 +9,10 @@ Post-implementation simplification pass. Review recently changed code and active The best code is code you don't have to write. The second best is code anyone can read. +## Available skills and subagents + +- **`verify` subagent** — Run after simplifications to ensure all tests, lints, and typechecks still pass. + ## Steps ### 1. Identify what to simplify diff --git a/.agents/skills/tdd/SKILL.md b/.agents/skills/tdd/SKILL.md index 96e4f4536d..e9addefe22 100644 --- a/.agents/skills/tdd/SKILL.md +++ b/.agents/skills/tdd/SKILL.md @@ -9,6 +9,11 @@ Implement code changes using strict Red-Green-Refactor. Iron law: **no productio Wrote code before a test? Delete it. Start over from a failing test. +## Available skills and subagents + +- **`/e2e`** — Use when the change needs a Playwright E2E test instead of a unit test. +- **`/verify`** — Run after completing all TDD cycles to ensure everything passes across the monorepo. + ## When to use - Bug fixes — write a test that reproduces the bug before fixing @@ -27,14 +32,9 @@ Wrote code before a test? Delete it. Start over from a failing test. ```bash cd apps && pnpm --filter @kandev/web test -- --run path/to/file.test.ts ``` -- **Web E2E** (`apps/web/e2e/`): Playwright tests with full-stack isolation (backend + frontend + DB per worker). Uses page objects in `e2e/pages/` and fixtures in `e2e/fixtures/`. Run: - ```bash - make test-e2e # all tests, headless - cd apps && pnpm --filter @kandev/web e2e -- tests/my-test.spec.ts # single file - make test-e2e-headed # with visible browser - ``` +- **Web E2E** (`apps/web/e2e/`): delegate to `/e2e` for Playwright tests. -Choose the right level: unit tests for isolated logic, web E2E for user-facing flows. +Choose the right level: unit tests for isolated logic, E2E for user-facing flows. ## Steps diff --git a/.agents/skills/verify/SKILL.md b/.agents/skills/verify/SKILL.md index b14182d7a8..c3f5ef0813 100644 --- a/.agents/skills/verify/SKILL.md +++ b/.agents/skills/verify/SKILL.md @@ -9,45 +9,64 @@ Run the full verification pipeline for the monorepo, then fix any issues found. ## Steps -1. **Rebase on main** (ensures CI parity — CI merges main into the PR branch): - ```bash - git fetch origin main --quiet - ``` - - If the current branch is `main`, skip this step. - - If the branch is stacked on another feature branch (not main), skip this step. - Detect: `git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null` — if the upstream is NOT `origin/main` (e.g., another feature branch), skip rebase. - - Otherwise, rebase: - ```bash - git rebase origin/main - ``` - - If the rebase has conflicts, resolve them: - 1. For each conflicted file, read the file and understand both sides of the conflict - 2. Resolve by keeping the correct combination of both changes (don't just pick one side) - 3. `git add ` then `git rebase --continue` - 4. Repeat for each conflicting commit until the rebase completes - 5. If a conflict is too ambiguous to resolve confidently, abort (`git rebase --abort`) and ask the user for guidance +**Create a task for each step below and mark them as completed as you go.** This pipeline must run in order — formatting before linting prevents formatter-induced lint failures. -2. **Format** (prevents formatter-induced lint failures): - - `make -C apps/backend fmt` - - `cd apps && pnpm format` +### 1. Rebase on main -3. **Verify in parallel** where possible: - - `make -C apps/backend test lint` - - `cd apps && pnpm --filter @kandev/web typecheck && pnpm --filter @kandev/web lint` +Ensures CI parity — CI merges main into the PR branch. -4. **Fix issues** — do NOT just report them: - - Read each failing file at the reported line number - - Fix the root cause (don't suppress warnings or add ignores) - - Common fixes: - - **Type errors**: fix the type, add a missing import, or correct the function signature - - **Lint — function too long**: extract a helper function or sub-component - - **Lint — file too long**: split the file into smaller, cohesive files grouped by responsibility (e.g., separate types, helpers, constants, or sub-domains into their own files) - - **Lint — cyclomatic/cognitive complexity**: simplify conditionals, extract early returns, break into smaller functions - - **Lint — unused imports**: remove them - - **Lint — duplicate strings**: extract to a constant - - **Test failures**: read the test, understand the assertion, fix the code (not the test) unless the test is outdated - - After fixing, re-run only the failed command to confirm the fix +```bash +git fetch origin main --quiet +``` -5. **Repeat** steps 3-4 until all commands pass. If a fix introduces new issues, address those too. +- If the current branch is `main`, skip this step. +- If the branch is stacked on another feature branch (not main), skip this step. + Detect: `git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null` — if the upstream is NOT `origin/main` (e.g., another feature branch), skip rebase. +- Otherwise, rebase: + ```bash + git rebase origin/main + ``` +- If the rebase has conflicts, resolve them: + 1. For each conflicted file, read the file and understand both sides of the conflict + 2. Resolve by keeping the correct combination of both changes (don't just pick one side) + 3. `git add ` then `git rebase --continue` + 4. Repeat for each conflicting commit until the rebase completes + 5. If a conflict is too ambiguous to resolve confidently, abort (`git rebase --abort`) and ask the user for guidance -6. **Done** when all pass cleanly: rebase, fmt, typecheck, test, lint. +### 2. Format + +Run formatters first — they may change line lengths which affects linter results. + +- `make -C apps/backend fmt` +- `cd apps && pnpm format` + +### 3. Verify in parallel + +Run these in parallel where possible: + +- `make -C apps/backend test lint` +- `cd apps && pnpm --filter @kandev/web typecheck && pnpm --filter @kandev/web lint` + +### 4. Fix issues + +Do NOT just report issues — fix them: + +- Read each failing file at the reported line number +- Fix the root cause (don't suppress warnings or add ignores) +- Common fixes: + - **Type errors**: fix the type, add a missing import, or correct the function signature + - **Lint — function too long**: extract a helper function or sub-component + - **Lint — file too long**: split the file into smaller, cohesive files grouped by responsibility (e.g., separate types, helpers, constants, or sub-domains into their own files) + - **Lint — cyclomatic/cognitive complexity**: simplify conditionals, extract early returns, break into smaller functions + - **Lint — unused imports**: remove them + - **Lint — duplicate strings**: extract to a constant + - **Test failures**: read the test, understand the assertion, fix the code (not the test) unless the test is outdated +- After fixing, re-run only the failed command to confirm the fix + +### 5. Repeat + +Repeat steps 3-4 until all commands pass. If a fix introduces new issues, address those too. + +### 6. Done + +All pass cleanly: rebase, fmt, typecheck, test, lint. Mark all tasks as completed.