detail

What this skill does

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

**Build a read-only codebase map first when available:**

```bash
python3 scripts/codebase-map.py . --format markdown
```

Use the map to orient the pattern search around the project's framework, routes, data layer, service boundaries, largest files, high fan-in/fan-out modules, and import cycles. Treat the map as navigation context only; implementation tasks must still cite exact files from direct inspection.

**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.

Start from this codebase map when deciding where to look:
[paste scripts/codebase-map.py markdown output if available]

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.

```xml
<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:

```xml
<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