execute-docs

---
name: execute-docs
description: Scaffolds tailored project documentation — `CLAUDE.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `DESIGN_SYSTEM.md`, `TASKS.md`. Reads upstream planning artifacts (MVP_SPEC, FEATURES, UX, DESIGN.md) and short-circuits discovery questions when present. Use when setting up a new project or adding doc structure to an existing repo.
---

# Execute Docs

Generate a complete set of project documentation files that give Claude (and human developers) full context on how to build within a project. This skill creates tailored, interconnected docs — not generic templates.

## When to Use

- Starting a new project from scratch
- Adding structure to an existing project that lacks docs
- Migrating or rebranding a project and need fresh docs
- Setting up a repo so Claude Code can work effectively in it

## What Gets Generated

| File | Purpose |
|------|---------|
| `CLAUDE.md` | Root-level instructions for Claude — points to all other docs |
| `docs/ARCHITECTURE.md` | System overview, project structure, data flow, schema, integrations |
| `docs/CONVENTIONS.md` | Copy-paste code patterns, library-specific idioms, breaking changes |
| `docs/DESIGN_SYSTEM.md` | Stack-specific implementation of the brand spec — CSS vars / SwiftUI tokens, component patterns, accessibility |
| `docs/TASKS.md` | Phase scaffold with placeholder tasks (expanded on-demand by `execute-features-web` (or `-ios`)) |

## Upstream Skills

This skill is the consolidator at the end of the planning pipeline. When upstream artifacts exist, this skill reads them and short-circuits the related discovery questions. The expected pipeline:

```
plan-mvp → plan-features → plan-ux-* → plan-design → execute-docs → execute-features-{web,ios}
```

| Upstream skill | Produces | Effect on execute-docs |
|---|---|---|
| `plan-mvp` | `planning/MVP_SPEC.md` | Skip "project name, type, scope, features" questions |
| `plan-features` | `planning/FEATURES.md` (single mode) or `planning/features/` directory (split mode) | Skip feature-list questions; reference from ARCHITECTURE; drives task expansion in execute-features-{web,ios} |
| `plan-ux-web` / `plan-ux-app` / `plan-ux-ios` | `docs/UX.md` | Skip "main pages/screens" question; drives TASKS.md phase structure; component list seeds DESIGN_SYSTEM.md |
| `plan-design` | `docs/DESIGN.md` (or library entry) | Skip design questions; treated as source of truth and do-not-edit; DESIGN_SYSTEM.md derives implementation from it |

None of these are required. If they're missing, this skill prompts to run them (hard prompt for UX/FEATURES, soft note for DESIGN.md) and offers to invoke them in the same session.

## Workflow

### Step 1: Detect Upstream Artifacts

Before asking any discovery questions, check for upstream planning artifacts. Each one short-circuits a chunk of discovery.

**Check for these files in order:**

```bash
# Run from the project root
ls planning/MVP_SPEC.md planning/FEATURES.md planning/features/README.md docs/UX.md docs/DESIGN.md 2>/dev/null
```

Also check the user's design library: `ls ~/.claude/design-md-library/` to see if a brand-matched DESIGN.md exists there.

**For each artifact found, read it and note:**
- `MVP_SPEC.md` → project name, type, scope, feature list, intent
- `FEATURES.md` (single mode) OR `planning/features/README.md` (split mode) → feature list, status, dependencies, phase assignments. **In split mode, do not read individual feature files** — the README index is enough for `execute-docs`. Individual files are read by `execute-features-web` (or `-ios`) during task expansion.
- `UX.md` → page/screen list, conversion models, components needed per page
- `DESIGN.md` → brand spec (tokens, typography, motion, voice)

**Resolve features mode:** If both `FEATURES.md` and `planning/features/` somehow exist, ask the user which is canonical (don't guess — they may be mid-migration). If only one exists, use it. If neither exists, prompt to run `plan-features`.

**For each artifact missing, prompt the user:**

| Missing | Prompt strength | Behavior |
|---|---|---|
| `FEATURES.md` or `planning/features/` | **Hard** | "I notice no feature specs exist. `plan-features` produces buildable per-feature specs (single file or split files) that make TASKS.md and `execute-features-{web,ios}` much more concrete. Run it now (recommended), or proceed without?" |
| `UX.md` | **Hard** | "I notice no UX.md exists. `plan-ux-web` (marketing) / `plan-ux-app` (web app) / `plan-ux-ios` (iOS) define pages/screens, conversion or engagement models, and components — TASKS.md phases derive from it. Run the right variant now (recommended), or proceed without?" |
| `DESIGN.md` | **Soft** | After generating, mention: "Consider running `plan-design` to add a brand spec — DESIGN_SYSTEM.md will reference it as source of truth." |
| `MVP_SPEC.md` | None | Optional upstream; just proceed with discovery |

If the user agrees to run an upstream skill, invoke it in the same session, then re-enter this skill's Step 1 to re-detect.

### Step 2: Discovery Interview

Ask the user these questions to gather enough context. **Skip any question whose answer is already in an upstream artifact you read in Step 1.** Don't ask them all at once — group them naturally and adapt based on answers. Skip questions where the answer is obvious from context (e.g., if you're already in a Next.js project).

**Project Basics:** *(skip if MVP_SPEC.md exists)*
- What's the project name and one-line description?
- What type of project? (web app, content site, iOS app, mobile app (cross-platform), API, CLI tool, library, etc.)
- What's the current state? (greenfield, existing codebase, rewrite)

**Stack & Architecture:**
- Frontend framework? (Next.js, React, Astro, React Native/Expo, etc.)
- Native iOS? (Swift/SwiftUI — if yes, skip web-specific questions like styling approach and component library)
- Styling approach? (Tailwind, CSS Modules, styled-components, etc.)
- Component library? (shadcn/ui, Material UI, custom, none)
- CMS? (Sanity, Contentful, Strapi, none — Sanity is the default for content-driven sites. If using Sanity, note whether visual editing / Sanity Studio is needed.)
- Backend/API? (same framework, separate service, BaaS like Supabase/Firebase)
- Database? (Postgres, MongoDB, SQLite, Supabase, etc. — skip if using a CMS as the primary data layer)
- Auth approach? (Supabase Auth, NextAuth, Clerk, Astro middleware, custom)
- State management? (TanStack Query, Zustand, Redux, React context — skip for Astro content sites and native iOS)
- Key integrations? (AI APIs, payment, push notifications, etc.)

**Design:** *(skip if DESIGN.md exists — its tokens, typography, and brand voice answer all of these)*
- Is there an existing design system or brand guidelines?
- Color scheme preference? (dark theme, light theme, both)
- Primary accent color?
- Mobile-first or desktop-first?

**Project Scope:** *(skip pages/features questions if UX.md and feature specs exist)*
- What are the main features/pages? (3-5 bullet points) — skip if UX.md present
- Any phased rollout? (MVP → v2 → etc.)
- Solo developer or team?
- What's the intent? (hobby/learning, side project, freelance offering, startup/serious venture)

**Phase 0 — Pre-Build Setup (skip for hobby/learning projects):**

For anything beyond a hobby, prompt the user on these before jumping into the main build:

- **Landing page / waitlist:** "Do you want to set up a landing page to start collecting emails while you build? This can be as simple as a single-page site with a headline, value prop, and email capture." If yes, include a `Phase 0: Pre-Launch Foundation` in TASKS.md with landing page tasks scoped to the stack (e.g., a `/coming-soon` route in Next.js, or a standalone single-page deploy). Keep it minimal — the goal is to start collecting interest, not to build a marketing site.

- **Analytics instrumentation:** "Let's wire up analytics from day one so you can actually measure what matters at launch." Default to **PostHog** (free up to 1M events/month, includes web analytics, session replay, funnels, feature flags, and A/B testing in one tool). PostHog has an MCP server for querying analytics data from Claude Code.

  Stack-aware setup:
  - **Next.js / React web apps:** PostHog JS snippet or `posthog-js` package. Track: page views (autocaptured), signup events, core action completion, feature usage.
  - **React Native / Expo mobile apps:** PostHog React Native SDK. Track: app opens, onboarding completion, core action completion, retention events (D1/D7/D30).
  - **SaaS / subscription products:** PostHog for product analytics + Stripe webhook events for MRR, churn, upgrades.
  - **API / developer tools:** PostHog server-side SDK. Track: API key creation, first successful API call, usage volume, error rates.
  - **Any project with auth:** Track the full activation funnel — signup → email verified → first core action → return visit.
  - **Landing pages (separate repo):** PostHog JS snippet. If the landing page uses Kit (ConvertKit) for email capture, track form submissions as PostHog events to see the full funnel.

  Include in TASKS.md Phase 0:
  - [ ] Install PostHog (`posthog-js` or appropriate SDK for the stack)
  - [ ] Set up core event tracking (list 3-5 key events specific to the project)
  - [ ] Verify events fire correctly in development
  - [ ] Set up a PostHog dashboard for launch-day metrics
  - [ ] If landing page / waitlist: set up Kit (ConvertKit) form or API integration for email capture

### Step 3: Generate Docs

After gathering answers, generate all five files. **Generation order matters when upstream artifacts exist** — earlier files inform later ones:

1. ARCHITECTURE.md (informed by FEATURES + UX)
2. CONVENTIONS.md (stack-specific, informed by FEATURES dependencies)
3. DESIGN_SYSTEM.md (implementation of DESIGN.md, components from UX.md)
4. TASKS.md (scaffold only — phases from UX, capability assignments from FEATURES)
5. CLAUDE.md (cross-references everything)

Follow these principles:

**ARCHITECTURE.md:**
- Start with an ASCII system overview diagram
- Document the actual folder structure (adapt to framework)
- Include data flow diagrams for key user journeys
- If there's a database, include the full schema with SQL
- Document all external integrations with env vars
- Include state management strategy with query key conventions
- Separate MVP vs post-MVP architecture
- **If `UX.md` exists:** Add a "User-Facing Architecture" section near the top: *"For UX/IA, page inventory, and conversion models, see `docs/UX.md`. This file documents system architecture; `UX.md` documents UX architecture."*
- **If feature specs exist** (either `planning/FEATURES.md` or `planning/features/`): Add a "Feature Specs" section: *"For per-feature acceptance criteria, states, data lifecycles, and dependencies, see `planning/FEATURES.md` (or `planning/features/<slug>.md` per feature in split mode). Architecture decisions here should match the data models declared there."* Cross-reference any features that drive architectural decisions using the actual path that exists (e.g., "Local-first storage is required by the Recipe Capture feature — see `planning/features/recipe-capture.md` → Data" in split mode, or "see FEATURES.md → Recipe Capture → Data" in single mode).

**CONVENTIONS.md:**
- Include REAL code patterns, not descriptions of patterns
- Every section should have copy-pasteable code blocks
- Cover the specific library versions being used
- Document breaking changes from previous major versions
- Include patterns for: components, data fetching, mutations, forms, error handling
- **For Astro projects:** Include patterns for `.astro` components, island hydration (`client:load`, `client:visible`, `client:idle`), content collections, Sanity GROQ queries (if using Sanity), and `<Image>` component usage. Note which components need client-side JS and which are static.
- **For native iOS projects:** Include patterns for SwiftUI views, navigation, data flow (ObservableObject, @State, @Binding), networking, and Swift conventions (naming, optionals, error handling). Skip web-specific patterns entirely.
- Add a library reference table with versions and docs links
- **Include a "Core Development Philosophy" section** covering:
  - **KISS:** Write simple, readable code. Avoid clever tricks. Prefer clarity over brevity. Show good vs bad examples (e.g., `.filter()` over `.reduce()` for simple filtering)
  - **YAGNI:** Build features only when needed. No abstraction layers "just in case." No generic utilities for single use cases. Implement simplest solution, refactor when patterns emerge (3+ uses)
  - **Functional Programming First:** Pure functions, immutable data, higher-order functions over imperative loops, compose small reusable utilities, functional components with hooks exclusively
- **Include a "Critical Guidelines / Before Writing Any Code" section:**
  1. Check TASKS.md for current milestone scope — ask user before implementing features not in the current milestone. Stay focused on MVP scope and ask user for guidance when blocked.
  2. Reference CONVENTIONS.md for patterns — copy existing patterns, don't reinvent solutions.
  3. Never implement temporary workarounds — no `// TODO: fix this later`, no `any` types "for now", no hardcoded values without constants. Ask user for guidance when blocked. Propose proper solutions, not hacks.
  4. Ask before major decisions — new dependencies, architectural changes, database schema changes, deviating from planned features.
