@izkac/forgekit 0.3.11 → 0.3.13

package/vendor/skills/forge/phases/brainstorm.md

@@ -1,23 +1,23 @@
-# Brainstorm phase
-
-Read and follow [../skills/brainstorming/SKILL.md](../skills/brainstorming/SKILL.md) in full.
-
-**Pace:** Honor `brainstorm.depth` from [../references/pace.md](../references/pace.md) / `forge status` — `full` (default skill), `short` (≤2–3 approaches), or `minimal` (confirm intent + one approach when design is obvious).
-
-## Terminal state
-
-After user approves the design:
-
-1. Save to `.forge/sessions/<id>/brainstorm/notes.md` and `decisions.md`
-2. Read [../references/plan-routing.md](../references/plan-routing.md) and **proceed to OpenSpec propose** — do not ask for a plan mode
-3. Follow [plan-openspec.md](./plan-openspec.md) — **not** implementation until OpenSpec artefacts are approved
-
-```bash
-forge phase brainstorm
-# after OpenSpec propose:
-forge phase plan --plan-type openspec --openspec <name>
-```
-
-<HARD-GATE>
-Do NOT invoke implement phase or write production code until OpenSpec plan phase completes and user approves.
-</HARD-GATE>
+# Brainstorm phase
+
+Read and follow [../skills/brainstorming/SKILL.md](../skills/brainstorming/SKILL.md) in full.
+
+**Pace:** Honor `brainstorm.depth` from [../references/pace.md](../references/pace.md) / `forge status` — `full` (default skill), `short` (≤2–3 approaches), or `minimal` (confirm intent + one approach when design is obvious).
+
+## Terminal state
+
+After user approves the design:
+
+1. Save to `.forge/sessions/<id>/brainstorm/notes.md` and `decisions.md`
+2. Read [../references/plan-routing.md](../references/plan-routing.md) and **proceed to OpenSpec propose** — do not ask for a plan mode
+3. Follow [plan-openspec.md](./plan-openspec.md) — **not** implementation until OpenSpec artefacts are approved
+
+```bash
+forge phase brainstorm
+# after OpenSpec propose:
+forge phase plan --plan-type openspec --openspec <name>
+```
+
+<HARD-GATE>
+Do NOT invoke implement phase or write production code until OpenSpec plan phase completes and user approves.
+</HARD-GATE>

package/vendor/skills/forge/phases/finish.md

