Howells Arc Detail

BANNED TOOLS — calling these is a skill violation:

• EnterPlanMode — BANNED. Do NOT call this tool. This skill IS the planning process. The steps below replace Claude's built-in planning entirely. You are NOT doing a task that needs plan mode — you ARE already executing a structured plan-creation process. Calling EnterPlanMode would bypass the skill and waste the user's time.
• ExitPlanMode — BANNED. You are never in plan mode. There is nothing to exit.

If you feel the urge to "plan before acting" — that urge is satisfied by following the <process> steps below. They ARE the plan. Execute them directly.

Load these only if relevant:

• ${ARC_ROOT}/references/model-strategy.md — if dispatching build agents
• ${ARC_ROOT}/references/frontend-design.md — if UI work involved
• ${ARC_ROOT}/references/ai-sdk.md — if ai in package.json

For UI work, also load interface rules:

• rules/interface/design.md — Visual principles
• rules/interface/colors.md — Color methodology
• rules/interface/spacing.md — Spacing system
• rules/interface/layout.md — Layout patterns
• rules/interface/animation.md — Motion rules
• rules/interface/forms.md — If forms involved
• rules/interface/interactions.md — Interaction patterns
• ${ARC_ROOT}/references/component-design.md — React component patterns

Use Glob tool to detect in parallel:

Use Grep tool on package.json:

• Pattern: "next" → Next.js
• Pattern: "react" → React

Record detected stack:

• Test runner: [vitest/jest/playwright/cypress/pytest]
• Package manager: [pnpm/yarn/npm/pip/uv]
• Framework: [next/react/fastapi/etc]

Step 2: Load Design Document

Find the design doc:

