<tool_restrictions>

MANDATORY Tool Restrictions

REQUIRED TOOLS — use these when indicated:

AskUserQuestion — REQUIRED for all user-facing questions. Use structured options instead of plain text.

BANNED TOOLS — calling these is a skill violation:

EnterPlanMode — BANNED. Do NOT call this tool. This skill has its own lightweight planning process. Execute it directly.
ExitPlanMode — BANNED. You are never in plan mode. </tool_restrictions>

<required_reading> Read these before building:

references/testing-patterns.md — Test philosophy
references/frontend-design.md — If UI work
references/component-design.md — If React components </required_reading>

Agent	Model	Use For
`implementer`	opus	General implementation (utilities, services)
`ui-builder`	opus	UI components from spec
`design-specifier`	opus	Design decisions when no spec exists
`unit-test-writer`	sonnet	Unit tests (vitest)
`integration-test-writer`	sonnet	Integration tests (vitest + MSW)
`e2e-test-writer`	opus	E2E tests (Playwright)
`fixer`	haiku	TS/lint cleanup
`debugger`	sonnet	Failing tests
`test-runner`	haiku	Run vitest, analyze results
`spec-reviewer`	sonnet	Verify matches spec
`code-reviewer`	haiku	Code quality gate
`plan-completion-reviewer`	sonnet	Whole-plan gate (if >3 tasks)

<rules_context> Check for project coding rules:

