Howells Arc Document

BANNED TOOLS — calling these is a skill violation:

• EnterPlanMode — BANNED. Do NOT call this tool. This skill has its own documentation generation process. Claude's built-in plan mode would bypass it.
• ExitPlanMode — BANNED. You are never in plan mode. There is nothing to exit.

REQUIRED TOOLS:

• AskUserQuestion — Preserve the one-question-at-a-time interaction pattern for every user question, including clarifying scope, choosing audience, and validating content. In Claude Code, use the tool. In Codex, ask one concise plain-text question at a time unless a structured question tool is actually available in the current mode. This prevents walls of text with multiple questions. If you need to provide context before asking, keep it to 2-3 sentences max, and do not narrate missing tools or fallbacks to the user.

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

• One question at a time via the AskUserQuestion interaction pattern — In Claude Code, use the tool. In Codex, ask one concise plain-text question at a time unless a structured question tool is actually available in the current mode. Never ask more than one question per message, and do not narrate missing tools or fallbacks to the user.
• Substance before meta-decisions — Scan the codebase and show what you found BEFORE asking about audience, format, or location. Users decide better with concrete context.
• Framework-aware, not framework-coupled — Detect existing docs frameworks and generate in their format. If none exists, generate plain markdown and recommend one. Never install or scaffold frameworks.
• Incremental validation — Generate a sample section first. Get approval on style and depth before generating the rest.
• Respect existing docs — When docs already exist, offer to add to the existing structure rather than replacing everything.
• Code examples from source — Every code example in generated docs must come from actual source code, never fabricated.

If a related task exists, note its ID and mark it in_progress with TaskUpdate when starting.

Check for recent documentation work or related changes.

Phase 1: Detect Intent & Context

