claude-plugins/composer/skills/composer/SKILL.md

---
name: composer
description: Discovery-phase orchestrator. State-aware skill that walks a user from "I want an app that…" to a tree of stories in their issue tracker, writing reviewable artifacts in docs/planning/ along the way. Use when the user runs /composer, /composer-status, /composer-review, or /composer-load — or asks to "start product discovery", "lay out a project", or "plan an app". For mock generation, the composer-mocks skill is invoked. For design/interaction system, ui-system is invoked.
---

# Composer — orchestrator

You walk a user through product discovery, one phase at a time, producing
artifacts in `docs/planning/`. **Detect first, ask second.** Read what exists
before asking anything; resume at the first missing or stale phase.

## Modes

This skill has four modes, dispatched by which command invoked it:

- **continue** (default, from `/composer`) — resume the interview at the next missing phase.
- **status** (from `/composer-status`) — read-only progress report.
- **review** (from `/composer-review`) — convene a council on an artifact.
- **load** (from `/composer-load`) — push stories to the project's tracker.

## Phase order and artifacts

| # | Phase | Artifact path | Skill |
|---|---|---|---|
| 1 | concept            | `docs/planning/concept.md`                          | self |
| 2 | users              | `docs/planning/users.md`                            | self |
| 3 | requirements       | `docs/planning/requirements.md`                     | self |
| 3 | requirements (NFR) | `docs/planning/nfr.md`                              | self |
| 3 | requirements (IA)  | `docs/planning/ia.md`                               | self |
| 4 | design-system      | `.claude/skills/<slug>-design-system/SKILL.md`†     | `ui-system` |
| 5 | interaction-design | `.claude/skills/<slug>-interaction-design/SKILL.md`†| `ui-system` |
| 6 | flows              | `docs/planning/flows.md`                            | self |
| 7 | mocks              | `docs/planning/mocks/`                              | `composer-mocks` |
| 8 | architecture       | `docs/planning/architecture.md` + `adr/`            | self |
| 9 | stories            | `docs/planning/stories.md`                          | self |
| 10| roadmap            | `docs/planning/roadmap.md`                          | self |
| 11| load               | (project tracker)                                   | self |

†Phases 4 and 5 produce **project-local skills**, not docs in
`docs/planning/`. Skills auto-load via description matching whenever
UI work happens; a doc would not. Each phase also drops a pointer file
in `docs/planning/` (`design-system.md` and `interaction-design.md`) so
the planning index can find the skill location. Detect completion by
the SKILL.md file in the project skill directory, not by the pointer.

A phase with multiple files (requirements) is "complete" only when all its
files exist. The slug is resolved from `package.json` `name`, then git
remote name, then directory name (kebab-case ASCII).

## continue mode

### Detect

Scan `docs/planning/`. For each phase, decide:
- **missing** — artifact absent, this is where we resume.
- **present** — artifact exists.
- **stale** — artifact exists but an upstream phase was modified after it.

The first **missing** phase is where to resume. If everything is present, ask
the user whether to advance past load (suggest `/symphony-init`) or revisit a
phase.

### Phase 1 — Concept

Goal: one-paragraph north star.

```
What are you building? One sentence is fine.
```

Probe minimally — surface, audience, platform — then draft `concept.md` from
the template. Show the draft, accept edits, write the file. Do not invent
goals the user didn't state.

### Phase 2 — Users & workflows

Goal: surface every actor that touches the system, including non-human ones.

The interview pattern:

1. Ask who the user thinks the user is.
2. Ask what they *do* — list verbs.
3. For each verb, ask who or what is on the other side.
4. Probe for: other humans, AI agents, integrations, scheduled jobs, the data
   format itself, future-self, backups.

Example move: if the user says "just me" but later mentions "I want Claude to
read these," surface that explicitly:

> Then we have at least two users: you (primary), and the agent (read access,
> possibly write?). That changes the data model — agent-readable usually means
> structured-enough to query. Want to add the agent as a named user-class?

Write `users.md` with: primary persona, anti-personas, named user-classes
(humans + non-humans), and a verb-keyed workflow list. **Never draft a
speculative second human persona.** Hidden actors are surfaced through
workflows, not invented.

### Phase 3 — Requirements (3 files)

Three artifacts, one phase.

**`requirements.md`** — hard / soft / non-goals.

Ask each in turn:
- Hard: "If the app doesn't do this, it isn't useful — what falls in that bucket?"
- Soft: "Would-be-nice items, deferable."
- Non-goals: "What will we explicitly say *no* to when it comes up?"

Push back on ambiguous "and" lists. Every conjunction is usually two
requirements pretending to be one.

**`nfr.md`** — non-functional requirements with thresholds.

Ask about: performance budgets, scale targets, availability target, security
posture, accessibility level (WCAG AA is the floor), browser/device support,
offline behavior, data retention, observability needs. Each one needs a
**number or named threshold**, not a vibe. "Fast" is not an NFR; "p95
interaction < 100ms on mid-tier mobile" is.

**`ia.md`** — information architecture.

Identify: top-level concepts (entities), how they relate, how they're
named, and how a user navigates between them. This is the taxonomy file —
it's what mocks and architecture both look up later.

After writing all three, **auto-suggest a council review**:

```
Three artifacts written. Summon Lena (PM), Vera (skeptic), and Marge (end-user)
to review before we move on? [Y/n]
```

If content suggests it, also propose:
- **Femi (legal-triage)** — regulated data, jurisdictions, third parties, IP
- **Camila (privacy)** — PII, multi-user data, biometrics, minors
- **Ingrid (finance)** — money, billing, refunds, subscriptions

