diff --git a/.claude/settings.json b/.claude/settings.json index d0269328c..0967ef424 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,9 +1 @@ -{ - "enabledPlugins": { - "code-simplifier@claude-plugins-official": true, - "frontend-design@claude-plugins-official": true, - "feature-dev@claude-plugins-official": true, - "code-review@claude-plugins-official": true, - "rust-analyzer-lsp@claude-plugins-official": true - } -} +{} diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 083d42f29..0967ef424 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -1,16 +1 @@ -{ - "env": { - "ANTHROPIC_API_KEY": "YOUR_API_KEY_HERE" - }, - "permissions": { - "allow": [ - "mcp__linear-server__get_issue", - "Bash(npx vitest:*)", - "Bash(bash tests/run.sh)", - "Bash(cargo test:*)", - "Bash(grep:*)", - "mcp__linear__list_milestones", - "Bash(npx markdownlint-cli:*)" - ] - } -} +{} diff --git a/.claude/skills/close-linear-issue/SKILL.md b/.claude/skills/close-linear-issue/SKILL.md deleted file mode 100644 index 1ff874b22..000000000 --- a/.claude/skills/close-linear-issue/SKILL.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -name: close-linear-issue -description: | - Closes a completed Linear issue after testing. Merges the PR, moves the issue to Done, and cleans up. - Triggers on "close ", "complete ", "merge ", "ship ", or "/close-issue". ---- - -# Close Linear Issue - -Merge a PR, move related Linear issues to Done, and clean up branches/worktrees safely. - -## Tool Contract - -Use these exact tools/commands: - -- Linear: `mcp__linear__get_issue`, `mcp__linear__list_issues`, `mcp__linear__save_issue`, `mcp__linear__save_comment` -- GitHub CLI: `gh pr list`, `gh pr view`, `gh pr checks`, `gh pr merge`, `gh pr edit` -- Git: `git worktree remove`, `git branch -D`, `git push origin --delete`, `git pull` - -Required fields: - -- Linear close: `save_issue` with `id` + `state: "Done"`, plus closing comment containing PR URL and merge commit. -- PR data: fetch with `gh pr view --json number,url,body,state,mergeCommit,statusCheckRollup,baseRefName,headRefName`. - -Fallback behavior: - -- Retry failed API/CLI step once. If still failing, stop and report exact command and output. - -## Required Checks Policy - -Before merge: - -1. Read branch protection/rulesets for the PR base branch. -2. List enforced required checks. -3. If required checks exist, wait on them via `gh pr checks --watch --required`. -4. If required checks list is empty, continue but post explicit risk comments on PR and Linear. - -## Idempotency Rules - -- If PR already merged, continue close flow without error. -- If issue already `Done`, skip state transition but still perform remaining cleanup/reporting. -- Avoid duplicate close comments by checking for existing comment containing same PR URL + merge SHA. -- If branch/worktree already removed, treat as success. - -## Output Hygiene - -- Use temp markdown files with `gh pr edit --body-file` for long PR updates. -- Never paste long command output into PR/Linear comments. - -## Identify - -1. Fetch issue details. -2. Find PR by `gitBranchName` (`gh pr list --head `). -3. Resolve worktree path `../worktrees/`. -4. Child handling: - - Fetch children via `mcp__linear__list_issues(parentId=issue.id)`. - - Parse PR body for both `Fixes ` and `Closes ` keywords. - - Any non-Done child not included in PR close keywords is a blocker. - -## Verify Test Plan - -Check PR body `## Test plan` section. - -- If unchecked items exist, stop and report which items remain unchecked. -- If section is absent, stop and report the missing section. -- Continue only after the PR test plan reflects completed automated and manual validation. - -## Merge - -Direct merge execution is allowed. - -1. First merge action (if PR is open): rebase branch onto `origin/main`. -2. Resolve conflicts when mechanical; escalate to user when judgment is needed. -3. Run `cd app && npx tsc --noEmit`. -4. Push with `--force-with-lease` if rebase changed history. -5. Apply required checks policy above. -6. Merge PR (prefer squash). -7. Capture merge commit SHA. - -## Close - -1. Move all linked issues to `Done`: - - Primary issue plus every issue found in `Fixes`/`Closes` keywords. -2. Add closing Linear comment with PR URL and merge SHA. -3. Cleanup from main repo: - - If worktree has uncommitted changes, capture `git status --porcelain` and ask user before force remove. - - `git worktree remove --force ` - - delete local branch - - delete remote branch - - pull latest `main` -4. Report closure status. - -## Error Recovery - -| Situation | Action | -| --- | --- | -| No PR found | Stop; instruct user to create PR via implement flow | -| Required checks failing | Stop and report failing checks | -| Merge conflict with semantic choice | Escalate to user | -| Worktree missing | Continue with PR + Linear close | -| Cleanup branch delete fails because already deleted | Continue | diff --git a/.claude/skills/create-linear-issue/SKILL.md b/.claude/skills/create-linear-issue/SKILL.md deleted file mode 100644 index 89c3dd730..000000000 --- a/.claude/skills/create-linear-issue/SKILL.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -name: create-linear-issue -description: | - Creates Linear issues from product thoughts, feature requests, or bug reports. Decomposes large issues into smaller ones. - Triggers on "create issue", "log a bug", "file a ticket", "new feature", "break down ", or "/create-issue". ---- - -# Create Linear Issue - -Turn a short product thought into a clear, product-level Linear issue. - -## Tool Contract - -Use these exact tools: - -- `mcp__linear__list_issues`: dedupe search and child discovery -- `mcp__linear__get_issue`: fetch parent issue for decomposition -- `mcp__linear__list_projects`: project selection -- `mcp__linear__get_project`: fetch full project details -- `mcp__linear__list_milestones`: milestone discovery for selected project -- `mcp__linear__list_cycles`: cycle discovery for the team -- `mcp__linear__list_issue_labels`: label selection -- `mcp__linear__save_issue`: create/update issue(s) -- `mcp__linear__save_comment`: optional rationale notes on parent - -Required fields: - -- New issue via `save_issue`: `team`, `title`, `project`, `milestone`, `cycle`; include `description`, `labels`, `estimate`, `assignee: "me"` when available. -- Decomposition child issue: must include parent reference in description and AC mapping. -- **`milestone` and `cycle` are mandatory.** Never create an issue without both. - -Fallback behavior: - -- If required Linear tools are unavailable or failing after one retry, stop and report missing capability. Do not fabricate IDs, labels, or project names. - -## Core Rules - -1. Product-level only. No file names, component names, or architecture in issue body. -2. Confirm before creating. Always show final issue draft before `save_issue`. -3. Clarifications: ask at most 2 targeted questions. If confidence is high (>=80%), default assumptions and proceed. -4. Idempotency: re-runs must not duplicate equivalent issues/comments. Reuse discovered open issue when appropriate. -5. Acceptance criteria in Linear must use Markdown checkboxes (`- [ ] ...`). -6. Resolve the target project from user input or existing issue context. Do not hardcode a project name in this skill. -7. Milestone selection must be from the resolved project only. If no clear milestone match exists, ask the user before creating the issue. Never omit milestone. -8. Cycle selection is mandatory. Use `list_cycles` to find the current or next cycle for the team. If ambiguous, ask the user. Never omit cycle. -9. Do not decompose by implementation layer (`frontend`/`backend`/`API`). Issues must represent integrated, user-visible outcomes that can be validated end-to-end. -10. Decomposition is allowed only by feature slices. Frontend-only splits are allowed only when each split is an independently testable feature outcome. - -## Outcomes - -- Request understood (feature, bug, or decompose) -- Requirements drafted and estimate confirmed -- Issue created (or child issues created) with traceable ACs - -## Understand the Request - -- If user intent is decompose (e.g., `break down `), follow **Decompose Path**. -- Otherwise classify as `feature` or `bug`. - -## Dedupe Check (required) - -Before creating any issue: - -1. Search open issues with `list_issues` using title/keyword query. -2. If a near-duplicate exists, present it and ask whether to reuse/update instead of creating a new one. - -## Issue Schema (required) - -Use this description template: - -```md -## Problem -... - -## Goal -... - -## Non-goals -- ... - -## Acceptance Criteria -- [ ] ... -- [ ] ... - -## Risks -- ... - -## Test Notes -- ... -``` - -## Estimate - -See `references/linear-operations.md` for estimate table. - -- `L` is the maximum single-issue size. -- If scope exceeds `L`, switch to decomposition. - -## Project, Milestone, and Cycle Resolution (required) - -Before drafting or creating an issue: - -1. Resolve the target project from explicit user input, parent issue context, or team defaults discovered through Linear. -2. Use `list_projects`/`get_project` to resolve the project ID/name. -3. Use `list_milestones` for that project and map feature intent to milestone candidates. -4. If exactly one milestone is a clear match, include it in the draft. -5. If project or milestone is ambiguous, ask the user before `save_issue`. -6. Never pick a milestone from a different project. -7. Use `list_cycles` with the team ID to find the current cycle. Default to the current active cycle; if none, use the next upcoming cycle. -8. If cycle is ambiguous, ask the user before `save_issue`. -9. Every issue must have both a milestone and a cycle before creation. Block on user input if either cannot be resolved. - -## Create Path - -1. Resolve project and fetch labels. -2. Resolve milestone candidates from that project. -3. Resolve cycle for the team (current or next). -4. Draft title, estimate, project, milestone, cycle, labels, description (schema above). -5. Confirm draft with user. -6. Create with `mcp__linear__save_issue` (`assignee: "me"` when allowed). Must include `milestone` and `cycle`. -7. Return issue ID + URL. - -## Decompose Path - -1. Fetch parent issue, resolve project, and fetch labels. -2. Split into 2-4 child issues, each <= `L`. -3. Traceability rule: each child maps to exactly one AC group from parent. -4. Resolve milestone candidates from the resolved project; if unclear, ask user before create. -5. Resolve cycle for the team (current or next). -6. Confirm child plan with user. -7. Create children with `save_issue` in parallel when safe. Each child must include `milestone` and `cycle`. -8. Update parent description to list child IDs and AC-group mapping. - -## Output Hygiene - -- Never inline long command/test output into Linear issue fields. -- Keep Linear description concise and product-facing. diff --git a/.claude/skills/create-linear-issue/references/bug-flow.md b/.claude/skills/create-linear-issue/references/bug-flow.md deleted file mode 100644 index e37092056..000000000 --- a/.claude/skills/create-linear-issue/references/bug-flow.md +++ /dev/null @@ -1,17 +0,0 @@ -# Bug Flow - -## Step 1: Investigation - -Spawn an `Explore` sub-agent to review code and recent git history. It returns the standard split: - -**INTERNAL (coordinator only):** likely root cause, affected scope, recent relevant commits, estimated fix complexity (XS/S/M/L). - -**FOR THE ISSUE:** user-visible symptom, reproduction steps, severity, frequency. - -## Step 2: Present Findings - -Show the user the product-level findings. Ask to confirm or correct. - -## Step 3: Estimate - -Use the sub-agent's internal scope signal. diff --git a/.claude/skills/create-linear-issue/references/feature-flow.md b/.claude/skills/create-linear-issue/references/feature-flow.md deleted file mode 100644 index ee9cf8c87..000000000 --- a/.claude/skills/create-linear-issue/references/feature-flow.md +++ /dev/null @@ -1,36 +0,0 @@ -# Feature Flow - -## Step 1: Proceed or Explore? - -Ask the user: proceed with the stated approach, or explore alternatives first? - -In both cases, the codebase is reviewed internally for feasibility. The difference is scope. - -## Step 2a: Direct Path - -Review the codebase directly to assess feasibility and scope. - -**INTERNAL (coordinator only):** feasibility, scope signal (XS/S/M/L), constraints. - -**FOR THE ISSUE:** numbered requirements + checkbox ACs. Product-level only. - -## Step 2b: Exploration Path - -When complexity is high, run parallel research. - -1. **Codebase analyst** — feasibility, constraints, scope (internal only) -2. **External researcher** — how similar products handle this, UX patterns, backend patterns - -Synthesize into 2-3 product-level options. Always include the user's original approach. No implementation details. - -## Step 3: User Picks - -Present options clearly and let the user pick one. - -## Step 4: Requirements Definition - -Write requirements for the chosen approach. Use INTERNAL / FOR THE ISSUE split. - -## Step 5: User Refinement - -Present requirements. Max 2 clarification rounds, then proceed with best assumptions. diff --git a/.claude/skills/create-linear-issue/references/linear-operations.md b/.claude/skills/create-linear-issue/references/linear-operations.md deleted file mode 100644 index 192e9fdff..000000000 --- a/.claude/skills/create-linear-issue/references/linear-operations.md +++ /dev/null @@ -1,23 +0,0 @@ -# Linear Operations - -Execute Linear operations directly by default using MCP tools. Use sub-agents only when parallel research is required. - -## Required MCP Tools - -- `mcp__linear__list_issues` -- `mcp__linear__get_issue` -- `mcp__linear__list_projects` -- `mcp__linear__list_issue_labels` -- `mcp__linear__save_issue` -- `mcp__linear__save_comment` - -If any required tool fails after one retry, stop and report the exact failing step. - -## Estimate Mapping - -| Label | Value | Agent effort | -|---|---|---| -| XS | 1 | < 10 min | -| S | 2 | ~30 min | -| M | 3 | 1-2 hours | -| L | 5 | Half day (max single issue) | diff --git a/.claude/skills/implement-linear-issue/SKILL.md b/.claude/skills/implement-linear-issue/SKILL.md deleted file mode 100644 index 173ce73db..000000000 --- a/.claude/skills/implement-linear-issue/SKILL.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -name: implement-linear-issue -description: | - Implements a Linear issue end-to-end, from planning through PR creation. - Triggers on "implement ", "work on ", "working on ", "build ", "fix ", or "/implement-issue". - Also triggers when the user simply mentions a Linear issue identifier (e.g. "ABC-123"). ---- - -# Implement Linear Issue - -Implement a Linear issue end-to-end and produce a review-ready PR. - -## Tool Contract - -Use these exact tools/commands: - -- Linear: `mcp__linear__get_issue`, `mcp__linear__list_issues`, `mcp__linear__save_issue`, `mcp__linear__save_comment` -- GitHub CLI: `gh pr create`, `gh pr edit`, `gh pr view`, `gh pr checks` -- Git: `git worktree`, `git status`, `git add`, `git commit`, `git push` - -Required fields: - -- Status transition via `save_issue`: `id`, `state`; include `assignee: "me"` when moving to active work. -- PR validation: `gh pr view --json url,number,body,state,headRefName,baseRefName,statusCheckRollup` - -Fallback behavior: - -- If a required Linear/GitHub operation fails after one retry, stop and report the exact failed step and command. - -## Required Checks Policy - -Before moving issue to `In Review`, inspect required checks for the base branch. - -- If required checks exist: ensure PR state/checks satisfy them. -- If required checks list is empty: continue, but post explicit risk comments on PR and Linear stating no required checks are enforced. - -## Idempotency Rules - -- Re-runs must be safe: - - Do not duplicate implementation notes comments if an equivalent note already exists. - - Do not reopen `Done/Cancelled/Duplicate` issues. - - If PR already exists for branch, update it instead of creating a new one. - - If worktree already exists on the correct branch, reuse it. - -## Output Hygiene - -- Always write PR bodies/long comments to temp markdown files and use `--body-file`. -- Never inline long command outputs into PR body, Linear description, or comments. - -## Autonomy - -Do not ask permission for non-destructive work. Only confirm with user: - -- Implementation plan for non-trivial scope -- Scope changes discovered during implementation -- Final status before moving to review - -## Setup - -1. Fetch issue via `mcp__linear__get_issue`. -2. Check child issues via `mcp__linear__list_issues(parentId=issue.id)`. -3. Status guard: - - `Done/Cancelled/Duplicate`: stop. - - `Todo`: assign to me + move to `In Progress`. - - `In Progress`: continue (assign to me if missing). - - `In Review`: move back to `In Progress`. -4. Create or reuse worktree at `../worktrees/`. - - If the branch is already checked out in the main worktree, detach main first (`git checkout --detach`) before creating the worktree. - - Never implement directly in the main worktree. If worktree creation fails, stop and report the error. - -## Approach Selection - -- XS/S + isolated changes: implement directly. -- M+ or multi-component: create a short plan, then execute with parallelism where useful. -- User can always override. - -## Branch Sync (required) - -Before running Quality Gates, rebase the working branch onto `origin/main`. - -1. Fetch latest `origin/main`. -2. Rebase current branch onto `origin/main`. -3. Resolve conflicts when mechanical; escalate to user when semantic judgment is required. -4. Push with `--force-with-lease` if history changed. - -## Quality Gates - -```text -Quality Gates: -- [ ] Tests written -- [ ] Tests passing -- [ ] Logging compliant -- [ ] Brand compliant -- [ ] Architecture compliant -- [ ] Code simplified (optional for large diffs) -- [ ] Code reviewed -- [ ] Docs updated -- [ ] Final validation -``` - -### Tests written - -Add targeted tests for changed behavior only. Update/remove obsolete tests. - -### Tests passing - -Run: - -1. `cd app && npx tsc --noEmit` -2. Test commands based on changed areas per repo guidelines. - -### Logging compliant - -Confirm changed code follows repo logging rules. - -### Brand compliant - -For changed frontend files, verify compliance with `.claude/rules/frontend-design.md`: no raw Tailwind color classes or hardcoded hex values, correct AD brand CSS variables, state indicator colours, and Lucide icons only. - -### Architecture compliant - -Verify changed code follows the data/calculation/action split and state management rules in `.claude/rules/coding-conventions.md`. Check business logic is not mixed with side effects and component-local state is not hoisted to global store. - -### Code simplified (optional) - -- Optional by default. -- Required only when diff is large (roughly >5 files or >300 LOC) or readability is clearly degraded. - -### Code reviewed - -Run a focused code review pass (directly or via sub-agent). - -### Docs updated - -Update docs only where behavior/commands/conventions changed. - -### Final validation - -Run final relevant tests after fixes/review. - -## Completion - -1. Verify checklist coverage against issue description: - - Evaluate every issue checkbox under Scope / Requirements / AC / Test Notes. - - Check only items that are demonstrably implemented in code/tests. - - Leave unverifiable or partial items unchecked. -2. Sync Linear checklist state: - - Update issue description checkboxes (`[ ]`/`[X]`) via `mcp__linear__save_issue`. - - Add one concise Linear comment with evidence for each newly checked item (file/test refs). -3. Create/update PR: - - Use `gh pr create/edit --body-file `. - - PR body must include `Fixes ` lines for primary issue and any included child issues. -4. Harden PR link: - - Run `gh pr view --json ...` and verify PR exists, is open, and `Fixes ` entries are present. -5. Generate concise implementation notes from: - - `git log --oneline main..HEAD` - - `git diff --stat main...HEAD` -6. Post implementation notes to Linear. -7. Branch protection awareness: - - Read required checks state; enforce policy above. -8. Move issue(s) to `In Review`. -9. Report PR URL, worktree path, recommended test mode, and manual test steps. -10. Do not remove worktree in implement flow. - -## Error Recovery - -| Situation | Action | -| --- | --- | -| Worktree exists on wrong branch | Remove and recreate | -| Linear API fails | Retry once, then stop with details | -| Tests fail after 3 attempts | Escalate with failure details | -| ACs remain unmet | Keep `In Progress` and report gaps | diff --git a/.claude/skills/implement-linear-issue/references/agent-team-guidelines.md b/.claude/skills/implement-linear-issue/references/agent-team-guidelines.md deleted file mode 100644 index 4abb8ad32..000000000 --- a/.claude/skills/implement-linear-issue/references/agent-team-guidelines.md +++ /dev/null @@ -1,24 +0,0 @@ -# Agent Team Guidelines - -## Team Leads - -Each work stream gets a team lead (spawned via `Task`). Provide: worktree path, issue ID, the ACs this stream owns, task list, and dependencies. - -Team leads coordinate within their stream — spawning sub-agents for parallel tasks, not writing code themselves. - -### Rules - -- **Test deliberately, not blindly.** Before writing any test code: - 1. Read existing tests for files you changed — understand what's already covered - 2. Update tests that broke due to your changes - 3. Remove tests that are now redundant - 4. Add new tests only for genuinely new behavior - 5. Never add tests just to increase count — every test must catch a real regression -- Commit + push before reporting (conventional commit format) -- Check off your ACs on Linear after tests pass -- Report back: what completed, tests updated/added/removed, ACs addressed, blockers -- Do NOT write to the Implementation Updates section (coordinator-only) - -## Failure Handling - -Max 2 retries per team before escalating to user. Pause dependent streams if a blocking failure occurs. diff --git a/.claude/skills/implement-linear-issue/references/fast-path.md b/.claude/skills/implement-linear-issue/references/fast-path.md deleted file mode 100644 index 2e4da39d2..000000000 --- a/.claude/skills/implement-linear-issue/references/fast-path.md +++ /dev/null @@ -1,18 +0,0 @@ -# Fast Path — Small Issues - -## When to Use - -Use when ALL are true: - -- Estimate is XS or S (1-2 points) -- Changes are isolated to one area of the codebase -- User can override in either direction - -## How It Works - -Skip team orchestration. Spawn a **single `general-purpose` sub-agent** that implements, updates/adds/removes tests as needed, commits, pushes, and checks off ACs on Linear. The agent must read existing tests before writing any — update broken tests, remove redundant ones, and only add tests for genuinely new behavior. -Only the **code reviewed** and **final validation** gates apply — the single agent handles tests and logging inline. Code review and PR creation are never skipped. - -**Always run `npx tsc --noEmit`** (from `app/`) before committing — catches type errors in untouched files that reference changed interfaces. - -Linear updates still apply — write what was done, tests, and PR link. diff --git a/.claude/skills/implement-linear-issue/references/git-and-pr.md b/.claude/skills/implement-linear-issue/references/git-and-pr.md deleted file mode 100644 index a0eed6cf2..000000000 --- a/.claude/skills/implement-linear-issue/references/git-and-pr.md +++ /dev/null @@ -1,46 +0,0 @@ -# Git and PR Conventions - -## PR Body Template - -Title: `VU-XXX: short description` - -```markdown -Fixes - - - - - - - -## Summary -[2-3 sentences from implementation status] - -## Changes -- [Bullet list from team reports] - -## Test plan -- [x] [Automated tests that passed, with counts] -- [ ] [Manual verification step 1] -- [ ] [Manual verification step 2] -- [ ] [... one checkbox per user-facing behavior to verify] - -## Acceptance Criteria -- [x] [AC 1] -- [x] [AC 2] -``` - -## Test Plan Guidelines - -The test plan section is **checked during `/close-issue`** — unchecked items block the merge. - -- **Automated tests**: Mark `[x]` immediately after tests pass. Include test counts. -- **Manual tests**: Leave `[ ]` unchecked. The user checks these off on the PR after manual testing. -- Write manual test items as concrete steps the user can follow (action → expected result). -- Cover every user-visible behavior change — not internals. - -After creating the PR, update the Linear issue via `mcp__linear__save_issue` and/or `mcp__linear__save_comment` with the PR URL. - -## Worktree Preservation - -**Do NOT remove the worktree.** The user tests manually on it. Include the worktree path in the final status report. diff --git a/.claude/skills/implement-linear-issue/references/linear-updates.md b/.claude/skills/implement-linear-issue/references/linear-updates.md deleted file mode 100644 index 6c4a12289..000000000 --- a/.claude/skills/implement-linear-issue/references/linear-updates.md +++ /dev/null @@ -1,23 +0,0 @@ -# Linear Issue Updates During Implementation - -## Core Rules - -1. **Rewrite, don't append.** The implementation updates section is a living snapshot — not an audit log. -2. **Never remove acceptance criteria.** Check them off or add new ones. -3. **Preserve the original issue description.** Append the Implementation Updates section below it. -4. **Pass real newlines**, never `\n` escape sequences. - -## What to Include - -- **Status** (In Progress / Blocked / Ready for Review) -- **Branch** and **PR** (once created) -- **What was done** — brief list of completed work -- **Tests** — what was tested - -Keep it concise. A fast-path S issue needs 5-10 lines, not a full report. - -## Who Writes What - -- **Coding agents** check off their ACs on Linear after tests pass -- **Coordinator** owns the Implementation Updates section (prevents race conditions) -- Update at meaningful checkpoints and at completion diff --git a/.claude/skills/implement-linear-issue/references/planning-flow.md b/.claude/skills/implement-linear-issue/references/planning-flow.md deleted file mode 100644 index 328faf819..000000000 --- a/.claude/skills/implement-linear-issue/references/planning-flow.md +++ /dev/null @@ -1,31 +0,0 @@ -# Planning Flow - -## Planning Mode - -For M+ or multi-component work, create a short plan first. Use sub-agents only when parallel planning/research is beneficial. - -Inputs: worktree path, issue title, requirements, acceptance criteria. - -The planner does a structural scan — understanding what areas are involved and dependencies, not implementation details. - -## Required Outputs - -The plan must cover: - -1. **Work streams** — what can run in parallel vs. what has dependencies -2. **AC mapping** — which stream/task addresses each acceptance criterion. Flag any uncovered ACs. -3. **Test strategy** — consult the project's test strategy to identify which tests cover the files being changed. For each work stream, specify: - - **Update**: existing test files that need changes to match new behavior - - **Remove**: tests that become redundant or test deleted behavior - - **Add**: new test files for genuinely new behavior - - **Run**: the full set of tests to execute after implementation -4. **Risk notes** — shared files, potential conflicts between streams -5. **Logging plan** — which new Rust commands need `info!`/`error!` logging, which frontend actions need `console.*` - -## Present Plan to User - -Show work streams, dependency chain, AC mapping, and risks. User may approve, adjust, or reorder. - -## On Plan Rejection - -If the user rejects the plan, revise it with the user's feedback. The revised plan must present 2-3 alternative approaches with trade-offs (scope, complexity, risk). If the chosen approach changes requirements or ACs, update the Linear issue via `mcp__linear__save_issue` before execution. diff --git a/.claude/skills/implement-linear-issue/references/review-flow.md b/.claude/skills/implement-linear-issue/references/review-flow.md deleted file mode 100644 index 81714e089..000000000 --- a/.claude/skills/implement-linear-issue/references/review-flow.md +++ /dev/null @@ -1,22 +0,0 @@ -# Review Flow - -## Code Review - -Run a focused code review directly. Use a sub-agent only for heavyweight or parallel review. - -## Fix Cycle - -- **High/medium severity** → must fix -- **Low severity** → fix if straightforward, otherwise note - -Spawn fix agents (parallel if touching different areas). **Max 2 review cycles** — then proceed with remaining low-severity notes. -Run fixes directly by default. Parallel fix sub-agents are optional when areas are independent. - -## Completion Criteria - -Before moving to Review on Linear, all of these must be true: - -- Relevant tests pass -- No outstanding high-severity issues -- PR created and linked -- Linear issue updated with final notes diff --git a/.claude/skills/implement-linear-issue/references/test-mode.md b/.claude/skills/implement-linear-issue/references/test-mode.md deleted file mode 100644 index c8914ff85..000000000 --- a/.claude/skills/implement-linear-issue/references/test-mode.md +++ /dev/null @@ -1,57 +0,0 @@ -# Test Mode Classification - -Determines whether a change needs **mock mode** or **full mode** for manual testing. - -## Decision Rule - -Run `git diff --name-only main` in the worktree. If **ANY** changed file matches a full-mode path, recommend full mode. Otherwise recommend mock mode. - -## Full Mode (`npm run dev`) - -Changes that affect agent execution or output quality. Requires an API key. - -| Path Pattern | Why | -|---|---| -| `agents/` | Agent prompt content | -| `agent-sources/workspace/CLAUDE.md` | Agent instructions | -| `app/sidecar/*.ts` (except `mock-agent.ts`, `mock-templates/`) | Sidecar runtime logic | -| `app/src-tauri/src/agents/` | Rust agent orchestration (sidecar.rs, sidecar_pool.rs) | -| `app/src-tauri/src/commands/workflow.rs` (agent-execution paths) | Workflow step dispatch | -| `app/sidecar/mock-templates/` | Mock replay data itself | -| SDK config or model selection logic | Affects which model runs | - -## Mock Mode (`MOCK_AGENTS=true npm run dev`) - -Everything else. Replays bundled JSONL templates (~1s per step, no API spend). - -- Frontend: components, pages, styles, routing (`app/src/`) -- Stores, hooks, utilities (`app/src/stores/`, `app/src/hooks/`, `app/src/lib/`) -- Non-agent Rust commands: settings, skills, files, git, dashboard, usage -- Tests and test infrastructure -- Scripts, docs, config files - -## Launch Commands - -**Mock mode** (from worktree): - -```bash -cd ../worktrees//app && MOCK_AGENTS=true npm run dev -``` - -**Full mode** (from worktree): - -```bash -cd ../worktrees//app && npm run dev -``` - -## Examples - -| Changed Files | Mode | Reason | -|---|---|---| -| `app/src/pages/dashboard.tsx`, `app/src/stores/skill-store.ts` | Mock | Pure UI + state | -| `app/src-tauri/src/commands/settings.rs` | Mock | Non-agent Rust command | -| `agents/confirm-decisions.md` | Full | Agent prompt change | -| `app/sidecar/run-agent.ts` | Full | Sidecar runtime | -| `app/src/components/workflow/AgentOutputPanel.tsx` | Mock | UI display of agent output (mock replays work) | -| `app/src-tauri/src/agents/sidecar.rs` | Full | Agent process management | -| `app/sidecar/mock-templates/step0-research.jsonl` | Full | Mock data itself changed | diff --git a/AGENTS.md b/AGENTS.md index 37f4e3a7f..0ad954204 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -137,9 +137,7 @@ Every new feature must include logging. Canonical logging conventions and log-le ## Gotchas -- **SDK has NO team tools:** `@anthropic-ai/claude-agent-sdk` does NOT support TeamCreate, TaskCreate, SendMessage. Use the Agent tool for sub-agents instead. Multiple Agent calls in the same turn run in parallel. - **Parallel worktrees:** `npm run dev` auto-assigns a free port — safe to run multiple Tauri instances simultaneously. - **Windows compatibility:** Path separators, CRLF line endings, env-var prefix syntax, and Rust toolchain selection are recurring sources of Windows CI failures. Follow `.claude/rules/windows-compat.md` before writing path assertions, regex, `package.json` scripts, or Rust CI config. - **Linear Markdown — no double-escaping:** The `description` and `body` fields in `save_issue`/`save_comment` accept raw Markdown. Write literal newlines, `*`, `-`, `[ ]` etc. directly. Never escape them (`\\n`, `\\*`, `\\[X\\]`) — double-escaped descriptions render as garbled text in Linear. -- **Business logic:** Use the data/calculation/action split across all layers (frontend, Rust, sidecar) — calculations must be pure functions, actions own all side effects. Full rules: `.claude/rules/coding-conventions.md`. - **State:** Component-local UI state must stay in `useState`, not Zustand. Use Zustand only for shared, cross-component, or navigation-persistent state. Full rules: `.claude/rules/state-management.md`.