- **Include an "Anti-Patterns to Avoid" section** with project-specific don'ts (adapt to the stack — e.g., for TypeScript projects: no `any`, no TODO hacks, no hardcoded values; for all projects: no premature abstraction, no scope creep beyond current milestone)

**DESIGN_SYSTEM.md:**

This file is the **stack-specific implementation** of the brand spec. It is *not* the brand spec itself.

- **If `DESIGN.md` exists:** Open the file with a "Source of Truth" section:

  ```markdown
  ## Source of Truth

  Brand tokens, typography, motion, and voice live in `docs/DESIGN.md`.
  This file translates that spec into our stack: [Next.js + Tailwind / SwiftUI / etc.].

  **Do not edit `DESIGN.md` directly** — it's a verbatim brand spec from `plan-design`.
  If the brand evolves, re-run `plan-design` and overwrite. Implementation changes
  (CSS variable names, component code, accessibility patterns) belong here.
  ```

  Then derive stack tokens (CSS variables, SwiftUI tokens, Compose theme values, etc.) directly from `DESIGN.md`'s color, type, spacing, and motion sections. Use the *same names* where possible so the mapping is obvious.

- **When `DESIGN.md` exists, don't restate its brand specs.** DESIGN_SYSTEM.md is the *delta* between brand and stack — what it adds is implementation code, token names, accessibility patterns, and component composition for the chosen stack (Tailwind/CSS, SwiftUI, Jetpack Compose, React Native, Flutter, etc.). Visual specs (hex codes, padding values, radii, type sizes, motion timings) live in `DESIGN.md` only — DESIGN_SYSTEM.md references them, never restates them. The token map should be a `brand role → stack token` table without re-listing hex/values; readers cross-reference `DESIGN.md` when they need the values. Component entries follow the pattern: *"Brand rules: see `DESIGN.md` §X. Implementation: [stack-specific code/classes/modifiers/props]."* If a section in DESIGN_SYSTEM.md could be deleted without losing implementation info, delete it — point to `DESIGN.md` instead. This applies to any frontend stack (web, iOS, Android, cross-platform). **If no `DESIGN.md` exists, this rule does not apply** — DESIGN_SYSTEM.md becomes the standalone source of truth and should include the visual specs directly (see fallback below).

