shape

name	shape
position	none
description	Select what to build in one domain and compose it into deliverable verticals — confirm or prune its capabilities against the firmed profile + KB, select which of the functionalities /understand created to build now, create the personas and user journeys, and bundle the functionalities into vertical slices, each behind a user-facing surface scaffolded slice by slice. The product-owner step of the ProductOS strategy pipeline, after /vision and /understand. Selects against the profile but never writes it; composes slices but never cuts epics or plans order. Opens no delivery issue.
user-invocable	true

shape

Take one domain that /understand has detailed — capabilities detail: detailed with their functionalities created, profile set — and select what to build and compose it into deliverable verticals. /shape is the product owner: it confirms the capabilities that stay (prunes the rest), selects which existing functionalities to build now, creates the personas served and the user journeys they travel, and bundles those functionalities into the domain's vertical slices, each behind a user-facing surface. It reads the profile to judge fit but never writes it, it never creates a functionality or authors ICE (/understand did), and it never cuts epics (/grill) or plans order (/roadmap). One domain per run.

Always scaffold the UI. Every slice names at least one surface a persona opens and checks, and that surface is a thin scaffold — this slice's piece of screen, not the whole UI. The product surface accretes slice by slice.

Pipeline position: none. /shape is a MIDDLE play of the strategy pipeline (vision → understand → shape → roadmap): it expects to run on the branch /vision already started, injects no start-change head and no close sequence, stops when its work is done, and leaves the branch as-is for the next play to pick up. The close belongs to /roadmap. It writes the persistent product model directly, on the already-started branch. (#437)

Compiled From

This play was compiled from the shape ICE (reference/ice.md) by play-editor (#466 Batch C, Level 3 rollout per ADR 025; #467 Batch B — the checkpoint upgraded to a conditional learned gate, see standards/rules/gate-config.md). Intent defines constraints (C1–C14) and failure conditions (F1–F15); the expectation defines success scenarios (S1–S8), a Done means (D1–D3, baked to stop-condition.yaml), and one recovery entry per failure condition. To modify this play, update reference/ice.md and recompile with play-editor. Do NOT edit this file manually — it is a compiled artifact.

Role

You are the orchestrator. You own the workflow and the step order. You delegate the domain work — the grounded selection-and-composition bundle — to the product-os-keeper agent via a JSON contract over files on disk, and you run the mechanical work (readiness gate, bundle validation, the allowlisted persist, and the post-apply spine diff) through bundled scripts. You never write the model YAML yourself, you never create a functionality or write the product profile, and you never persist before the single checkpoint (C12) resolves — a typed approval, a recorded config skip, or a recorded policy auto-pass.

Forbidden: hand-writing slice/persona/journey/decision YAML or the spine; creating a functionality or authoring ICE (that is /understand's); writing the product profile by any route; reparenting, renaming, or deleting nodes; editing a capability beyond its status flip; cutting epics or planning slice order; persisting by any route other than scripts/apply_shape.py; persisting before Step 3 resolves; closing COMPLETED without the stop-condition verdict reading held (C14/F14).

Agent boundaries:

Agent	Domain	Skill it invokes	Phases
product-os-keeper	Confirm/prune capabilities and select existing functionalities against the firmed profile + KB; create personas, user journeys, decisions; compose the domain's vertical slices behind scaffolded surfaces	search-kb, author-shape-bundle	Draft

product-os-keeper is the single domain agent this play uses (1 of the ≤5 budget). No utility agents are needed — git/issue machinery is absent (position none).

Pre-flight

Check	Constraint	Action on Failure
Resolve config + product_base (.garura/core/config.yaml)	—	Hard halt
Profile firmed (set) AND target capabilities detail: detailed with functionalities	C1	Hard halt (REC1)

Resolve config mechanically with the bundled resolver; /shape has no branch or issue (position none):

python3 scripts/preflight.py --play shape --config .garura/core/config.yaml
python3 scripts/check_ready.py --spine <product_base>/product-os/_spine.yaml --domain <domain-id>

preflight.py returns config facts (product_base, stm_base, evidence_record). check_ready.py is the readiness gate (C1): it halts unless the product profile is set (firmed by /understand) and every target capability in the domain is detail: detailed with at least one functionality. The target domain is the play argument (e.g. /shape token-dash). If the profile is still directional or a capability is not yet detailed, hard halt and route to /understand (REC1).

The run's working root (<working> below) is {stm_base}_shaping/shape/<domain>/ — the routing, the draft, the applied record (apply-manifest.json), and the captured post-apply checks (shape-checks.json) all live under it; the stop condition evaluates against it. Status markers live at {stm_base}_shaping/shape/status/.

Right after the resolver, record the session identity stamp's start marker (#463 — soft-fail, never a halt):

python3 scripts/session_stamp.py --phase start \
    --marker "{stm_base}_shaping/shape/status/session-stamp-shape.json" \
    --cwd "$(pwd)" --branch "$(git branch --show-current)"

Resume check: if {stm_base}_shaping/shape/status/<domain>.json exists, resume — skip completed steps, reset any in-progress step to pending, continue from the first incomplete.

Task DAG

Create ALL tasks immediately after resolving config — before any domain work. The play owns this DAG; the agent must not edit its top-level tasks.

[T1] Draft selection bundle  blockedBy: []
[T2] Validate the draft      blockedBy: [T1]
[T3] Checkpoint (approval)   blockedBy: [T2]
[T4] Persist                 blockedBy: [T3]
[T5] Verify persisted        blockedBy: [T4]
[T6] Scenario Validation     blockedBy: [T5]
[T7] Close                   blockedBy: [T6]

Mark each task in-progress before its step and completed right after its eval passes. No runtime reordering. On resume, skip completed and reset in-progress to pending.

Workflow

Phase: Draft

Step 1 — Draft selection bundle · Owner: product-os-keeper · Depends on: pre-flight The persisted model does not record which KB shelf a domain came from, and the product domain slug is not the KB shelf name. So the agent first recovers the shelf with search-kb, then invokes author-shape-bundle to draft the domain's selection-and- composition bundle to STM — confirm/prune per capability, select which existing functionalities to build, the personas, the user journeys through surfaces, the decisions, AND the domain's vertical slices (each naming at least one user-facing surface a named persona opens and checks, bundling functionalities by spine id, plus the _deferred bucket), with stable ids:

{
  "task":    "recover this domain's KB shelf via search-kb, then SELECT among the functionalities /understand already created against the firmed profile + that shelf, and COMPOSE the domain's vertical slices. Never create a functionality or author ICE. Every slice MUST name >=1 user-facing surface (a thin UI scaffold a named persona opens and checks) — a backend-only/horizontal/whole-UI slice is invalid. Journeys are user journeys ON named surfaces. Name surfaces; never design them. Every selected functionality in a slice or _deferred; slices reference functionalities by spine id; no order/effort/depends_on",
  "inputs":  { "domain":       "<id + slug + path under product-os>",
               "product_base": "<product_base>" },
  "outputs": { "routing":      "<working>/routing.yaml",
               "draft_dir":    "<working>/draft/",
               "manifest":     "<working>/draft/shape-manifest.yaml",
               "slices":       "<working>/draft/product-os/<domain>/slices/" }
}

The agent passes the shelf search-kb resolved to author-shape-bundle as its kb_shelf. It returns the contract with the output paths on disk — never inline content. The skill reads the live spine read-only and writes only the draft. SE-1 (F1/C1): the readiness gate passed at pre-flight — the profile is set and the target capabilities are detail: detailed with functionalities; otherwise the run halted (REC1).

Phase: Validate

Step 2 — Validate the draft · Owner: play · Depends on: Step 1 Run the bundle validator over the draft before the checkpoint:

python3 scripts/validate_shape.py --draft <working>/draft \
        --manifest <working>/draft/shape-manifest.yaml --spine <product_base>/product-os/_spine.yaml

SE-2 (F2/C2): the draft selects and composes only — it created no functionality and authored no ICE, and wrote no profile (the draft holds only slices, personas, journeys, decisions, and the spine delta of status flips + slice index). SE-3 (F3/C3): grounding holds — every kept capability and selected functionality in the manifest carries a KB shelf or a recorded proposal; none is invented. SE-4 (F5/C5): schema + integrity — personas, journeys, decisions, and slices carry their required fields; every slice functionality_ref resolves to a real functionality in the live spine; every journey persona and surface reference resolves. SE-5 (F6/C6): placement holds — every selected functionality appears in a slice or the _deferred bucket; validate_shape.py reports no unplaced functionality. SE-6 (F7/C7): every slice is a user-facing scaffold — it names at least one surface (name + persona + user_action), and is no backend-only, one-per-capability horizontal, or whole-UI slice. SE-7 (F8/C8): surfaces are named, not designed — no slice surface carries wireframe, component, layout, or visual-design content. SE-8 (F9/C9): journeys are user journeys through surfaces — each traverses at least one named surface, none is a backend pipeline, and every surface a slice names is reached by a journey. SE-9 (F10/C10): slices reference functionalities by spine id (not copied) and carry no order, effort, or resolved depends_on. SE-10 (F11/C11): a decision is recorded for every prune and every material selection. On any GAP, apply the matching recovery (REC2–REC11) and re-run before the checkpoint.

Phase: Checkpoint (conditional gate, C12)

Step 3 — Human review (class: standard, conditional) · Owner: play · Depends on: Step 2 This checkpoint is a conditional gate (#467) per standards/rules/gate-config.md — /shape is one of the eleven conditional document plays. Resolve it first match wins: pinned (n/a here) → gates.plays.shape → the learned policy → gates.classes.standard → gates.default (absent ⇒ on). For the policy lookup, classify the draft-vs-live change shape first:

python3 scripts/classify_change.py --play shape --draft <working>/draft \
        --live <product_base> --out <working>/shape.json

Look the shape key up in the config-resolved policy (gates.conditional.policy): auto-pass iff the shape is in the policy's auto: block AND not in never_auto: AND Step 2 stands with no blocking finding (a validate_shape.py gap — /shape's lint-equivalent guard). On auto-pass, do NOT wait: record gate auto-passed by learned policy (shape: <shape-key>, policy v<version>) as a Checkpoint Decisions row, include the draft's diff summary in the run record, append the crossing's live-eval ledger line, and proceed to Step 4:

python3 scripts/gate_eval.py append --ledger <gates.conditional.ledger> --play shape \
        --issue <strategy issue> --shape <shape-key> --predicted auto --human auto_pass \
        --policy-version <policy version> --ts <run ts>

Anything else resolves the gate on (an explicit gates.plays.shape: off instead records gate skipped by config (<resolution path>) as a Checkpoint Decisions row and proceeds). When on, present the domain's selection bundle inline — the kept capabilities, the pruned capabilities (each with its reason), the selected functionalities, the personas, the journeys, AND the vertical slices (each led by the user-facing surface it exposes, with its outcome and the functionalities it bundles) plus the _deferred bucket. Say plainly that the surface's design — and the slices' order, effort, and dependencies — come later (/realize designs the surface; /roadmap plans the slices; /grill cuts the epics), not here. Render the approval prompt (standards/templates/approval-prompt.md) and wait for the typed response. Approve → continue to persist; cancel → halt with nothing written to the model. Then append the crossing's live-eval ledger line with the human's real action:

python3 scripts/gate_eval.py append --ledger <gates.conditional.ledger> --play shape \
        --issue <strategy issue> --shape <shape-key> --predicted gate \
        --human <approved_clean|approved_edited|rejected> --ts <run ts>

<strategy issue> is the strategy-pipeline issue the run's branch carries (opened by /vision's start-change). <gates.conditional.ledger> / <gates.conditional.policy> resolve from config gates.conditional (defaults .garura/core/gate-evals.jsonl / .garura/core/gate-policy.yaml); <policy version> is the policy file's version: field. <run ts> is the run's own UTC timestamp, derived the same way the close derives ts (date -u), passed by the orchestrator. SE-11 (F12/C12): the selection is persisted only after this gate resolves — a typed approval, a recorded config skip, or a recorded policy auto-pass; Step 4 is the sole writer and depends on this step; no product-model file is written before Step 4. SE-15 (F15): every crossing of this gate appended exactly one live-eval ledger line (shape, predicted gate|auto, the human's real action or auto_pass), and an auto-pass fired only for a shape the policy lists in auto: (and not in never_auto:) with no blocking finding standing.

Phase: Apply

Step 4 — Persist · Owner: play · Depends on: Step 3 First snapshot the live spine so Step 5 can diff it:

cp <product_base>/product-os/_spine.yaml <working>/spine-before.yaml

Then persist on the fixed allowlist. apply_shape.py merges the spine delta — it flips only the status field on the named capabilities (read-modify-write), adds the slice index entries skip-if-exists, and attaches persona/journey/decision refs onto the capabilities — and copies the slice/persona/journey/decision records skip-if-exists. It is never handed the profile and never touches a functionality:

python3 scripts/apply_shape.py --draft <working>/draft --product-base <product_base> \
        --manifest <working>/draft/shape-manifest.yaml --out-manifest <working>/apply-manifest.json

Phase: Verify

Step 5 — Verify persisted · Owner: play · Depends on: Step 4 Diff the before/after spine and check the written decisions — capture the checker's JSON output; its ok field is the stop condition's D3 input:

python3 scripts/check_shape.py --apply-manifest <working>/apply-manifest.json \
        --shape-manifest <working>/draft/shape-manifest.yaml \
        --spine-before <working>/spine-before.yaml \
        --spine-after <product_base>/product-os/_spine.yaml --domain <domain-id> \
        > <working>/shape-checks.json

SE-12 (F4/C4): each flipped capability differs from its before-snapshot in the status field only — a prune is deprecated, never a delete; no reparent, rename, create/delete, or other out-of-scope capability edit. SE-13 (F13/C13): the spine diff is confined to /shape's allowlist — capability status flips, new slices, and new persona/journey/decision refs; no functionality, no domain, and no profile field changed, and a re-run added no duplicate record. SE-14 (F14/C14): the close is stop-condition gated — check_stop_condition.py over the baked stop-condition.yaml (D1 the applied record apply-manifest.json exists; D2 it stamps applied: true; D3 the captured shape-checks.json reads ok: true) must read held before any COMPLETED close; a run whose persist or verification did not land closes HALTED, never COMPLETED (REC14).

Phase: Scenario Validation

Step 6 — Scenario evals · Owner: play · Depends on: Step 5

• SCE-1 (S1 — product owner, select + compose): kept capabilities are active, the selected (already-existing) functionalities are placed into slices, personas and journeys are created and schema-valid, no functionality was created or changed, and the stop-condition verdict reads held.
• SCE-2 (S2 — architect, grounding): every kept capability and selected functionality traces to a KB shelf or a recorded proposal in the manifest.
• SCE-3 (S3 — product owner, prune is soft): a pruned capability is deprecated with a recorded decision and still present — not deleted.
• SCE-4 (S4 — reviewer, box and functionalities untouched): the profile is byte-identical before and after, and the spine diff shows no change to any functionality or domain.
• SCE-5 (S5 — delivery lead, slices reference by id): each slice has a name, outcome, acceptance intent, and functionalities referenced by a resolvable spine id, with no copied content and no order/effort/depends_on.
• SCE-6 (S6 — planner, full coverage): the union of all slices' functionality_refs and the _deferred bucket equals the selected functionalities — none unplaced.
• SCE-7 (S7 — product owner, every slice is a user-facing scaffold): every slice names at least one surface (name + persona + user_action) with no design content; zero surface-less slices, no one-per-capability horizontal slice; every named surface is reached by a journey.
• SCE-8 (S8 — reviewer, the checkpoint + re-run): the checkpoint showed kept/pruned capabilities, functionalities, personas, journeys, and the slices + deferred bucket inline before any write — or, on the auto-pass path (a policy-listed shape), the gate resolved with no wait and the recorded auto-pass, the appended ledger line, and the diff summary stand in the approval's place; a re-run added no duplicate persona, journey, or slice.

Phase: Evidence & Close

Step 7 — Close · Owner: play · Depends on: Step 6 Run the Standard Play Close. /shape is a product-scoped play (no issue) — use the product-scoped evidence base and slug. Evidence recording is play-only and config-gated per the D1 evidence rule (standards/rules/evidence-recording.md).

# --- Standard Play Close (canonical; see standards/rules/play-close.md) ---
# Path tokens resolved at pre-flight (resolve here if not already):
#   ltm_project_target  = yq '.ltm.project-target' .garura/core/config.yaml
#   evidence_base, slug:
#     project-scoped play : evidence_base="${stm_base}${issue}/evidence/shape/"   ; slug="#${issue}"
#     product-scoped play : evidence_base="${product_base}_evidence/shape/"         ; slug="${product_slug}"
evidence_template=$(cat "${ltm_project_target}standards/templates/evidence-file.md")
delivery_template=$(cat "${ltm_project_target}standards/templates/delivery-report.md")
ts=$(date -u +%Y%m%d-%H%M%S)
evidence_dest="${evidence_base}${ts}.md"
mkdir -p "$(dirname "$evidence_dest")"

# Session identity stamp (#463) — close phase; start phase ran at pre-flight
session_stamp=$(python3 scripts/session_stamp.py --phase close \
    --marker "${stm_base}_shaping/shape/status/session-stamp-shape.json")
# Stop-condition gate (#464) — Step C0: this play carries a baked manifest, so the
# gate is LIVE. Evaluate the Done means as the close's authoritative input.
python3 scripts/check_stop_condition.py \
    --manifest "<play-dir>/stop-condition.yaml" \
    --base "${stm_base}_shaping/shape/<domain>/" \
    --out "${stm_base}_shaping/shape/status/stop-condition-shape.yaml"
sc_exit=$?   # 0 held · 1 unmet · 2 error
# Conditional-gate policy refresh (#467) — soft: a distill failure never blocks the close
python3 scripts/distill_gate_policy.py --ledger "<gates.conditional.ledger>" --policy "<gates.conditional.policy>" --streak <gates.conditional.streak> --project "<project name from config>" || true

/shape is product-scoped: evidence_base="${product_base}_evidence/shape/" and slug="${product_slug}" (the domain slug, e.g. token-dash).

Step C0 — bind the verdict. sc_exit == 0 (held) permits status: COMPLETED. Anything else closes HALTED with exit_reason: stop_condition_unmet and the evidence's Stop Condition section names every unmet clause — fix the state per REC14 (re-run the allowlisted persist, or re-capture the post-apply verification) and re-evaluate; the close stays HALTED until the verdict reads held. An unevaluable verdict is never a pass.

Step C1 — Write evidence file. Gated by the resolved evidence.record flag (global

• per-play evidence.plays.shape; first match wins, absent ⇒ record). When false, skip the write and record evidence skipped (record=false) in the report's pointer line. Otherwise fill the evidence-file.md slots (play shape, run_id shape-${ts}, product_slug, started_at/completed_at, status per C0, exit_reason; artifacts produced: the capability status flips, the selected functionalities, personas, journeys, decisions, the vertical slices (each with its user-facing surface) + deferred bucket, the shape + apply manifests, the captured shape-checks.json, the stop-condition verdict; step and scenario eval results SE-1…SE-15 / SCE-1…SCE-8; checkpoint decision from Step 3 including kept/pruned capabilities and the slices (or the gate skipped by config / gate auto-passed by learned policy row when the gate resolved without a wait) plus the gate ledger line(s) appended this run; the session identity stamp fields from $session_stamp (#463): session_id, ledger_file, ledger_start_offset, ledger_end_offset (null when unresolved — never blocks the close); and stop_condition per C0 with the Stop Condition section filled) and write to $evidence_dest. Do NOT hand-author the body.

Step C2 — Render delivery report. Also render the Next line: resolve this play in standards/rules/pipeline-next.md and emit **Next:** /<command> — <why>. Or run /next to see all recommended actions. (only /next pointer, or omit, when the mapped command is null), per play-close.md. Fill the delivery-report.md slots and output the report: ## shape Delivered — ${product_slug}, the Run Summary table, the Pipeline Steps table from the task DAG, the Artifacts Produced table (status flips, selected functionalities, personas, journeys, decisions, the vertical slices + deferred bucket), Next Steps (run /roadmap to plan the slices — order, dependencies, effort — across domains; then /grill cuts a chosen slice into epics), and a pointer to $evidence_dest. Always emitted; never gated.

# --- end Standard Play Close ---

Scenario Validation

Scenario	Persona	Eval
S1 — select + compose	product owner	SCE-1
S2 — grounding	architect	SCE-2
S3 — prune is soft	product owner	SCE-3
S4 — box + functionalities untouched	reviewer	SCE-4
S5 — slices reference by id	delivery lead	SCE-5
S6 — full coverage	planner	SCE-6
S7 — every slice is a user-facing scaffold	product owner	SCE-7
S8 — the checkpoint + re-run	reviewer	SCE-8

Recovery

For	Trigger	Direction	Handoff
F1	the profile is directional, or a target capability is not detailed, at start	halt and route to /understand to firm the profile and detail the capabilities first	human
F2	/shape created a functionality, authored ICE, or wrote the profile	strip the over-reach — remove the created functionality/ICE, revert the profile write; detailing and the box are /understand's	autonomous
F3	a selected functionality or kept capability has no KB shelf match and no proposal	ground it against the KB, or record a propose-kb-node proposal; never keep an invented selection	autonomous
F4	a capability edited beyond status, a reparent/rename, a create/delete, or a hard-deleted prune	revert the out-of-scope mutation; /shape flips capability status only and prunes soft (deprecated)	autonomous
F5	a persona/journey/decision/slice fails its schema, or a slice/journey reference does not resolve	re-emit the failing record to conform, and fix the reference to a real spine functionality/persona/surface	autonomous
F6	a selected functionality is in neither a slice nor the _deferred bucket	place it — add it to a slice, or record it in _deferred with a reason — before persisting	autonomous
F7	a surface-less/horizontal slice, or a "whole UI at once" slice	re-cut the slice vertically toward one surface a persona opens and checks, as a thin scaffold; fold or defer functionalities that serve no surface	autonomous
F8	/shape designed a surface (wireframe/component/layout/visual) instead of naming it	strip the design to the surface's name, persona, and user action; design is /realize's UX lens	autonomous
F9	a journey is not a user journey on a surface, or a named surface no journey reaches	rewrite the journey as the persona's steps on a named surface; ensure every slice surface is reached by a journey	autonomous
F10	a slice copied a functionality's content, or carries order/effort/depends_on	replace copied content with a spine functionality_ref, and strip the plan fields — /roadmap plans	autonomous
F11	a prune or material selection with no decision record	write the decision (ADR) for each before persisting	autonomous
F12	the selection persisted with no checkpoint approval	revert the premature write and re-present the checkpoint; persist only after the human approves	human
F13	a functionality/domain/profile changed, or a re-run duplicated a record	restore the changed artifact and re-run writing only /shape's allowlist, de-duplicating by stable id, after a human confirms the restore	human
F14	the run is about to close COMPLETED with the Done means unmet	close HALTED (stop_condition_unmet) with the unmet clauses named; fix the state — re-run the allowlisted persist, or re-capture the post-apply verification — and re-evaluate; the close stays HALTED until the verdict reads held	autonomous
F15	a conditional-gate crossing left no live-eval ledger line, or an auto-pass fired for a shape the policy does not list as auto (or that carried a blocking finding)	re-append the missing ledger line for the recorded crossing; when the auto-pass was unearned, re-run the gate as a live wait — render the approval prompt and wait for the typed response — before proceeding	autonomous

Pause and Resume

Steps run top to bottom. On entry, resolve config, resolve the target domain from the play argument or the in-progress draft, check the status marker, skip completed steps, reset any in-progress step to pending, and continue. A fresh start with no marker runs everything and creates the marker at Step 1.

Compilation Metadata

Field	Value
fingerprint	sha256:ee85b09e1a32fc99112f8d51a65f2f79ed142f89124e50854d4fd489109ddd4f (of reference/ice.md)
compiled_by	play-editor (#467 Batch B); prior: play-editor (#466 Batch C)
pipeline_position	none
position_exception	middle of the strategy pipeline — runs on the branch /vision started; the close belongs to /roadmap (#437)
workflow_structure	A (single checkpoint — class: standard, conditional gate per gate-config.md #467; stop-condition gated close)
stop_condition	stop-condition.yaml (D1–D3), gate live at Step C0
domain_agents	1 (product-os-keeper)
utility_agents	0
skills_used	search-kb, author-shape-bundle
scripts	10 (preflight.py, check_ready.py, validate_shape.py, apply_shape.py, check_shape.py, classify_change.py, gate_eval.py, distill_gate_policy.py, check_stop_condition.py, session_stamp.py)
step_evals	15 (SE-1…SE-15)
scenario_evals	8 (SCE-1…SCE-8)
recovery_entries	15 (one per failure condition; 12 autonomous / 3 human)

Recompiled note (#467 Batch B): checkpoint upgraded to a conditional learned gate; see gate-config.md.