Decision 0045 · Accepted
Templates pin flow-skills; one owner
per workflow
flow-next and flow-mono ship a .agents/skills-lock.json of technical skills that pnpm setup installs.
- Status
- Accepted
- Built from:
- da88c48
Status: Accepted (2026-10-29). Amends the start rule "do not install flow-skills into the new repository" (skills/start/SKILL.md). Spec: 033.
Context
flow-next and flow-mono ship a .agents/skills-lock.json of technical skills that pnpm setup installs. Flow's own workflow skills are not in it, so a fresh clone has no /start until the person installs flow-skills separately. The lock also carries workflow skills from other catalogs that overlap Flow's: domain-modeling and prototype (same names as Flow skills, from mattpocock/skills), diagnosing-bugs (overlaps debug), research (overlaps explore), and two TDD skills (tdd, test-driven-development) that overlap each other.
Decision
- Each template's root
skills-lock.jsonpins the Flow catalog fromgaboesquivel/flow-skillsby content hash (refreshed withpnpm skills:update), and commits the installed skills (.agents/skills/, linked from.claude/skills/), so a fresh clone already gives the agent/startand the rest of Flow. - Flow owns workflow (discovery, specs, delivery, debugging, domain language, prototyping). The lock drops third-party skills whose job a Flow skill already owns, and keeps one TDD skill. Technical skills (framework, library, platform, tooling) stay.
startkeeps whatever the template's lock installs and does not install flow-skills a second time.
Rationale
The fastest first run is the one with nothing to install by hand. Two skills with the same name or the same job make the agent pick arbitrarily, which breaks Flow's guarantees (direction-change gate, spec status, delivery mode).
Alternatives
- Install flow-skills globally and keep templates Flow-free. Rejected: an extra manual step before
/start, and versions drift per machine. - Keep the overlapping skills and document precedence. Rejected: hosts load by description match, not by documented precedence.
Consequences
Template releases follow flow-skills releases (pnpm skills:update). Adopters who prefer the dropped skills can add them back to their own lock.