- **If `UX.md` exists:** Pull the canonical component list from `UX.md`'s "Components needed" sections across all pages. Every component named there gets an entry here with stack-specific implementation. If `UX.md` names a component you can't define, flag it for the user rather than inventing.

- **For web projects:** Define CSS variables / theme tokens, include the full color system with semantic naming, document typography scale with actual classes, show component patterns with real code (buttons, cards, inputs, modals), include custom components specific to the project, cover layout patterns, add animation definitions, include accessibility section, end with a design checklist.

- **For native iOS projects:** Define the color asset catalog structure, typography using system and custom fonts, SwiftUI component patterns (buttons, cards, inputs, sheets), layout patterns (NavigationStack, TabView), and accessibility modifiers. Skip CSS-specific guidance entirely. Reference Apple's Human Interface Guidelines (https://developer.apple.com/design/human-interface-guidelines) for platform conventions on color, typography, layout, and component behavior.

- **If neither `DESIGN.md` nor `UX.md` exists:** Generate a standalone DESIGN_SYSTEM.md from the discovery answers (current behavior). Add a soft note at the top suggesting `plan-design` and one of `plan-ux-web` / `plan-ux-app` / `plan-ux-ios` (per surface) for stronger downstream behavior.

**TASKS.md:**

**This file is a phase scaffold, not a complete task list.** Tasks within each phase are placeholders. Actual task generation happens on-demand via `execute-features-web` (or `-ios`) when the user is ready to start building. This keeps the file concise and ensures tasks are generated against fresh context with current docs (feature specs, UX.md, ARCHITECTURE.md, CONVENTIONS.md) rather than baked in upfront.

