# Howells Arc Build

> <tool_restrictions>

- Skill: `tomevault-io/howells-arc-build` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/howells-arc-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/howells-arc-build/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/howells-arc-build

---


<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:**
1. `references/testing-patterns.md` — Test philosophy
2. `references/frontend-design.md` — If UI work
3. `references/component-design.md` — If React components
</required_reading>

<agents>
**Build uses the same agents as implement:**

| 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) |
</agents>

<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):**

```markdown
## 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:

```bash
git branch --show-current
```

**If on main:**
```bash
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 (MANDATORY)

**Hard gate:** Test file must exist and fail before any implementation code is written.

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

### Step 4d: Quality Gates

**Fixer (TS/lint):**
```bash
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

```bash
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:**
```bash
git add .
git commit -m "feat([scope]): [description]"
```

**Report:**
```markdown
## 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:

```markdown
## 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:
- [ ] Build plan documented and confirmed
- [ ] Feature branch created
- [ ] Tests written first (appropriate level)
- [ ] Implementation complete
- [ ] Spec review passed
- [ ] Code review passed
- [ ] All tests passing
- [ ] TS/lint clean
- [ ] Build plan completion verified (every item checked against code)
- [ ] Progress journal updated
</success_criteria>

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/howells) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->