!${CLAUDE_PLUGIN_ROOT}/scripts/skill-preflight.sh strategy 2>&1 || true

@.claude/shirabe-extensions/strategy.md @.claude/shirabe-extensions/strategy.local.md

Strategy Documents

STRATEGY documents capture the medium-term bet a project commits to when operationalizing a piece of an upstream VISION. They sit between VISION (long-term aspiration, years) and ROADMAP (sequenced features) at medium-term defensibility altitude. Each STRATEGY names a falsifiable hypothesis, decomposes it into coherent building blocks, maps coordination dependencies, and lists per-direction invalidation conditions so the team can recognize when the bet has been wrong.

A STRATEGY links one level in each direction: its upstream is a VISION, and its Downstream Artifacts are ROADMAPs. Keeping the links strict is what makes the chain walkable -- a reader moving VISION -> STRATEGY -> ROADMAP hits every altitude in order rather than landing two levels down with the reasoning in between skipped. The ROADMAP is the boundary between the strategic chain and the tactical one, and /brief is what crosses it, so a STRATEGY never links a PRD, DESIGN, or PLAN directly.

A PRD can still ground the conversation — /strategy docs/prds/PRD-<name>.md reads one to derive the bet, and an author holding a feature PRD who wants the medium-term bet behind it has a real strategy to write. But reading a document and recording it as the strategy's parent are different acts. upstream: takes a VISION or nothing; a strategy grounded in a PRD with no VISION above it omits the field and names the PRD in Strategic Context prose.

Writing style: Read skills/writing-style/SKILL.md for guidance.

Artifact Lifecycle

Lifecycle: Durable. Stays in docs/strategies/ after completion.

STRATEGY is durable because the medium-term bet — the falsifiable claim a project pursues — stays in the audit trail. Future readers reviewing which strategic direction was taken need the STRATEGY to remain in place.

Strategy Format

See references/strategy-format.md for the full format specification: frontmatter schema, required and optional sections, visibility-gated sections, section matrix, content boundaries, lifecycle states, validation rules, and quality guidance. Load it during Phases 2, 3, and 4.

File Location

STRATEGY documents live at docs/strategies/STRATEGY-<topic>.md (kebab-case). No directory movement until Sunset, which moves files to docs/strategies/sunset/. Stable paths keep cross-references durable and git blame readable.

Repo Visibility