**Structure:**

- Start with this critical reminder at the top of the file:
  ```
  > **⚠️ CRITICAL:** Update this file after completing work! Mark tasks with `[x]` when done.
  > **📦 Tasks expand on-demand:** Phase tasks are placeholders until you start work on the phase.
  > **🎨 Each phase splits design + feature:** Each expanded phase emits two subsections — `### Design tasks` and `### Feature tasks`. Design tasks (visual components with hardcoded data) run first via `execute-design-{web,ios}` + `close-design-phase-{web,ios}`. Feature tasks (wire components to real data) run second via `execute-features-{web,ios}` + `close-feature-phase-{web,ios}`. Both share one branch and one PR per phase. Design close completes before any feature task starts.
  > **🔒 Component boundary:** Once a design task commits a component, the feature pipeline may **extend** it (new props, variants, or states the data layer needs) but never **redesign** it (visual treatment, spacing, typography, color). Feature commits that extend a component must include a `Component extended:` note explaining what changed and why. Purely visual changes → BLOCKED with redirect to the design pipeline.
  ```

- **For non-hobby projects:** Start with a `Phase 0: Pre-Launch Foundation` section containing landing page tasks (if opted in) and analytics instrumentation tasks. **Phase 0 tasks are concrete from the start** — these are well-known and don't need expansion.

- **Phase structure when UX.md and feature specs exist** (hybrid):
  - **Phase 0** — Pre-launch foundation (concrete tasks; not split into design/feature since these are usually pure infrastructure)
  - **Phase 1** — Foundational features (auth model, data architecture, sync strategy — pulled from feature specs by dependency order, things other features depend on)
  - **Phase 2+** — Page-by-page from UX.md, in conversion-priority order (core loop pages first, then secondary surfaces)
  - Each phase header lists which **UX pages** and **FEATURES capabilities** it covers, but tasks remain placeholders. Each phase produces both design tasks (visual components) and feature tasks (data wiring); design tasks run first.

- **Phase structure when only one upstream artifact exists:** Use whichever exists to drive phases. If only `UX.md` exists, phases are page-by-page. If only FEATURES exists, phases are by capability dependency. If neither exists, use the user's stated phasing from discovery.

- Each phase scaffold looks like this:

  ```markdown
  ## Phase 1: Core Loop (Landing + Onboarding)

  **Status:** Not started
  **UX pages covered:** Landing, Onboarding
  **FEATURES capabilities covered:** Recipe Capture, Recipe Library
  **Goal:** Prove the activation event works end-to-end.

  ### Design tasks
  - [ ] Tasks not yet generated. Run `execute-design-web 1` (or `-ios`) to expand visual components from UX.md, DESIGN_SYSTEM.md, and mockups.

  ### Feature tasks
  - [ ] Tasks not yet generated. Run `execute-features-web 1` (or `-ios`) to expand data-wiring tasks from feature specs and ARCHITECTURE.md. Runs after design tasks complete.
  ```

- Include a Quick Reference section (commands, important files, env vars)
- Include a Key Decisions Log table
- Include Progress Tracking section per phase (% complete based on expanded tasks once they exist)

**CLAUDE.md:**
- Place at project root (not in /docs)
- Reference all docs that exist:
  - `Read docs/ARCHITECTURE.md for system design`
  - `Read docs/CONVENTIONS.md for code patterns`
  - `Read docs/UX.md for UX/IA before building any page or screen` *(if exists)*
  - `Read planning/FEATURES.md` (single mode) or `planning/features/README.md` first then specific feature files (split mode) for per-feature specs and acceptance criteria *(if exists)*
  - `Read docs/DESIGN.md for the canonical brand spec — DO NOT EDIT this file` *(if exists)*
  - `Read docs/DESIGN_SYSTEM.md for stack-specific implementation of the brand spec`
  - `Read docs/TASKS.md for current work — phase tasks expand on-demand. Each phase splits into design tasks (run first via execute-design-{web,ios}) and feature tasks (run second via execute-features-{web,ios}).`
- Include project-specific rules (naming conventions, do/don't patterns)
- **If `DESIGN.md` exists:** Add an explicit do-not-edit rule near the top of the rules section: *"`docs/DESIGN.md` is a verbatim brand spec from `plan-design`. Never edit it directly. To update the brand, re-run `plan-design` and overwrite. Implementation changes go in `DESIGN_SYSTEM.md`."*
- Note that tasks expand on-demand and split by domain: *"`docs/TASKS.md` contains phase scaffolds with placeholder tasks. Each phase produces design tasks (run first via `execute-design-{web,ios}`) and feature tasks (run second via `execute-features-{web,ios}`). The pipelines share one branch and one PR per phase."*
- Keep it concise — it's loaded every session

### Step 4: File Placement

```
project-root/
├── CLAUDE.md              # Root level
├── planning/              # Upstream artifacts (if they exist)
│   ├── MVP_SPEC.md        # from plan-mvp
│   ├── FEATURES.md        # from plan-features (single mode)
│   └── features/          # from plan-features (split mode — alternative to FEATURES.md)
│       ├── README.md      # index
│       ├── feature-a.md
│       └── feature-b.md
└── docs/
    ├── ARCHITECTURE.md
    ├── CONVENTIONS.md
    ├── UX.md        # from plan-ux-web / plan-ux-app / plan-ux-ios (if exists)
    ├── DESIGN.md          # from plan-design (if exists, do-not-edit)
    ├── DESIGN_SYSTEM.md
    └── TASKS.md
