howells/detail

<tool_restrictions>

MANDATORY Tool Restrictions

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. </tool_restrictions>

<arc_runtime> This workflow requires the full Arc bundle, not a prompts-only install.

Paths in this skill use these conventions:

• agents/..., references/..., disciplines/..., templates/..., scripts/..., rules/..., skills/<name>/... are Arc-owned files at the plugin root. Resolve the plugin root from this skill's filesystem location — it's the directory containing agents/ and skills/.
• ./... is local to this skill's directory.
• .ruler/..., docs/..., src/..., or any project-relative path refers to the user's project repository. </arc_runtime>

<required_reading> Read these reference files NOW:

1. references/testing-patterns.md
2. references/task-granularity.md
3. references/arc-paths.md

Load these only if relevant:

• references/model-strategy.md — if dispatching build agents
• references/component-design.md — React component patterns </required_reading>

<hard_rules> Before writing the plan file, present a brief summary of what you intend to plan (scope, task count estimate, key decisions) and use the AskUserQuestion interaction pattern to confirm. Plans must not appear without user input. </hard_rules>

<process> ## Step 1: Detect Project Stack

Use Glob tool to detect in parallel:

| Check | Glob Pattern | |-------|-------------| | Test frameworks | vitest.config.*, playwright.config.*, jest.config.*, cypress.config.* | | Package manager | pnpm-lock.yaml, yarn.lock, package-lock.json | | Python project | requirements.txt, pyproject.toml |

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 Feature Spec

Find the feature spec:

Primary: docs/arc/specs/*-spec.md
Fallbacks:
- docs/arc/specs/*.md
- docs/plans/*-spec.md
- 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 -spec.md or legacy -design.md with -implementation.md.

• Feature spec: docs/arc/specs/2025-06-15-user-dashboard-spec.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 feature spec implies multiple independent subsystems, stop and split the work into separate plans instead of forcing everything into one implementation plan.

Extract from the feature spec:

• User stories / acceptance criteria
• UI requirements and any external visual source
• 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 spec].
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 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 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 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

<test_commands> Based on detected test runner:

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"

</test_commands>

Step 5: Include UI Implementation Constraints

For each UI task, embed implementation-relevant UI requirements and external visual sources directly in the <action>. Do not invent visual direction in this skill. If the feature spec says the UI needs a visual direction that does not exist yet, create a checkpoint asking whether to pause for Chiaroscuro/Figma/user design input or continue by matching existing project patterns.

<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>
    UI requirements from feature spec:
    - Screens/states: product card in listing, loading, empty image fallback
    - Interaction: Add to Cart button updates state and announces result
    - Existing patterns: match src/components/product-list.tsx and src/components/ui/button.tsx
    - Visual source of truth: Figma URL below

    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"

    Structural sketch, if useful:
    ┌─────────────────┐
    │   [image]       │
    ├─────────────────┤
    │ Product Name    │
    │ $99.00          │
    │ [Add to Cart]   │
    └─────────────────┘

    Do not introduce new brand colors, typography, or motion beyond the external source or existing project patterns.
  </action>
  <test_code>
    // component rendering and interaction tests
  </test_code>
  <verify>
    pnpm vitest run src/components/product-card.test.tsx — all pass
    Component matches feature spec states and external visual source
  </verify>
  <done>ProductCard renders required states, Add to Cart works, tests pass</done>
  <commit>feat(ui): add product card interaction</commit>
</task>

Allowed UI sources:

• Feature spec UI requirements
• Existing project components and patterns
• Chiaroscuro or other external design spec
• Figma URL or user-provided screenshots
• docs/brand-system.md if present

Not allowed:

• Creating a new brand direction
• Choosing new typography/color/motion systems without an external source
• Treating structural sketches as visual design authority

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.

**Feature spec:** `docs/arc/specs/YYYY-MM-DD-<topic>-spec.md` (or legacy fallback path)
**Goal:** [One sentence from feature spec'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 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. </process>

<success_criteria> Implementation plan is complete when:

• [ ] Test framework detected
• [ ] Feature spec loaded
• [ ] Tasks written as XML with all required elements (<name>, <files>, <read_first>, <action>, <test_code>, <verify>, <done>, <commit>)
• [ ] Each task has exact file paths in <files>
• [ ] Each <action> contains inline values (no "look it up" references)
• [ ] Each <verify> has concrete, observable criteria (no "works correctly")
• [ ] Each <read_first> lists files the agent must check before acting
• [ ] UI tasks include implementation requirements and external visual source when relevant
• [ ] Plan-document-reviewer passes all 7 validation dimensions
• [ ] Plan committed to git </success_criteria>

<tool_restrictions_reminder> REMINDER: You must NEVER call EnterPlanMode or ExitPlanMode at any point during this skill — not at the start, not in the middle, not at the end. The plan file you just wrote IS the deliverable. Present it to the user as a normal message. </tool_restrictions_reminder>