Decision 0019 · Accepted
Voice-first
invocation
PRODUCT.md says ordinary language should be the complete user interface to Flow and that skills are optional conveniences. The catalog does the opposite.
- Status
- Accepted
- Built from:
- da88c48
Status: Accepted (2026-10-28). Partially supersedes 0004, 0006, 0008, 0013, and 0017. Amended by 0024 (named, gated hand-offs). Amended by 0028 (ship lands with no confirmation). Amended by 0048 (one trigger set per delivery skill; Flow claims "push it" and "deploy it").
Context
PRODUCT.md says ordinary language should be the complete user interface to Flow and that skills are optional conveniences. The catalog does the opposite. Every skill except flow sets disable-model-invocation: true, and scripts/validate.mjs fails the build otherwise. A plain request reaches a Flow skill only when the user types its slash command or names it. 0017 records the effect in Claude Code: "review this" reaches the built-in, not Flow.
The primary way the maintainer works is speech: talking to the agent or dictating with voice-to-text. Leading words were meant to be what a user says to reach a skill ("interview me" uses interview). 0008 instead defined them as agent-facing anchors, so the catalog lists phrases nobody says, such as "Label unresolved assumptions".
Manual-only invocation came from 0001, which rejected auto-invocation for context bloat and unintended workflows. That risk belonged to the retired router, which chained skills. A skill matched from a description does not chain, and every skill already states what it does not authorize.
Hosts give portable skills no priority mechanism; the model chooses from descriptions. Vercel's deploy-to-vercel writes its description around spoken phrases ("deploy my app", "push this live"), deploys previews by default, and asks before pushing. Its plugin adds priority and path or command patterns, but only through its own hooks, which a portable skill cannot rely on.
Decision
- Talking is the primary interface. Ordinary language, including dictated speech, reaches every Flow skill. Slash commands remain optional shortcuts.
- Skills are model-invocable by default. Only
startstays explicit-only, because it creates a repository. - A leading word is the user's phrase. Redefine it as the short phrase a user says to reach a skill. Each
descriptionstates what the skill does, then "Use when the user says …" with two or three dictation-safe variants: short, common words that survive speech recognition. The body keeps using that phrase as its behavior anchor. - Flow owns intent and durable artifacts; the host owns execution. Do not claim generic host verbs:
- "Plan this" belongs to the host's plan mode. Flow's phrases are "spec it" (
to-spec) and "break it down" (to-tasks). - "Review the code" belongs to the host's code review. Flow
reviewanswers alignment phrases such as "check it against the spec" or "are we aligned". - "Build it" and "ship it" may reach
implementandship; no Claude Code built-in claims them.
- "Plan this" belongs to the host's plan mode. Flow's phrases are "spec it" (
shipconfirms and hands off deployment. Model invocation is allowed. Before pushing,shipstates what it will commit and push and waits for a yes. Deployment defers to the platform's own skill or configuration when present (for exampledeploy-to-vercel) and prefers preview over production unless asked.- Retire
simplify,security, andperformance. They are generic, overlap host built-ins, and as model-invocable skills would compete with them on every request. Product-thinking skills are where Flow differs from host built-ins. - Users control priority, not Flow. Agent compatibility documents an optional phrase-to-skill table users may paste into their own user-level instructions (for example
~/.claude/CLAUDE.md). Flow never writes it. It resolves names only and does not chain skills.
Rationale
Voice is the intended interface, and in current hosts only model-invocable skills with phrase-shaped descriptions can be reached by voice. Ceding generic verbs avoids a contest Flow cannot win portably and keeps Flow on intent work no built-in covers. Confirmation before pushing addresses misrecognized dictation better than manual-only invocation, which blocks voice entirely.
Alternatives
- Keep explicit-only invocation. Rejected: contradicts the product promise and blocks voice.
- Claim generic verbs with broad descriptions. Rejected: unreliable against built-ins and surprising to users.
- Collide on built-in names to shadow them. Rejected: works on one host, fragments portability (0017).
- Keep
shipexplicit-only. Rejected: "ship it" is a natural spoken phrase; confirmation before pushing covers the risk.
Consequences
validate.mjs,agents/openai.yamladapters, and contract tests enforce the new split:startexplicit, every other skill implicit.- Every
descriptionis rewritten with trigger phrases; skill catalog leading words become those phrases; GLOSSARY.md updates Leading word. - Remove
skills/simplify/,skills/security/, andskills/performance/; catalog drops to twenty-one skills. - Update PRODUCT.md, README, agent compatibility, and every statement that skills require explicit invocation. State the skill count only where the validator list lives.
- Context cost rises: about twenty descriptions load in every session. Keep each to two sentences.
- Triggering is probabilistic. Acceptance needs a live smoke record: fifteen to twenty dictated plain phrases in Claude Code, with the skill each reached. Structural checks cannot establish it.