Use Glob tool: .ruler/*.md

If .ruler/ exists, read relevant rules by detection:

Always load:

code-style.md — formatting, naming, file organization
typescript.md — type definitions, strict mode
error-handling.md — error boundaries, Result patterns
security.md — OWASP, input validation, secrets
env.md — environment variable handling
git.md — commit conventions, branching
testing.md — test strategy, coverage requirements
versions.md — minimum version requirements
stack.md — approved technologies

Load by detection:

React (react/next): react.md, react-correctness.md, react-performance.md
Next.js (next): nextjs.md
Tailwind (tailwindcss): tailwind.md
Drizzle/Prisma: database.md
wrangler.toml: cloudflare-workers.md
AI SDK (ai): ai-sdk.md
Clerk/WorkOS: auth.md
API routes or tRPC: api.md
CLI tools: cli.md
External services: integrations.md
Turborepo (turbo.json): turborepo.md
Tooling (biome, eslint): tooling.md
SEO-relevant pages: seo.md

If .ruler/ does NOT exist, suggest running /arc:rules first.

For UI work, load interface rules from rules/interface/:

Always for UI:

design.md — visual design principles
colors.md — color system and palette
spacing.md — spacing scale and consistency
typography.md — type scale, font choices
layout.md — layout patterns, grid systems

By detection:

Forms: forms.md — form design, validation UX
Animations/transitions: animation.md — motion principles
Interactive components: interactions.md — hover, focus, click patterns
App UI (authenticated): app-ui.md — dashboard, settings patterns
Marketing pages: marketing.md — landing page patterns
Responsive work: responsive.md — breakpoints, mobile-first
Accessibility: content-accessibility.md — WCAG, screen readers
Performance: performance.md — rendering, loading optimization </rules_context>

When to Use Build vs Ideate

Use Build	Use Ideate
Single component	New app or major feature
Add utility function	Multiple interconnected features
Extend existing feature	New architecture patterns
1-5 files affected	10+ files affected
Clear requirements	Exploratory/unclear scope

If in doubt: Start with build. If scope grows, pivot to ideate.

Process

Phase 1: Scope Check

Assess the request:

How many files will this touch?
Is this UI, logic, or both?
Does it need design decisions?
What test levels needed?

If scope is large (>5 files, new patterns):

AskUserQuestion:
  question: "This looks substantial — multiple features and new patterns. Would benefit from /arc:ideate for proper design."
  header: "Scope Check"
  options:
    - label: "Switch to /arc:ideate"
      description: "Start a full design process for this larger scope"
    - label: "Continue with /arc:build"
      description: "Keep going with lightweight planning despite the scope"

If scope is appropriate: Proceed.

Phase 2: Create Build Plan

Document a lightweight plan (not just mental notes):

## Build Plan: [Feature Name]

### What We're Building
[1-2 sentence description]

### Files to Create/Modify
| File | Action | Purpose |
|------|--------|---------|
| src/components/OrgSwitcher.tsx | Create | Main component |
| src/components/OrgSwitcher.test.tsx | Create | Unit tests |
| src/hooks/useOrganizations.ts | Create | Data fetching hook |

### Implementation Approach
1. [First step]
2. [Second step]
3. [Third step]

### Agents Needed
| Task | Agent |
|------|-------|
| Component UI | ui-builder or design-specifier |
| Hook logic | implementer |
| Unit tests | unit-test-writer |
| Integration tests | integration-test-writer (if API calls) |

### Test Coverage
- Unit: [what to test]
- Integration: [what to test, if any]
- E2E: [what to test, if critical flow]

### Design Decisions (if UI)
- [ ] Needs design-specifier? [yes/no]
- [ ] Has existing patterns to follow? [reference]

Share the plan with the user, then confirm:

AskUserQuestion:
  question: "Here's my build plan. Look right?"
  header: "Confirm Build Plan"
  options:
    - label: "Looks good"
      description: "Proceed with the plan as written"
    - label: "Needs changes"
      description: "I want to adjust the plan before you start building"

Wait for confirmation before proceeding.

Phase 3: Set Up Branch

If not on a feature branch:

git branch --show-current

If on main:

git checkout -b feat/[feature-name]
# or for isolated work:
git worktree add .worktrees/[feature-name] -b feat/[feature-name]

Phase 4: Execute Build

For each task in the plan, follow the per-task loop:

┌─────────────────────────────────────────────────────────┐
│  1. TEST      → spawn test agent (unit/integration)     │
│  2. BUILD     → spawn build agent (implementer/ui)      │
│  3. TDD       → run test (fail → impl → pass)           │
│  4. FIX       → fixer (TS/lint cleanup)                 │
│  5. SPEC      → spec-reviewer (matches plan?)           │
│  6. QUALITY   → code-reviewer (well-built?)             │
│  7. COMMIT    → atomic commit                           │
└─────────────────────────────────────────────────────────┘

Step 4a: Write Tests First

Determine test type:

Building	Test Agent
Pure function/hook	unit-test-writer
Component with props	unit-test-writer
Component + API	integration-test-writer
Auth-related	integration-test-writer (with Clerk/WorkOS mocks)

Spawn test agent:

Task [unit-test-writer] model: sonnet: "Write unit tests for [component/function].

From build plan:
- [what to test]
- [edge cases]

File: [path]"

Step 4b: Build Implementation

Select build agent based on task:

For UI components:

Task [ui-builder] model: opus: "Build [component] from plan.

Requirements:
- [from build plan]

Existing patterns: [reference similar components]
Follow spacing and design rules."

For logic/utilities:

Task [implementer] model: opus: "Implement [function/service].

Requirements:
- [from build plan]

Follow project conventions."

If design decisions needed (no existing spec):

Task [design-specifier] model: opus: "Design [component/feature].

Context: [what it's for]
Output spec for ui-builder."

Step 4c: TDD Cycle

pnpm vitest run [test-file]  # Should FAIL first
# Implementation happens
pnpm vitest run [test-file]  # Should PASS

Step 4d: Quality Gates

Fixer (TS/lint):

pnpm tsc --noEmit
pnpm biome check --write .

If issues:

Task [fixer] model: haiku: "Fix TS/lint errors in [files]"

Spec review:

Task [spec-reviewer] model: sonnet: "Verify implementation matches build plan.

Plan said: [requirements]
Files: [list]

Check: nothing missing, nothing extra."

Code quality:

Task [code-reviewer] model: haiku: "Quick code quality check.

Files: [list]
Check: no any, error handling, tests exist."

Phase 5: Final Verification

pnpm test              # All tests pass
pnpm tsc --noEmit      # No TS errors
pnpm biome check .     # No lint errors

If UI work, screenshot and verify:

mcp__claude-in-chrome__computer action=screenshot

Phase 5.5: Plan Completion Check

Re-read the build plan from Phase 2. For each item in the plan:

Is it implemented? (read the actual file, don't trust memory)
Is it substantive? (not a stub or placeholder)
Is it wired up? (imported where needed, rendered, called)

If >3 tasks in the build plan, spawn plan-completion-reviewer:

Task [plan-completion-reviewer] model: sonnet: "Verify implementation matches build plan.

BUILD PLAN:
[paste build plan from Phase 2]

FILES CHANGED:
[list files created/modified]

Check every item was built. Nothing skipped, nothing extra."

Do NOT proceed to Phase 6 until every item in the build plan is verified.

Phase 6: Complete

Commit:

git add .
git commit -m "feat([scope]): [description]"

Report:

## Build Complete: [Feature]

### Created
- [file] — [purpose]

### Tests
- Unit: [N] tests
- Integration: [N] tests (if any)

### Verified
- [X] All tests passing
- [X] TS/lint clean
- [X] Spec review passed
- [X] Code review passed

Offer next steps:

AskUserQuestion:
  question: "Build complete. What would you like to do next?"
  header: "Next Steps"
  options:
    - label: "Merge to main"
      description: "Merge the feature branch into main"
    - label: "Create PR"
      description: "Push the branch and open a pull request"
    - label: "Add more features"
      description: "Continue building on this branch"
    - label: "Done"
      description: "Nothing else needed right now"

<progress_append> After completing the build:

## YYYY-MM-DD HH:MM — /arc:build
**Task:** [What was built]
**Outcome:** Complete
**Files:** [Key files]
**Agents used:** [list]
**Tests:** [N] unit, [N] integration
**Next:** [Merge / PR / Continue]

---

</progress_append>

<success_criteria> Build is complete when: