0cdbb1b4a4
Per plugin-structure spec, plugin-internal references in component
files (commands, agents, skills) must use \${CLAUDE_PLUGIN_ROOT} so
they resolve correctly regardless of where the plugin is installed
(local repo, marketplace cache, npm-installed, etc.).
Updated:
- symphony/skills/symphony-init/SKILL.md: WORKFLOW.md template ref
- composer/skills/ui-system/SKILL.md: all six template refs in the
Write phase
- composer/skills/composer/SKILL.md: added a Templates section that
enumerates each phase's template path with \${CLAUDE_PLUGIN_ROOT},
plus the ADR template ref in phase 8
Composer's CLAUDE.md gains a clarifying note that templates/design-
system/SKILL.md and templates/interaction-design/SKILL.md are template
skeletons, not actual plugin skills — they're copied into a consuming
project's .claude/skills/ at install-time of the design system. Per
the auto-discovery rule (scans skills/ only), they are not loaded as
plugin skills.
Removed empty composer/agents/ directory (composer has no agents;
workers are owned by symphony).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
# composer
|
|
|
|
Discovery-phase companion. Composer interviews you from "I want an app that…"
|
|
to a tree of stories in your issue tracker, producing reviewable artifacts in
|
|
`docs/planning/` along the way. Pairs with **Symphony** — Composer's output
|
|
(stories in the tracker) is Symphony's input (work to dispatch).
|
|
|
|
Like Symphony, Composer is **tracker-agnostic**. The project's `CLAUDE.md`
|
|
documents how to write to the tracker; Composer's load phase reads those
|
|
instructions.
|
|
|
|
## Phase order
|
|
|
|
| # | Phase | Artifact(s) | Skill |
|
|
|---|---|---|---|
|
|
| 1 | Concept | `docs/planning/concept.md` | `composer` |
|
|
| 2 | Users & workflows | `docs/planning/users.md` | `composer` |
|
|
| 3 | Requirements | `docs/planning/{requirements,nfr,ia}.md` | `composer` |
|
|
| 4 | Design system | `.claude/skills/<slug>-design-system/` (project skill) | `ui-system` (placeholder) |
|
|
| 5 | Interaction design | `.claude/skills/<slug>-interaction-design/` (project skill) | `ui-system` (placeholder) |
|
|
| 6 | Flows | `docs/planning/flows.md` | `composer` |
|
|
| 7 | Mocks | `docs/planning/mocks/*.tsx` | `composer-mocks` |
|
|
| 8 | Architecture | `docs/planning/architecture.md` + `adr/NNNN-*.md` | `composer` |
|
|
| 9 | Stories | `docs/planning/stories.md` | `composer` |
|
|
| 10 | Roadmap | `docs/planning/roadmap.md` | `composer` |
|
|
| 11 | Load | (project's tracker) | `composer` |
|
|
|
|
**Phases 4 and 5 do not write to `docs/planning/`.** The design-system and
|
|
interaction-design artifacts are *project-local skills* in `.claude/skills/`
|
|
because they need to auto-load via description matching whenever UI work
|
|
is happening. A reference doc gets read once and drifts out of context as
|
|
the conversation grows; a skill loads on demand every time the trigger
|
|
matches. `docs/planning/` gets pointer files so the planning index stays
|
|
discoverable.
|
|
|
|
**Phase 7 imports tokens directly from the skill**, not from a copy:
|
|
|
|
```tsx
|
|
import { color, spacing, fontSize } from
|
|
"../../.claude/skills/<slug>-design-system/tokens";
|
|
```
|
|
|
|
Single source of truth across mocks, real components, themes, and any
|
|
future visual code in the project.
|
|
|
|
**Architecture is last on purpose.** It's a *response* to a complete spec,
|
|
not a setting picked at the start. Stack choices made before the design
|
|
system, interaction model, and mocks lock you into shapes that don't fit
|
|
the problem.
|
|
|
|
## Note on templates
|
|
|
|
`templates/design-system/SKILL.md` and `templates/interaction-design/SKILL.md`
|
|
are **templates**, not actual skills of this plugin. The plugin's auto-loaded
|
|
skills live in `skills/` (`composer`, `composer-mocks`, `ui-system`); the
|
|
templates under `templates/` are skeletons that the `ui-system` skill copies
|
|
into a *consuming project's* `.claude/skills/<slug>-design-system/` and
|
|
`.claude/skills/<slug>-interaction-design/` directories.
|
|
|
|
Per Claude Code's plugin auto-discovery, only `SKILL.md` files under `skills/`
|
|
are loaded as plugin skills — `templates/` is a regular subdirectory and is
|
|
ignored by discovery.
|
|
|
|
## Layout
|
|
|
|
- `commands/composer.md` — main entry, state-aware. Continues from the first
|
|
missing artifact in `docs/planning/`.
|
|
- `commands/composer-review.md` — summon a council on the current artifact.
|
|
- `commands/composer-mock.md` — generate or revise a mock for a named flow.
|
|
- `commands/composer-load.md` — push stories to the project's tracker.
|
|
- `commands/composer-status.md` — show what's done, missing, and stale.
|
|
- `skills/composer/SKILL.md` — orchestrator: phase detection + interview.
|
|
- `skills/composer-mocks/SKILL.md` — JSX/TSX mock generation + text feasibility audit.
|
|
- `skills/ui-system/SKILL.md` — design + interaction system interview *(placeholder; to be fleshed out)*.
|
|
- `templates/*` — starter skeletons for each artifact.
|
|
|
|
## Council touchpoints
|
|
|
|
Composer auto-suggests councils at phase boundaries; users can also invoke
|
|
`/composer-review` at any time.
|
|
|
|
| After phase | Default council |
|
|
|---|---|
|
|
| Requirements | Lena (PM), Vera (skeptic), Marge (end-user) |
|
|
| Mocks | Marge (end-user), Maya (a11y) |
|
|
| Architecture | Tomás (architect), Gerald (sr engineer), Priya (DBA), Aisha (DevOps) |
|
|
| Pre-load | Marcus (eng manager), Vera (skeptic) — sanity-check scope honesty |
|
|
|
|
Composer scans content and adds:
|
|
- **Femi (legal-triage)** when it spots regulated jurisdictions, third-party data flows, or licensing questions
|
|
- **Camila (privacy-advocate)** when it spots PII, multi-user data, or DNA/health data
|
|
- **Ingrid (finance-controller)** when it spots money flows, billing, refunds, or subscriptions
|
|
|
|
## Three things Composer doesn't do
|
|
|
|
1. **Invent users.** The interview probes for hidden actors (agents, integrations, future-self) by asking about workflows, not by drafting speculative personas.
|
|
2. **Lie in mocks.** Every visible string in a mock is annotated as static / computed / authored, with the source data and transform named. Strings that imply unspecified features get flagged before the mock is committed.
|
|
3. **Push to the tracker without confirmation.** Always shows a dry run before creating issues.
|
|
|
|
## Handoff to Symphony
|
|
|
|
After load, the project has stories in its tracker. Run `/symphony-init` to
|
|
set up the orchestrator that will execute them.
|