Glob: docs/arc/specs/*-design.md
Fallback: docs/plans/*-design.md

Pick the most recent one (highest date prefix). Read it. This is the source of truth for what to build.

Derive implementation plan filename: Replace -design.md with -implementation.md.

• Design: docs/arc/specs/2025-06-15-user-dashboard-design.md
• Implementation: docs/arc/plans/2025-06-15-user-dashboard-implementation.md

Step 2.2: Lock File Structure Before Tasks

Before defining tasks, write a short file map:

• Which files will be created or modified
• What responsibility each file owns
• Where boundaries or interfaces matter
• Whether any file is already too large or too tangled for a clean change

If the design implies multiple independent subsystems, stop and split the work into separate plans instead of forcing everything into one implementation plan.

Extract from the design doc:

• User stories / acceptance criteria
• ASCII UI wireframes
• Data model
• Component structure
• API surface

Step 2.5: Find Reusable Patterns (Parallel Agents)

Spawn agents to find existing code to leverage:

Task Explore model: haiku: "Find existing patterns in this codebase that we can
reuse for: [list components/features from design].
Look for: similar components, utility functions, hooks, types, test patterns.

Structure your findings as:
## Reusable Code
- `file:line` — what it provides and how to use it

## Similar Implementations
- Feature and entry point file:line

## Essential Files for This Feature
List 5-10 files most critical to understand before implementing:
- `file.ts` — why it matters
"

Task Explore model: haiku: "Analyze coding conventions in this project. What naming patterns,
file organization, and architectural patterns should new code follow?"

If using unfamiliar libraries/APIs:

Task general-purpose model: haiku: "Gather documentation and best practices for
[library name] focusing on [specific feature needed]."

When agents complete:

• List reusable code (with file paths)
• Note conventions to follow
• Share Essential Files list — these should be read before implementation
• Update task breakdown to use existing utilities

Step 3: Break Down Into Tasks

Each task = one TDD cycle (2-5 minutes), written as XML:

Tasks are executable prompts, not documentation. A fresh-context agent should be able to execute any task from the XML alone. See ${ARC_ROOT}/references/task-granularity.md for the full XML schema.

<task id="1" depends="" type="auto">
  <name>Create user authentication types</name>
  <files>
    <create>src/types/auth.ts</create>
    <test>src/types/auth.test.ts</test>
  </files>
  <read_first>
    src/types/user.ts
  </read_first>
  <action>
    Define LoginCredentials, AuthSession, and AuthError types.
    Use zod schemas for runtime validation.
    Import User type from src/types/user.ts.
  </action>
  <test_code>
    // exact test code
  </test_code>
  <verify>
    pnpm vitest run src/types/auth.test.ts — all pass
    pnpm tsc --noEmit — no type errors
  </verify>
  <done>Auth types exported, zod schemas validate, tests pass</done>
  <commit>feat(auth): add authentication types with zod validation</commit>
</task>

Required elements per task: <name>, <files>, <read_first>, <action>, <test_code>, <verify>, <done>, <commit>. See ${ARC_ROOT}/references/task-granularity.md for details.

Key rules for task content:

• <action> must contain inline values (env vars, function signatures, library choices with rationale) — never "look it up"
• <verify> must be concrete commands or observable states — never "works correctly" or "looks good"
• <read_first> lists files the agent must verify before acting — prevents assumptions about file state

Checkpoint Tasks

When a task requires human judgment, use the appropriate type attribute:

<task id="5" depends="1,2,3,4" type="checkpoint:verify">
  <name>Verify dashboard layout</name>
  <action>
    Agent starts dev server automatically before presenting checkpoint.

    Verify at http://localhost:3000/dashboard:
    1. Desktop (>1024px): Sidebar visible, content fills remaining
    2. Tablet (768px): Sidebar collapses
    3. Mobile (375px): Single column layout
  </action>
  <verify>User approves or describes issues</verify>
  <done>Dashboard layout approved at all breakpoints</done>
</task>

<task id="3" depends="" type="checkpoint:decide">
  <name>Select authentication provider</name>
  <action>
    Options:
    1. Clerk — Best DX, pre-built UI, paid after 10k MAU
    2. NextAuth — Free, self-hosted, maximum control
    3. Supabase Auth — Built-in with our DB

    Recommendation: Clerk (fastest to ship)
  </action>
  <verify>User selects provider</verify>
  <done>Auth provider selected, decision recorded</done>
</task>

Rules:

• Automate everything possible before a checkpoint (start servers, deploy, etc.)
• Never ask user to run CLI commands — agent does it
• Max 1 checkpoint per logical milestone
• checkpoint:action tasks are created DYNAMICALLY during execution (auth gates), not pre-planned
• See ${ARC_ROOT}/references/checkpoint-patterns.md

Task ordering:

1. Data/types first (foundation)
2. Core logic (business rules)
3. UI components (presentation)
4. Integration (wiring together)
5. E2E tests (full flow verification)

Step 4: Generate Test Commands

vitest:

# Single test file
pnpm vitest run src/path/to/file.test.tsx

# Single test
pnpm vitest run src/path/to/file.test.tsx -t "test name"

# Watch mode (for development)
pnpm vitest src/path/to/file.test.tsx

playwright:

# Single test file
pnpm playwright test tests/path/to/file.spec.tsx

# Single test
pnpm playwright test tests/path/to/file.spec.tsx -g "test name"

# With UI
pnpm playwright test --ui

jest:

# Single test file
pnpm jest src/path/to/file.test.tsx

# Single test
pnpm jest src/path/to/file.test.tsx -t "test name"

Step 5: Include UI References

For each UI task, embed aesthetic direction and references directly in the <action>:

<task id="7" depends="5,6" type="auto">
  <name>Create ProductCard component</name>
  <files>
    <create>src/components/product-card.tsx</create>
    <test>src/components/product-card.test.tsx</test>
  </files>
  <read_first>
    src/components/ui/card.tsx
    src/lib/utils.ts
  </read_first>
  <action>
    Aesthetic Direction (from design doc):
    - Tone: luxury/refined
    - Memorable: hover lift with shadow bloom
    - Typography: GT Sectra display + IBM Plex Sans body
    - Color: warm neutrals, gold accent
    - Motion: subtle hover states, no page transitions

    Figma: https://figma.com/design/xxx/yyy?node-id=123-456
    Screenshot: docs/arc/specs/assets/YYYY-MM-DD-topic/figma-123-456.png
    Fetch fresh context: mcp__figma__get_design_context fileKey="xxx" nodeId="123:456"

    ASCII Wireframe:
    ┌─────────────────┐
    │   [image]       │
    ├─────────────────┤
    │ Product Name    │
    │ $99.00          │
    │ [Add to Cart]   │  ← hover lift + shadow bloom
    └─────────────────┘

    AVOID: Roboto/Arial/system-ui, purple gradients, generic shadows
    ENSURE: The hover effect is the memorable moment
  </action>
  <test_code>
    // component rendering and interaction tests
  </test_code>
  <verify>
    pnpm vitest run src/components/product-card.test.tsx — all pass
    Visual: hover effect produces distinct shadow bloom, not generic box-shadow
  </verify>
  <done>ProductCard renders with luxury aesthetic, hover lift works, tests pass</done>
  <commit>feat(ui): add ProductCard with hover shadow bloom</commit>
</task>

Why all three (aesthetic + Figma + ASCII):

• Aesthetic direction = the creative vision
• ASCII = structure and layout intent
• Figma = exact implementation details
• All three ensure the result is intentional, not generic

Step 6: Write Implementation Plan

Header:

# [Feature Name] Implementation Plan

> **For Arc:** Use /arc:implement to execute this plan. Subagents should report DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, or BLOCKED.

**Design:** `docs/arc/specs/YYYY-MM-DD-<topic>-design.md` (or legacy fallback path)
**Goal:** [One sentence from design doc's problem statement]
**Stack:** [Framework] + [Test runner] + [Package manager]

---

Tasks section: Write all tasks following the template from Step 3.

Save to: The filename derived in Step 2 (e.g., docs/arc/plans/2025-06-15-user-dashboard-implementation.md)

Step 6.5: Review The Plan Document

After writing the plan:

1. Dispatch ${ARC_ROOT}/agents/workflow/plan-document-reviewer.md
2. Fix issues in the plan
3. Re-review until approved or after 5 loops escalate to the user

Step 7: Commit and Offer Next Steps

git add docs/arc/plans/
git commit -m "docs: add <topic> implementation plan"

Plan is ready. Tell the user the plan is saved and offer next steps as plain text. Do NOT call EnterPlanMode or ExitPlanMode. Just print the summary and ask what they want to do next.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.