```

Ask the user if they prefer `/docs/` or a different directory. Some projects use `.claude/` or keep everything at root. `planning/` should generally stay separate from `docs/` since planning artifacts have a different access pattern (read during expansion, not during execution).

### Step 5: Review & Iterate

After generating, tell the user:
- Which files were created and where
- Which upstream artifacts were detected and consumed (e.g., "Read UX.md — Phase 2-4 are derived from your 6 pages")
- Which upstream artifacts are missing and what skill produces them
- Suggest they review each file and flag anything to adjust
- Offer to flesh out any section that needs more detail
- **Remind them:** "TASKS.md has phase scaffolds only. Each phase produces design tasks first, then feature tasks. When ready to build, run `execute-design-{web,ios} N` to expand and execute visual components, then `execute-features-{web,ios} N` to wire them to real data. Both pipelines share one branch and one PR per phase."

## Important Guidelines

- **Be specific, not generic.** These docs should feel hand-crafted for this exact project. No boilerplate filler.
- **Use real code.** Every pattern in CONVENTIONS.md should be actual working code for their stack.
- **Cross-reference.** Each doc should link to the others at the bottom.
- **Adapt the template.** Not every project needs a DESIGN_SYSTEM.md (e.g., a CLI tool). Skip files that don't apply and explain why.
- **Match the user's depth.** If they give detailed answers, generate detailed docs. If they're brief, keep docs focused.
- **Version awareness.** Use the correct API patterns for the library versions they specify. Don't mix v4 and v5 patterns.
- **Cap output files at ~500 lines.** Long markdown bloats downstream context and becomes unscannable. Sweet spot: 100–400 lines per file. If a file would exceed 500 lines, split into topical sub-files (e.g., `DESIGN_SYSTEM.md` → `DESIGN_SYSTEM.md` overview + `COMPONENTS.md` + `TOKENS.md`; or `ARCHITECTURE.md` → `ARCHITECTURE.md` + `DATA_MODEL.md` + `INTEGRATIONS.md`) and cross-link from a short parent index. Apply during generation — don't write 900 lines first and split after.