@@ -1,87 +1,90 @@
-# Finish phase
-
-Before marking done, integrity must pass (or the user must approve an incomplete finish):
-
-```bash
-forge integrity-check    # spine + deferrals + executed e2e (green, current) / BLOCKED
-forge score              # preview L2 scorecard (optional)
-forge phase done         # runs integrity checks + writes scorecard.md/json
-# escape hatch only with an honest reason:
-# forge phase done --allow-incomplete "E2E blocked: no Compose in this environment"
-```
-
-`forge phase done|finish` always writes `.forge/sessions/<id>/scorecard.md` (and
-`.json`) — an L2 grade of session artifacts. Answer the **human ship-check**
-questions in that file for platform/async work (L3). See [usage.md](../../../docs/usage.md)
-§ Session success.
-
-## OpenSpec path (`planType: openspec`)
-
-1. Confirm all tasks complete in `tasks.md`.
-2. User runs or approves `/opsx:archive` / `openspec archive`.
-3. **ADR follow-up (optional):** if `.forge/config.json` has `adr.enabled: true`
-   (or the project uses ADRs), follow the **`archive-to-adr`** skill using
-   `adr.dir` / `adr.decisionsDoc`. If ADRs are disabled, skip.
-4. End with **Suggested commit** block (display only — do not commit).
-
-```bash
-forge phase done
-forge cleanup
-```
-
-## Specs path (`planType: specs`)
-
-1. Confirm all tasks complete in `<specsDir>/changes/<name>/tasks.md`.
-2. **Archive** (with user approval) — prefer the CLI:
-
-   ```bash
-   forge change archive <name>
-   # → <specsDir>/changes/archive/YYYY-MM-DD-<name>
-   ```
-
-   Or move manually:
-
-   ```bash
-   git mv <specsDir>/changes/<name> <specsDir>/changes/archive/<YYYY-MM-DD>-<name>
-   ```
-
-   (plain `mv` if the dir is untracked).
-3. **ADR follow-up (optional):** same rule as OpenSpec — if `adr.enabled`,
-   follow **`archive-to-adr`** on the archived change; otherwise skip.
-4. End with **Suggested commit** block (display only — do not commit).
-
-```bash
-forge phase done
-forge cleanup
-```
-
-## Throwaway path (`planType: throwaway`)
-
-1. Confirm all tasks in `plan.md` checked off.
-2. Summarize what shipped.
-3. Mark session done and cleanup:
-
-```bash
-forge phase done
-forge cleanup
-```
-
-## Direct path (`planType: direct`)
-
-1. Confirm implementation matches brainstorm `notes.md` / `decisions.md`.
-2. Summarize what shipped.
-3. Mark session done and cleanup:
-
-```bash
-forge phase done
-forge cleanup
-```
-
-## Skipped path (`/forge:skip`)
-
-Session already at `phase: skipped`. No finish steps.
-
-## Hand-off
-
-Leave implementation files staged/unstaged per user preference. Never commit unless
-explicitly asked (project git policy).
+# Finish phase
+
+Before marking done, integrity must pass (or the user must approve an incomplete finish):
+
+```bash
+forge integrity-check    # spine + deferrals + executed e2e (green, current) / BLOCKED
+forge score              # preview L2 scorecard (optional)
+forge phase done         # runs integrity checks + writes scorecard.md/json
+# escape hatch only with an honest reason:
+# forge phase done --allow-incomplete "E2E blocked: no Compose in this environment"
+```
+
+`forge phase done|finish` always writes `.forge/sessions/<id>/scorecard.md` (and
+`.json`) — an L2 grade of session artifacts. Answer the **human ship-check**
+questions in that file for platform/async work (L3). See [usage.md](../../../docs/usage.md)
+§ Session success.
+
+## OpenSpec path (`planType: openspec`)
+
+1. Confirm all tasks complete in `tasks.md`.
+2. User runs or approves `/opsx:archive` / `openspec archive`.
+3. **ADR follow-up (optional):** if `.forge/config.json` has `adr.enabled: true`
+   (or the project uses ADRs), follow the **`archive-to-adr`** skill using
+   `adr.dir` / `adr.decisionsDoc`. If ADRs are disabled, skip.
+4. End with **Suggested commit** block (display only — do not commit).
+
+```bash
+forge phase done
+forge cleanup
+```
+
+## Specs path (`planType: specs`)
+
+1. Confirm all tasks complete in `<plan.dir>/changes/<name>/tasks.md`.
+2. **Archive** (with user approval) — prefer the CLI (merges delta specs into
+   `<plan.dir>/specs/` first, matching OpenSpec archive behavior):
+
+   ```bash
+   forge change archive <name>
+   # → sync deltas → <plan.dir>/specs/<cap>/spec.md
+   # → <plan.dir>/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+   Skip the merge with `--no-sync` only when deliberate. Or move manually
+   (you must sync deltas yourself):
+
+   ```bash
+   git mv <plan.dir>/changes/<name> <plan.dir>/changes/archive/<YYYY-MM-DD>-<name>
+   ```
+
+   (plain `mv` if the dir is untracked).
+3. **ADR follow-up (optional):** same rule as OpenSpec — if `adr.enabled`,
+   follow **`archive-to-adr`** on the archived change; otherwise skip.
+4. End with **Suggested commit** block (display only — do not commit).
+
+```bash
+forge phase done
+forge cleanup
+```
+
+## Throwaway path (`planType: throwaway`)
+
+1. Confirm all tasks in `plan.md` checked off.
+2. Summarize what shipped.
+3. Mark session done and cleanup:
+
+```bash
+forge phase done
+forge cleanup
+```
+
+## Direct path (`planType: direct`)
+
+1. Confirm implementation matches brainstorm `notes.md` / `decisions.md`.
+2. Summarize what shipped.
+3. Mark session done and cleanup:
+
+```bash
+forge phase done
+forge cleanup
+```
+
+## Skipped path (`/forge:skip`)
+
+Session already at `phase: skipped`. No finish steps.
+
+## Hand-off
+
+Leave implementation files staged/unstaged per user preference. Never commit unless
+explicitly asked (project git policy).

package/vendor/skills/forge/phases/implement.md

@@ -1,77 +1,77 @@
-# Implement phase
-
-Read and follow [../skills/subagent-driven-development/SKILL.md](../skills/subagent-driven-development/SKILL.md).
-
-Every implementer subagent must follow [../references/tdd-core.md](../references/tdd-core.md) (condensed TDD rules — the brief includes the pointer; full skill only when stuck).
-
-On test failures or unexpected behavior, use [../skills/systematic-debugging/SKILL.md](../skills/systematic-debugging/SKILL.md) before proposing fixes.
-
-**Test strategy:** [../references/test-strategy.md](../references/test-strategy.md) — tier 1 (scoped TDD) + tier 2 (narrow task evidence) during implement; **tier 3 (full workspace) runs once at verify**, not per task.
-
-**Pace:** Read `resolvedPace` / effective knobs from `forge status` (or [../references/pace.md](../references/pace.md)). After each task, decide whether to dispatch a reviewer via `review.perTask` + hard floor:
-
-| `review.perTask` | When to dispatch reviewer |
-| ---------------- | ------------------------- |
-| `always` | After every task (`thorough`) |
-| `per-group` | When the task closes a `tasks.md` group (`##` section — OpenSpec or specs engine), or immediately if the task is high-risk (`standard`) |
-| `high-risk-only` / `never` | Only when hard-floor high-risk |
-
-When skipping the reviewer, still write `task-review.md` with `APPROVED (pace self-check)` and keep tier-2 evidence mandatory for behavior changes. For `per-group` reviews, cover all tasks in that section in one reviewer pass; save as `group-review.md` next to the group’s tasks (or under `.forge/sessions/<id>/tasks/group-<nn>-<slug>/group-review.md`). Prefer `--tier fast` when `models.bias` is `prefer-fast` and the task is mechanical. Cap fix→re-review loops at `review.maxRounds`.
-
-## Plan source
-
-| planType | Task list |
-| -------- | --------- |
-| `openspec` | `openspec/changes/<name>/tasks.md` via **`/forge:apply`** (preferred), **`openspec-apply-change`** / `/opsx:apply` |
-| `specs` | `<specsDir>/changes/<name>/tasks.md` (default `specs/`) — read directly; no vendor CLI steps |
-
-Legacy sessions with planType `throwaway` or `direct`: resume from the session's own artefacts (`plan.md` / `brainstorm/notes.md`); new work always uses the configured engine (`openspec` or `specs`).
-
-For OpenSpec: follow `openspec-apply-change` for CLI steps, but **wrap each task** in the subagent loop (do not implement all tasks inline in coordinator context). For specs: read `proposal.md` / `design.md` / `tasks.md` from the change dir as context, then run the same subagent loop.
-
-## Runtime integrity (hard)
-
-Honor [../references/runtime-integrity.md](../references/runtime-integrity.md) in every brief and review packet:
-
-- Briefs **must never** contain “stub OK”, “later task”, “minimal poll loop only”, or equivalent. Shrink scope only by stopping and asking the user.
-- Capability specs beat narrow task wording. Fill reviewer `{CAPABILITY_SPEC_EXCERPT}` from the change's capability specs — not only the task line.
-- Do not mark a section complete if libraries exist but nothing in the production path calls them.
-- **Deferrals:** if wiring genuinely lands in a later task, register it — `forge defer add --task <id> --reason "…"` — and resolve it when that task lands. Unregistered "later" is a REJECT; unresolved deferrals block `forge phase done`.
-- **Spine:** when a task wires a capability into production, update its `spine.json` row (runtimeOwner / writes / evidence). `forge spine check` must pass before verify ends.
-- **E2E:** the product-loop acceptance task (last implement task) delivers working `e2e.json` steps and a green `forge e2e run` — steps that would pass against a stubbed handler are invalid.
-
-## Per-task loop
-
-1. Extract full task text + file paths + relevant **capability** spec sections (not only the task checkbox line).
-2. Write `.forge/sessions/<id>/tasks/<nn>-<slug>/brief.md` using [../subagents/implementer-prompt.md](../subagents/implementer-prompt.md).
-3. Dispatch **implementer** subagent — brief includes [../references/tdd-core.md](../references/tdd-core.md). **Model:** resolve via `forge resolve-model --tier <fast|standard|capable>` (billing defaults to **`included`** — subscription/first-party pool; never invent API model slugs). Use `fast` for mechanical tasks (1–2 files, complete spec) and batched small tasks; `standard` for multi-file integration; escalate one capability tier (still `included`) when re-dispatching after `BLOCKED`. If `omitModel` is true, omit the Task `model` parameter.
-4. **Reviewer** (unless pace skips it):
-   - **`always` / high-risk hard floor:** dispatch [../subagents/task-reviewer-prompt.md](../subagents/task-reviewer-prompt.md) for this task → `task-review.md`.
-   - **`per-group` at group boundary:** dispatch one reviewer covering **all tasks in the just-finished `tasks.md` group** → `group-review.md` (include each task id + paths). Mid-group low-risk tasks: self-check `task-review.md` only.
-   - If `review.depth` is `spec-only`, focus on spec + tests evidence. Fill `{DIFF_RANGE}` and `{CAPABILITY_SPEC_EXCERPT}` — read actual code, not the implementer's summary. **Model:** `forge resolve-model --tier standard` (or `capable` for money/auth/contracts; use `fast` when `models.bias` is `prefer-fast` and not high-risk). Do **not** skip high-risk tasks.
-5. Fix loop until the reviewer approves (max `review.maxRounds` from pace; then escalate to the human). For group reviews, fix any rejected task in the group before continuing to the next group.
-6. Record **test evidence** from the implementer's report (every task, even when review is deferred to group end):
-   ```bash
-   forge evidence --task <nn>-<slug> --command "<tier-2 cmd>" --exit 0 --summary "<pass summary>"
-   ```
-   (Refuses non-zero exit without `--allow-fail`; template + rules in [../references/test-evidence.md](../references/test-evidence.md).)
-7. Mark task complete (`tasks.md` `- [x]` or update `tasksComplete`). Detect group boundary: next line in `tasks.md` is a new `##` heading, or no remaining tasks under the current heading.
-8. Repeat.
-
-**Batching:** consecutive small same-area tasks (docs, config, wording) may share one implementer brief + one review — see the batching rules in [subagent-driven-development](../skills/subagent-driven-development/SKILL.md). Never batch money/auth/contract/migration tasks.
-
-```bash
-forge phase implement --tasks-complete <N> --subagents <total dispatched so far>
-```
-
-## Forge constraints (include in every brief)
-
-- **No** autonomous `git commit` or `git push`
-- **Tier 2 tests only** before claiming task done — narrowest command for this task ([test-strategy.md](../references/test-strategy.md)); **not** the full workspace suite unless the task requires it
-- Trace ecosystem consumers when contracts change
-- Minimal diff — surgical changes only
-- Runtime integrity: no stubs / false success; name the runtime caller; tests must fail on a no-op ([runtime-integrity.md](../references/runtime-integrity.md))
-
-## After all tasks
-
-Proceed to [verify.md](./verify.md) then [review.md](./review.md).
+# Implement phase
+
+Read and follow [../skills/subagent-driven-development/SKILL.md](../skills/subagent-driven-development/SKILL.md).
+
+Every implementer subagent must follow [../references/tdd-core.md](../references/tdd-core.md) (condensed TDD rules — the brief includes the pointer; full skill only when stuck).
+
+On test failures or unexpected behavior, use [../skills/systematic-debugging/SKILL.md](../skills/systematic-debugging/SKILL.md) before proposing fixes.
+
+**Test strategy:** [../references/test-strategy.md](../references/test-strategy.md) — tier 1 (scoped TDD) + tier 2 (narrow task evidence) during implement; **tier 3 (full workspace) runs once at verify**, not per task.
+
+**Pace:** Read `resolvedPace` / effective knobs from `forge status` (or [../references/pace.md](../references/pace.md)). After each task, decide whether to dispatch a reviewer via `review.perTask` + hard floor:
+
+| `review.perTask` | When to dispatch reviewer |
+| ---------------- | ------------------------- |
+| `always` | After every task (`thorough`) |
+| `per-group` | When the task closes a `tasks.md` group (`##` section — OpenSpec or specs engine), or immediately if the task is high-risk (`standard`) |
+| `high-risk-only` / `never` | Only when hard-floor high-risk |
+
+When skipping the reviewer, still write `task-review.md` with `APPROVED (pace self-check)` and keep tier-2 evidence mandatory for behavior changes. For `per-group` reviews, cover all tasks in that section in one reviewer pass; save as `group-review.md` next to the group’s tasks (or under `.forge/sessions/<id>/tasks/group-<nn>-<slug>/group-review.md`). Prefer `--tier fast` when `models.bias` is `prefer-fast` and the task is mechanical. Cap fix→re-review loops at `review.maxRounds`.
+
+## Plan source
+
+| planType | Task list |
+| -------- | --------- |
+| `openspec` | `openspec/changes/<name>/tasks.md` via **`/forge:apply`** (preferred), **`openspec-apply-change`** / `/opsx:apply` |
+| `specs` | `<specsDir>/changes/<name>/tasks.md` (default `specs/`) — read directly; no vendor CLI steps |
+
+Legacy sessions with planType `throwaway` or `direct`: resume from the session's own artefacts (`plan.md` / `brainstorm/notes.md`); new work always uses the configured engine (`openspec` or `specs`).
+
+For OpenSpec: follow `openspec-apply-change` for CLI steps, but **wrap each task** in the subagent loop (do not implement all tasks inline in coordinator context). For specs: read `proposal.md` / `design.md` / `tasks.md` from the change dir as context, then run the same subagent loop.
+
+## Runtime integrity (hard)
+
+Honor [../references/runtime-integrity.md](../references/runtime-integrity.md) in every brief and review packet:
+
+- Briefs **must never** contain “stub OK”, “later task”, “minimal poll loop only”, or equivalent. Shrink scope only by stopping and asking the user.
+- Capability specs beat narrow task wording. Fill reviewer `{CAPABILITY_SPEC_EXCERPT}` from the change's capability specs — not only the task line.
+- Do not mark a section complete if libraries exist but nothing in the production path calls them.
+- **Deferrals:** if wiring genuinely lands in a later task, register it — `forge defer add --task <id> --reason "…"` — and resolve it when that task lands. Unregistered "later" is a REJECT; unresolved deferrals block `forge phase done`.
+- **Spine:** when a task wires a capability into production, update its `spine.json` row (runtimeOwner / writes / evidence). `forge spine check` must pass before verify ends.
+- **E2E:** the product-loop acceptance task (last implement task) delivers working `e2e.json` steps and a green `forge e2e run` — steps that would pass against a stubbed handler are invalid.
+
+## Per-task loop
+
+1. Extract full task text + file paths + relevant **capability** spec sections (not only the task checkbox line).
+2. Write `.forge/sessions/<id>/tasks/<nn>-<slug>/brief.md` using [../subagents/implementer-prompt.md](../subagents/implementer-prompt.md).
+3. Dispatch **implementer** subagent — brief includes [../references/tdd-core.md](../references/tdd-core.md). **Model:** resolve via `forge resolve-model --tier <fast|standard|capable>` (billing defaults to **`included`** — subscription/first-party pool; never invent API model slugs). Use `fast` for mechanical tasks (1–2 files, complete spec) and batched small tasks; `standard` for multi-file integration; escalate one capability tier (still `included`) when re-dispatching after `BLOCKED`. If `omitModel` is true, omit the Task `model` parameter.
+4. **Reviewer** (unless pace skips it):
+   - **`always` / high-risk hard floor:** dispatch [../subagents/task-reviewer-prompt.md](../subagents/task-reviewer-prompt.md) for this task → `task-review.md`.
+   - **`per-group` at group boundary:** dispatch one reviewer covering **all tasks in the just-finished `tasks.md` group** → `group-review.md` (include each task id + paths). Mid-group low-risk tasks: self-check `task-review.md` only.
+   - If `review.depth` is `spec-only`, focus on spec + tests evidence. Fill `{DIFF_RANGE}` and `{CAPABILITY_SPEC_EXCERPT}` — read actual code, not the implementer's summary. **Model:** `forge resolve-model --tier standard` (or `capable` for money/auth/contracts; use `fast` when `models.bias` is `prefer-fast` and not high-risk). Do **not** skip high-risk tasks.
+5. Fix loop until the reviewer approves (max `review.maxRounds` from pace; then escalate to the human). For group reviews, fix any rejected task in the group before continuing to the next group.
+6. Record **test evidence** from the implementer's report (every task, even when review is deferred to group end):
+   ```bash
+   forge evidence --task <nn>-<slug> --command "<tier-2 cmd>" --exit 0 --summary "<pass summary>"
+   ```
+   (Refuses non-zero exit without `--allow-fail`; template + rules in [../references/test-evidence.md](../references/test-evidence.md).)
+7. Mark task complete (`tasks.md` `- [x]` or update `tasksComplete`). Detect group boundary: next line in `tasks.md` is a new `##` heading, or no remaining tasks under the current heading.
+8. Repeat.
+
+**Batching:** consecutive small same-area tasks (docs, config, wording) may share one implementer brief + one review — see the batching rules in [subagent-driven-development](../skills/subagent-driven-development/SKILL.md). Never batch money/auth/contract/migration tasks.
+
+```bash
+forge phase implement --tasks-complete <N> --subagents <total dispatched so far>
+```
+
+## Forge constraints (include in every brief)
+
+- **No** autonomous `git commit` or `git push`
+- **Tier 2 tests only** before claiming task done — narrowest command for this task ([test-strategy.md](../references/test-strategy.md)); **not** the full workspace suite unless the task requires it
+- Trace ecosystem consumers when contracts change
+- Minimal diff — surgical changes only
+- Runtime integrity: no stubs / false success; name the runtime caller; tests must fail on a no-op ([runtime-integrity.md](../references/runtime-integrity.md))
+
+## After all tasks
+
+Proceed to [verify.md](./verify.md) then [review.md](./review.md).