Before writing content, detect visibility from CLAUDE.md (## Repo Visibility: Public|Private). If not found, infer from repo path (private/ -> Private, public/ -> Public; default to Private). Load the appropriate content governance skill:

• Private repos: Read skills/private-content/SKILL.md
• Public repos: Read skills/public-content/SKILL.md

Public STRATEGYs must not include a Competitive Considerations section, and must not reference private artifacts. The R8 custom check in shirabe validate enforces the section rule mechanically; the upstream-reference rules are enforced by content governance.

Creating a Strategy Document

When invoked as /strategy, this skill drives a six-phase workflow that scopes the bet conversationally, drafts the foundational sections, decomposes into building blocks, runs a three-reviewer jury, and finalizes through explicit human approval.

The skill produces a STRATEGY document. Use /strategy when the work needs medium-term defensibility framing (a falsifiable bet, named invalidation conditions, building-block decomposition). Use /vision if the conversation is long-term identity. Use /roadmap when the bet is already settled and what's needed is feature sequencing.

Input Modes

From $ARGUMENTS:

1. Empty — ask the user what bet they want to articulate.
2. Path to existing STRATEGY with lifecycle verb (accept, activate, sunset) — execute the lifecycle transition via shirabe transition <strategy-path> <status>. Sunset requires a reason: shirabe transition <strategy-path> Sunset --reason "<text>".
3. Path to a VISION document (matches docs/visions/VISION-*.md) — treat as the upstream VISION for the new STRATEGY; derive the bet candidate from upstream content during Phase 1, and record the path as the draft's upstream:.
4. Path to a PRD document (matches docs/prds/PRD-*.md) — read as grounding for the bet during Phase 1. The PRD is not recorded as the STRATEGY's upstream, per the read-vs-record rule above; if no VISION sits above the strategy, the draft omits the field.
5. Anything else — use as the starting topic for Phase 1 scoping.

Any of the modes above may carry --upstream <path>, naming the upstream VISION separately from the topic. /strategy <topic-slug> --upstream docs/visions/VISION-<name>.md produces STRATEGY-<topic-slug>.md recording that VISION as its upstream — the slug comes from the positional argument and the upstream from the flag, so the two need not share a name. Input Mode 3 is the special case where they do: a bare VISION path supplies both at once, which only works while the strategy's topic and the vision's filename coincide.

The flag is parsed before the positional argument is classified, and its value is never treated as a topic. A bare --upstream with no value is rejected at Phase 0 naming the missing argument. The value must name a VISION: the same basename rule Input Mode 3 enforces applies to the flag, because both feed the same recorded upstream: field. A grounding PRD (Input Mode 4) is never passed this way — it is read, not recorded, and the flag is the recording route.

Context Resolution

Execution mode: check $ARGUMENTS for --auto or --interactive flags, then CLAUDE.md ## Execution Mode: header (default: interactive). In --auto mode, make decisions based on evidence rather than blocking on user input. Record decisions in the ## Decisions section of the work/context.md key.

Topic slug constraint. The <topic> slug used in the session name and the STRATEGY filename must match [a-z0-9-]+ (kebab-case lowercase alphanumeric, hyphens only). Phase 0 enforces this constraint by rejecting any topic that contains other characters, including ., /, _, or whitespace. Without the constraint, ../-shaped topics could redirect verdict writes outside the scratch directory.

Upstream: check $ARGUMENTS for --upstream <path>. If present, the path is validated at Phase 0 and stored as the work/context.md key's ## Recorded Upstream; Phase 2 writes it into the STRATEGY's frontmatter. It points to the VISION this strategy operationalizes — the strategy's immediate neighbour one level up the strategic chain. /charter passes it on every chain where a VISION is available; an author invoking /strategy standalone passes it when a VISION exists that the topic slug does not name. When no VISION exists, omit the flag rather than reaching past the neighbour; the upstream field is then omitted from frontmatter.

Path canonicalization. Any user-supplied VISION or PRD path (Input Modes 3 and 4) and any --upstream value must be canonicalized at Phase 0 and rejected if the canonical path resolves outside the repo working tree. Symlinks resolving to arbitrary filesystem content would otherwise leak into a public commit.

Detect visibility (Private/Public) from CLAUDE.md or repo path. Infer from private/ or public/ in path if not explicit. Default to Private if unknown — restricting is easier to undo than oversharing.

Log: Drafting strategy with [Private|Public] visibility...

Workflow Phases

Phase 0: SETUP --> Phase 1: DISCOVER --> Phase 2: DRAFT --> Phase 3: STRUCTURAL FILL --> Phase 4: VALIDATE --> Phase 5: FINALIZE
(branch +         (scope + upstream     (Context, Thesis,  (Building Blocks,             (3-reviewer        (approval +
 visibility)       grounding)            Falsifiability)    Coordination, Non-Goals,     jury)               transition)
                                                            Downstream Artifacts)
                                                                                          |
                                                                                          v (FAIL loops back to Phase 2 or 3)

Phase 4 jury runs three reviewers in parallel:

• Bet quality — falsifiability of the Defensibility Thesis; named invalidation conditions per Falsifiability direction.
• Altitude — operates at medium-term defensibility (carries upstream VISION content without re-justifying long-term thesis; defers sequenced feature decomposition to ROADMAP). Applies the Building Blocks granularity rubric defined in references/strategy-format.md.
• Structural format — all required sections present and ordered; frontmatter valid; visibility-gated section honored; Downstream Artifacts entries point at durable paths.

All three must PASS before Phase 5 begins.

Session and Keys

/strategy keeps its working state as keys in its own koto session, strategy-<topic>, following ${CLAUDE_PLUGIN_ROOT}/references/skill-session-convention.md. It writes no file to the staging folder, chained or direct. As soon as the topic is known (from the argument, or from Phase 0's slug step on a cold start), and before the resume rows below are read, it opens the session and records whether it runs under a parent:

"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" open strategy <topic>
"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" adopt strategy <topic>

open attaches to a live strategy-<topic> (an interrupted run, whose keys the resume rows read), replaces a finished one (a fresh run), or creates it. Any non-zero exit from either command stops the run with the script's message: 127 or 69 means koto is missing or too old, and the skill never falls back to files. adopt exiting 3 is the two-parents case below.

Keys are read and written with koto against strategy-<topic>: koto context exists strategy-<topic> <key> tests one (exit 0 present, 1 absent), koto context get strategy-<topic> <key> prints it, koto context add strategy-<topic> <key> stores the content given on stdin (the whole content: to change one line, get the key, edit it, and add it back), koto context list strategy-<topic> --prefix <prefix> lists keys, and koto context remove strategy-<topic> <key> removes one. Reviewer agents never write keys: Phase 4 pins each verdict to a file in a skill-session.sh scratch directory and ingests it.

Closing. A direct run closes its session when it finishes: "${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" close strategy-<topic> done after Phase 5's last step, or close strategy-<topic> abandoned after a Reject's discard. Under a parent /strategy never closes its own session: the parent closes it at its own exit (skill-session.sh close-children), and the keys stay readable until then.

Resume Logic

dispatch read strategy <topic> prints parent=<session>
                                                         -> run under that parent; see ${CLAUDE_PLUGIN_ROOT}/references/fixes/sub-agent-dispatch.md
STRATEGY exists with status "Accepted" or "Active"       -> Offer to revise or start fresh
STRATEGY exists with status "Draft"                      -> Offer to continue from Phase 2 or 3
keys research/phase4_* exist in strategy-<topic>         -> Resume at Phase 4 (aggregate)
STRATEGY has Building Blocks section                     -> Resume at Phase 4
STRATEGY has Defensibility Thesis section                -> Resume at Phase 3
key work/discover.md exists in strategy-<topic>          -> Resume at Phase 2
key work/context.md exists in strategy-<topic>           -> Resume at Phase 1
On a branch related to the topic                         -> Resume at Phase 1
None of the above                                        -> Start at Phase 0

Running under a parent. The first row runs "${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" dispatch read strategy <topic> with the topic this run works on. A printed parent=<session> line means /strategy runs under that parent (scope-<topic> or charter-<topic>), with the parent's upfront decision in the rationale= and suppress_status_aware_prompt= lines; what changes under a parent is in ${CLAUDE_PLUGIN_ROOT}/references/fixes/sub-agent-dispatch.md. Four cases are no match. Three print nothing and exit 0, and the run is a direct one with the rows below unchanged: no parent session, a finished parent session, and a parent whose chain/dispatch key names another child. The fourth, two parent sessions that both name /strategy, exits 3: don't pick one and don't run directly; stop and report both sessions, which the script names on stderr, so the author can clear the stale key. Any other non-zero exit stops the run with the script's message (open has already checked koto). adopt has recorded the same match as chain/parent in strategy-<topic>, or removed a chain/parent an earlier chained run left.

Critical Requirements

• Topic-slug constraint: Phase 0 rejects topics not matching [a-z0-9-]+. Non-compliant topics never reach later phases.
• Path canonicalization: Phase 0 canonicalizes and bounds-checks any user-supplied upstream path, whether it arrived positionally or as the --upstream flag's value.
• Slug independence: the topic slug is never derived from the --upstream value. A flag-supplied upstream names the strategy's parent, not the strategy.
• Conversational scoping: Phase 1 is a dialogue, not a form to fill out. Org-scope STRATEGYs without an upstream VISION need this conversation to ground Strategic Context.
• Jury parallelism: Phase 4 spawns the three reviewer agents with run_in_background: true. Each reviewer's prompt is self-contained (no shared memory); the orchestrator aggregates verdicts.
• Human approval gate: Phase 5 requires explicit human approval via AskUserQuestion before Draft -> Accepted. Jury PASS alone does not transition status.
• Visibility hygiene: Public STRATEGYs must not surface Competitive Considerations content (R8 rejects mechanically). Phase 2 warns authors when quoting from private-upstream content into a public-visibility STRATEGY (requires manual sanitization).

Execution

Execute phases sequentially by reading the corresponding phase file:

0. Setup: branch + visibility/scope detection + slug + path validation
   • Instructions: references/phases/phase-0-setup.md
1. Discover: scoping conversation + upstream grounding
   • Instructions: references/phases/phase-1-discover.md
2. Draft: Strategic Context, Defensibility Thesis, Falsifiability
   • Instructions: references/phases/phase-2-draft.md
3. Structural Fill: Building Blocks, Coordination, Non-Goals, Downstream
   • Instructions: references/phases/phase-3-structural-fill.md
4. Validate: three-reviewer jury (parallel agents)
   • Instructions: references/phases/phase-4-validate.md
5. Finalize: approval + status transition + PR
   • Instructions: references/phases/phase-5-finalize.md

Output

Final artifact: docs/strategies/STRATEGY-<topic>.md, created in Draft status. After explicit user approval at Phase 5, transition to Accepted via shirabe transition <strategy-path> Accepted.

After acceptance, suggest next steps:

Team Shape

/strategy's team shape is declared in team.yaml as the machine-readable contract surface. The child layer spawns three reviewer peers at Phase 4 (bet-quality-reviewer, altitude-reviewer, structural-format-reviewer) to validate the drafted STRATEGY.

See Dispatch Contract for v1 parent-side consumption rules.

Reference Files