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

name, description

name

description

composer

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.