package/vendor/skills/forge/phases/plan-openspec.md

@@ -1,60 +1,60 @@
-# Plan phase — OpenSpec
-
-Thin wrapper around the project **`openspec-propose`** skill (or `/opsx:propose`).
-
-## Steps
-
-1. Derive change name with correct product prefix (`openspec/config.yaml` (if the project uses OpenSpec prefixes)).
-2. Run `openspec-propose` / `/opsx:propose <prefix>-<slug>`.
-3. Confirm `tasks.md` exists and change is apply-ready.
-4. **Spine (always) + orchestration seam** — see [../references/runtime-integrity.md](../references/runtime-integrity.md):
-
-   ```bash
-   forge spine init     # mandatory every change — fill rows or set notApplicable
-   ```
-
-   Sync-only / docs-only: `"notApplicable": "<reason>"`. Capability work: one row
-   per REQ cluster (library → runtime owner → writes → evidence).
-
-   When the spine has real rows, also `forge e2e init` — the executable
-   product-loop steps (`e2e.json`) are a **plan deliverable**: author them (or
-   task out their authoring) so verify can `forge e2e run` them.
-
-   If the change also involves workers, job queues, handlers, or cross-runtime
-   calls, `tasks.md` MUST include:
-
-   - Explicit **wiring** tasks per job kind / entry point → domain pipeline
-   - One **product-loop acceptance** task (last implement task, before
-     verify) — its output is a green `forge e2e run`
-
-   Missing spine = plan **not** ready. (`forge phase done` refuses without a
-   valid spine and, when the spine has rows, a green current e2e run —
-   keyword sniffing does not decide.)
-
-5. **Operator brief (mandatory)** — see [../references/operator-brief.md](../references/operator-brief.md):
-   write `openspec/changes/<change-name>/brief.html` — a plain-language,
-   self-contained HTML explanation of what will be built (mermaid diagrams
-   where helpful), then:
-
-   ```bash
-   forge brief stamp    # records specs hash (does NOT auto-open)
-   ```
-
-   `forge phase implement` hard-refuses while the brief is missing or stale
-   (specs edited after stamping → rewrite affected sections and re-stamp).
-
-6. Update session:
-   ```bash
-   forge phase plan --plan-type openspec --openspec <change-name>
-   forge phase implement --tasks-total <N>
-   ```
-   Count tasks from `tasks.md` checkboxes.
-
-7. Get user approval to proceed to implement (unless they already said "go").
-   The brief is what the operator reviews — tell them its path and that
-   `forge brief open` launches it; never open it for them.
-
-## Session tracking
-
-Forge session holds orchestration artefacts; canonical plan lives under
-`openspec/changes/<name>/`.
+# Plan phase — OpenSpec
+
+Thin wrapper around the project **`openspec-propose`** skill (or `/opsx:propose`).
+
+## Steps
+
+1. Derive change name with correct product prefix (`openspec/config.yaml` (if the project uses OpenSpec prefixes)).
+2. Run `openspec-propose` / `/opsx:propose <prefix>-<slug>`.
+3. Confirm `tasks.md` exists and change is apply-ready.
+4. **Spine (always) + orchestration seam** — see [../references/runtime-integrity.md](../references/runtime-integrity.md):
+
+   ```bash
+   forge spine init     # mandatory every change — fill rows or set notApplicable
+   ```
+
+   Sync-only / docs-only: `"notApplicable": "<reason>"`. Capability work: one row
+   per REQ cluster (library → runtime owner → writes → evidence).
+
+   When the spine has real rows, also `forge e2e init` — the executable
+   product-loop steps (`e2e.json`) are a **plan deliverable**: author them (or
+   task out their authoring) so verify can `forge e2e run` them.
+
+   If the change also involves workers, job queues, handlers, or cross-runtime
+   calls, `tasks.md` MUST include:
+
+   - Explicit **wiring** tasks per job kind / entry point → domain pipeline
+   - One **product-loop acceptance** task (last implement task, before
+     verify) — its output is a green `forge e2e run`
+
+   Missing spine = plan **not** ready. (`forge phase done` refuses without a
+   valid spine and, when the spine has rows, a green current e2e run —
+   keyword sniffing does not decide.)
+
+5. **Operator brief (mandatory)** — see [../references/operator-brief.md](../references/operator-brief.md):
+   write `openspec/changes/<change-name>/brief.html` — a plain-language,
+   self-contained HTML explanation of what will be built (mermaid diagrams
+   where helpful), then:
+
+   ```bash
+   forge brief stamp    # records specs hash (does NOT auto-open)
+   ```
+
+   `forge phase implement` hard-refuses while the brief is missing or stale
+   (specs edited after stamping → rewrite affected sections and re-stamp).
+
+6. Update session:
+   ```bash
+   forge phase plan --plan-type openspec --openspec <change-name>
+   forge phase implement --tasks-total <N>
+   ```
+   Count tasks from `tasks.md` checkboxes.
+
+7. Get user approval to proceed to implement (unless they already said "go").
+   The brief is what the operator reviews — tell them its path and that
+   `forge brief open` launches it; never open it for them.
+
+## Session tracking
+
+Forge session holds orchestration artefacts; canonical plan lives under
+`openspec/changes/<name>/`.