### Phases 4–5 — Design & Interaction systems

Delegate to the `ui-system` skill. That skill writes **project-local
skills** to `.claude/skills/<slug>-design-system/` and
`.claude/skills/<slug>-interaction-design/`, plus pointer stubs in
`docs/planning/`. The skills auto-load on UI work; the pointers exist
only for human discoverability of the planning index.

`ui-system` is currently a *placeholder* — it captures the minimum needed
for mocks to proceed, with prominent `<TBD: ...>` markers. Composer
continues to phase 6 once both project skills exist; the user should
revisit `ui-system` to fully specify before mocks are committed.

**After write, tell the user to verify**:

```
Two project skills now installed:
  .claude/skills/<slug>-design-system/
  .claude/skills/<slug>-interaction-design/

These auto-load whenever UI work is happening in this repo. If you're
in this session, they should be available now (run /agents to confirm).
If you're starting a new session, they'll load on the first UI-related
prompt.
```

### Phase 6 — Flows

Goal: name every primary user journey, step by step.

Read `users.md`'s workflow list. Each top-level workflow becomes a named flow
in `flows.md`. For each flow, capture: actor, trigger, preconditions, the
step-by-step interaction, success state, failure modes.

Don't over-design here — the goal is *naming and sequencing the journeys*,
not specifying every screen. Mocks come next.

### Phase 7 — Mocks

Delegate to the `composer-mocks` skill. It generates one mock per flow and
runs the text feasibility pass.

### Phase 8 — Architecture

Now the spec is complete. Read `concept.md`, `users.md`, `requirements.md`,
`nfr.md`, `ia.md`, `design-system.md`, `interaction-design.md`, `flows.md`,
and skim the mocks. Surface the constraints to the user:

```
Big constraints I'm pulling out:
  • [from requirements] hard offline-first
  • [from NFR] p95 interaction < 100ms on mid-tier mobile
  • [from users] AI agent reads notes — structured data needed
  • [from interaction-design] mobile-first, single locale (English) for v1
  ...

That points at: <stack hypothesis>. Convening a council to pressure-test:
  Tomás (architect), Gerald (sr engineer), Priya (DBA), Aisha (DevOps).
```

Run the council. Their synthesis informs ADRs. Draft each ADR (one per major
decision) using `adr/0000-template.md`; user signs off; write to
`adr/NNNN-<slug>.md`. Compose a summary `architecture.md` referencing the ADRs.

### Phase 9 — Stories

Goal: a flat list ready to load into the tracker.

For each flow, decompose into stories. Each story has: title, description,
acceptance criteria, dependencies (other stories), size estimate (S/M/L/XL),
and an epic/cluster tag. Don't over-decompose at this phase — granularity
shifts as the team starts working.

Reference flows.md for the source-of-truth on what each story enables.

### Phase 10 — Roadmap

Cluster stories into epics and sequence them into milestones. The first
milestone is the **smallest version that's still useful** — push back on
including soft requirements, NFR niceties, or scope creep here.

### Phase 11 — Load

See *load mode* below.

## status mode

Read-only. Print:

```
docs/planning/  ✓
  concept.md            ✓
  users.md              ✓
  requirements.md       ✓
  nfr.md                ✓ (modified after flows.md — flows may be stale)
  ia.md                 ✓
  design-system.md      ⚠ placeholder (return to flesh out)
  interaction-design.md ⚠ placeholder
  flows.md              ✓
  mocks/                ✓ (3 of 5 flows mocked)
  architecture.md       —
  adr/                  —
  stories.md            —
  roadmap.md            —

Next: phase 8 — architecture.
Council reviews recorded: requirements (2026-04-29).
```

## review mode

When invoked from `/composer-review`:

1. Pick the artifact: argument-named, else current phase's primary artifact.
2. Pick the council: argument-named, else phase default (see CLAUDE.md table)
   plus auto-additions when content suggests them.
3. Read the artifact + necessary upstream context.
4. Invoke the `council-of-experts:council` skill with a framed question.
5. Save the synthesis to `docs/planning/reviews/<artifact>-<YYYY-MM-DD>.md`.
6. Output the full council response to the user (the council skill already
   formats this — pass through unchanged).

## load mode

When invoked from `/composer-load`:

1. Read `stories.md` and `roadmap.md`.
2. Read the project's `CLAUDE.md` for the tracker integration section. If
   missing, exit with `tracker_integration_missing` and tell the user to
   either run `/symphony-init` (which writes the section) or add it manually.
3. Build the planned write set:
   - 1 milestone per first-cluster (the MVP slice)
   - 1 epic/parent issue per cluster (if the tracker supports parents)
   - 1 issue per story, linked to its epic, labeled per `stories.md`
4. Print the dry-run plan grouped by cluster. Show the exact tracker commands.
5. Wait for user confirmation.
6. Execute writes. On failure, stop and report — never auto-continue past an
   error that might leave partial state.
7. Update `stories.md` with the created issue IDs (e.g.
   `- [ ] PROJ-42 — Log a feeding for an active starter`). The file becomes
   the local↔tracker map.
8. Suggest `/symphony-init` if the project doesn't have Symphony set up.

## Hard rules

- **One question at a time** during interviews. The user has the floor.
- **Never invent users, requirements, or features the user didn't state.**
  Probe to extract; do not auto-complete.
- **Never push to the tracker without a dry run.**
- **Stale-aware.** When an upstream artifact changes, flag downstream
  artifacts as `stale` in status; ask the user before silently regenerating.
- **Re-entrant.** Every phase can be re-entered. Re-running on an existing
  artifact prompts the user before overwriting.