Silently gather context (don't dump findings on the user):

1. Read package.json — identify stack, dependencies, project name
2. Scan directory structure — app/, pages/, src/, packages/
3. Check for existing docs — Glob docs/**/*.md, docs/**/*.mdx, content/**/*.md, content/**/*.mdx
4. Check for existing docs framework (see Framework Detection below)

Then determine intent from the user's input:

If user provided a file/directory path (e.g., /arc:document src/lib/auth.ts):

• Read the target file/directory
• Analyze: exports, types, dependencies, usage patterns
• Use AskUserQuestion:

  Question: "I see [file] exports [N] functions and [N] types. Should I..."
  Header: "Scope"
  Options:
    - label: "Document just this file"
      description: "Reference doc: exports, types, usage examples"
    - label: "Document the broader feature"
      description: "Feature guide: all related files, end-to-end"
  

• Route to Reference or Feature flow based on answer

If user provided a description (e.g., "document the auth feature"):

• Route to Feature flow

If user provided no args:

• Use AskUserQuestion:

  Question: "What would you like to document?"
  Header: "Scope"
  Options:
    - label: "A specific file or module"
      description: "I'll point you at a file and generate a reference doc"
    - label: "A feature"
      description: "End-to-end documentation for a feature across all its files"
    - label: "The entire project"
      description: "Full documentation site — I'll scan the codebase and generate everything"
  

• Route based on answer

Phase 2: Scope & Audience

Reference Flow

1. Read the target file completely
2. Analyze exports, types, interfaces, dependencies, imported-by relationships
3. Present findings: "[File] exports [list]. It depends on [list] and is used by [list]."
4. Ask audience via AskUserQuestion:

   Question: "Who is this documentation for?"
   Header: "Audience"
   Options:
     - label: "Developers"
       description: "How the code works: architecture, types, patterns, dependencies"
     - label: "Users"
       description: "How to use it: getting started, configuration, examples"
     - label: "Both"
       description: "Separate sections for developers and users"
   

Feature Flow

1. Identify all files that comprise the feature:
   • Routes/pages related to it
   • API endpoints
   • Components
   • Types/interfaces
   • Utilities/helpers
   • Tests
   • Configuration
2. Present: "The [feature] spans [N] files: [list key files]"
3. If existing docs directory found, ask via AskUserQuestion:

   Question: "I see existing docs at [path]. Should I..."
   Header: "Existing docs"
   Options:
     - label: "Add to existing structure"
       description: "Create new doc files in the existing docs directory"
     - label: "Create standalone"
       description: "Generate docs in a new location"
   

4. Ask audience (same as Reference flow)

Full-Site Flow

1. Scan the codebase. Identify documentable units:

   What	Detection
   Routes/Pages	Glob app/, pages/, src/app/
   API endpoints	Glob api/ routes, server actions, tRPC routers
   Components	Exported components with props/interfaces
   Packages	packages/*/package.json in monorepos
   Configuration	.env.example, config files, environment variables
   Database schema	Drizzle schema files, Prisma schema
   Authentication	Auth providers, middleware, protected routes
   CLI commands	bin/ or command definitions

2. Generate an outline. Present it to the user:

   I found [N] routes, [N] API endpoints, [N] packages, and a [database] schema.
   
   Proposed documentation outline:
   1. Getting Started
   2. Features
      - Auth (5 files)
      - Billing (3 files)
      - Notifications (4 files)
   3. API Reference
      - Users endpoint
      - Orders endpoint
   4. Architecture
      - Overview
   5. Reference
      - Components (12)
      - Utilities (8)
   

3. Ask for approval via AskUserQuestion:

   Question: "Does this outline look right?"
   Header: "Outline"
   Options:
     - label: "Yes, proceed"
       description: "Generate docs for all these sections"
     - label: "Remove some sections"
       description: "I'll tell you what to skip"
     - label: "Add something missing"
       description: "There's something I want documented that's not listed"
   

4. Ask audience (same question as Reference/Feature flow)

Phase 3: Framework Detection

Check package.json dependencies and project files:

If framework detected:

• Note the format silently
• Generate content in that format
• Detect existing content directory (e.g., content/docs/ for Fumadocs)

If no framework detected:

• Will generate plain markdown
• After sample validation, recommend a framework based on stack:
  • Next.js project → "Fumadocs would give you search, navigation, and a polished UI. Set it up with /arc:implement?"
  • Astro project → "Starlight is built for Astro and gives you great docs out of the box."
  • General → "Plain markdown works everywhere. If you want a docs site later, Fumadocs or VitePress are good options."
• Use AskUserQuestion:

  Question: "No docs framework detected. Want to..."
  Header: "Format"
  Options:
    - label: "Plain markdown"
      description: "Simple .md files with a README index. Works everywhere."
    - label: "Set up a framework first"
      description: "I'll recommend one for your stack. Use /arc:implement to scaffold it, then come back."
  

Phase 4: Sample & Validation

Before generating all docs, produce one sample section.

Pick the most representative section from the outline (or the target for Reference/Feature flow). Generate it fully.

Show the sample to the user, then ask via AskUserQuestion:

Question: "Here's the [section name] documentation. Is the depth and style right?"
Header: "Style check"
Options:
  - label: "Yes, generate the rest"
    description: "This depth and tone is what I want"
  - label: "More detailed"
    description: "Include more technical depth, more examples"
  - label: "Less detailed"
    description: "Keep it higher-level, less verbose"
  - label: "Different tone"
    description: "I'll describe what I want changed"

If user wants changes: adjust and regenerate the sample. Repeat until approved.

This validated sample becomes the style reference for all subsequent generation (and for docs-writer agents in full-site mode).

Phase 5: Location

Determine where docs should live.

If existing docs directory was found in Phase 1, propose using it.

Otherwise, ask via AskUserQuestion:

Question: "Where should the docs live?"
Header: "Location"
Options:
  - label: "docs/"
    description: "Standard convention at the repo root"
  - label: "apps/docs/content/"
    description: "Monorepo convention — docs as a separate app"

For Fumadocs projects, check source.config.ts for the configured content directory and use that.

Phase 6: Generation

Reference & Feature (small scope)

Single-pass generation. No agents needed.

1. Use the templates from ${ARC_ROOT}/templates/doc-templates.md
2. Read all source files identified in Phase 2
3. Generate documentation matching the validated style sample
4. Write files to the chosen location
5. If framework detected, generate sidebar config (meta.json, _meta.json, etc.)

Full-Site (large scope)

Spawn docs-writer agents in batches following ${ARC_ROOT}/disciplines/dispatching-parallel-agents.md.

1. Prepare agent assignments. Each outline section = one agent. Each agent gets:

   • Section name and description
   • List of source files to read (exact paths)
   • Audience: developer, user, or both
   • The validated style sample from Phase 4
   • Output format: .md or .mdx
   • Framework-specific instructions (sidebar config format, frontmatter requirements)
   • Output location

2. Dispatch in batches of 2-3.

   Batch 1: Agent → Features/Auth, Agent → Features/Billing
   Batch 2: Agent → API Reference, Agent → Architecture
   Batch 3: Agent → Components Reference, Agent → Getting Started
   

3. Collect results. Each agent returns file contents in delimiter format.

4. Write files. Create the directory structure and write each file.

Phase 7: Consolidation (full-site only)

After all agents return:

1. Terminology check — Scan all generated docs for the same concept called different names. Standardize.
2. Cross-reference check — Verify all internal links ([see auth](../features/auth.md)) point to real files.
3. Gap check — Compare generated docs against the outline. Flag any missing sections.
4. Fix issues — Rewrite affected sections. Don't rewrite everything.

Phase 8: Supporting Files

Generate supporting infrastructure:

For plain markdown:

• README.md — Index with links to all sections, using the full-site index template
• getting-started.md — Quick start guide (if full-site mode)

For Fumadocs:

• meta.json in each directory — sidebar ordering
• Root index.mdx — Landing page
• getting-started.mdx — Quick start guide (if full-site mode)

For Nextra:

• _meta.json in each directory

For other frameworks:

• Appropriate sidebar/navigation config

Completion

Present what was generated:

Documentation generated:

Files: [N] docs written
Location: [path]
Format: [markdown / Fumadocs MDX / etc.]
Audience: [developer / user / both]

Sections:
- Getting Started
- Features: Auth, Billing, Notifications
- API Reference: Users, Orders
- Architecture: Overview
- Reference: Components, Utilities

Then offer next steps via AskUserQuestion:

Question: "What's next?"
Header: "Next step"
Options:
  - label: "Review the docs"
    description: "I'll walk through each section for your approval"
  - label: "Add more sections"
    description: "Document additional features or modules"
  - label: "Set up a docs framework"
    description: "Scaffold a docs site with /arc:implement to host these"
  - label: "Done"
    description: "Documentation is complete"

Doc staleness detection: /arc:implement checks for stale docs after completing work. If changed files have associated documentation, they prompt the user to update inline.

Production readiness: /arc:letsgo includes documentation coverage as a checklist item.

Design context: /arc:ideate reads existing docs to understand the current feature set.

Framework scaffolding: If the user wants a docs site (Fumadocs, etc.), route them to /arc:implement for the infrastructure. /arc:document generates content, not apps.

Entry: /arc:document — [scope] ([audience]) [N files]

Examples:

• /arc:document — auth.ts reference (developer) 1 file
• /arc:document — auth feature guide (user) 3 files
• /arc:document — full site (both) 24 files

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