prizmkit 1.1.130 → 1.1.131

package/bundled/skills/prizmkit-implement/references/workflow-state-protocol.md

@@ -0,0 +1,181 @@
+# PrizmKit Workflow State Protocol
+
+`workflow-state.json` is lifecycle runtime metadata for one formal requirement. It preserves stage handoff, repair routing, orchestrator ownership, and resume information without replacing authoritative artifacts or any host-owned execution checkpoint.
+
+## Location and Identity
+
+```text
+.prizmkit/state/workflows/<requirement-slug>.json
+```
+
+The state file is created only when a lifecycle runs. The active `artifact_dir` is the generic requirement artifact root and must be preserved exactly across every stage:
+
+```text
+.prizmkit/specs/<requirement-slug>/
+.prizmkit/bugfix/<bug-id>/
+.prizmkit/refactor/<refactor-id>/
+```
+
+Never select a different most-recent plan when resuming or handing off. Any execution checkpoint maintained by an external host remains separate from this lifecycle state. Never merge, substitute, or infer one schema from the other. The target project controls whether generated `.prizmkit/` files are committed, ignored, or shared.
+
+## Authority
+
+The state file is an index, not the authority for stage completion:
+
+| Information | Authority |
+|---|---|
+| Requirement goals and acceptance criteria | `{artifact_dir}/spec.md` |
+| Implementation tasks and completion | `{artifact_dir}/plan.md` plus current workspace |
+| Review findings and verdict | `{artifact_dir}/review-report.md` final result |
+| Test execution, verdict, and repair scope | Validated evidence package and authoritative `verdict.json` |
+| Test report presentation | `{artifact_dir}/test-report.md` as a derived view only |
+| Retrospective completion and result | `{artifact_dir}/retrospective-result.json` |
+| Durable architecture knowledge | `.prizmkit/prizm-docs/` |
+| Local commit | Git history and confirmed or authorized commit identity |
+| Current stage, orchestrator, and resume entry | Workflow state |
+| External orchestration progress | The external host's own checkpoint, never this state |
+
+Every consumer compares workflow state with authoritative artifacts and the current workspace. Missing or stale state is reconstructed from those sources and is never accepted as success by itself.
+
+## Schema
+
+```json
+{
+  "schema_version": 1,
+  "artifact_dir": ".prizmkit/specs/example",
+  "orchestrator": "prizmkit-workflow",
+  "stage": "test",
+  "status": "TEST_PASS",
+  "stage_result": "TEST_PASS",
+  "completed_stages": ["plan", "implement", "code-review", "test"],
+  "repair_scope": null,
+  "repair_round": 0,
+  "next_stage": "retrospective",
+  "resume_from": "prizmkit-retrospective"
+}
+```
+
+### Fields
+
+| Field | Meaning |
+|---|---|
+| `schema_version` | State schema version. Current value is `1`. |
+| `artifact_dir` | The single generic requirement artifact root reused by every stage. |
+| `orchestrator` | `prizmkit-workflow`, another semantic coordinator identifier, or `null` for direct stage use. |
+| `stage` | The stage that most recently wrote state. |
+| `status` | Lifecycle progression status, distinct from the domain `stage_result`. |
+| `stage_result` | Domain result such as `PASS`, `NEEDS_FIXES`, `TEST_*`, `DOCS_UPDATED`, or `NO_DOC_CHANGE`. |
+| `completed_stages` | Ordered stages completed for this requirement. |
+| `repair_scope` | `null`, `test-infrastructure`, `production`, `runtime`, `schema`, `dependency`, `public-interface`, or `unknown`. |
+| `repair_round` | Outer cross-stage repair round, from `0` through `3`. |
+| `next_stage` | Next semantic stage, or `null` after commit. |
+| `resume_from` | Exact atomic skill that can resume, or `null` after commit. |
+
+## Lifecycle and Verdict Mappings
+
+The mandatory formal lifecycle is:
+
+```text
+PLAN_READY
+  → IMPLEMENTED
+  → REVIEW_PASS
+  → TEST_PASS
+  → RETRO_COMPLETE
+  → COMMIT_PENDING
+  → COMMITTED
+```
+
+No formal stage is silently optional. Domain evidence maps as follows:
+
+```text
+review-report final PASS        → status=REVIEW_PASS, stage_result=PASS
+review-report final NEEDS_FIXES → status=REVIEW_NEEDS_FIXES, stage_result=NEEDS_FIXES
+validated verdict TEST_PASS     → status=TEST_PASS, stage_result=TEST_PASS
+validated verdict TEST_FAIL     → status=TEST_FAIL, stage_result=TEST_FAIL
+validated verdict TEST_BLOCKED  → status=TEST_BLOCKED, stage_result=TEST_BLOCKED
+retrospective result DOCS_UPDATED  → status=RETRO_COMPLETE, stage_result=DOCS_UPDATED
+retrospective result NO_DOC_CHANGE → status=RETRO_COMPLETE, stage_result=NO_DOC_CHANGE
+```
+
+`RETRO_COMPLETE` is the stable completion status. `DOCS_UPDATED` and `NO_DOC_CHANGE` are mutually exclusive retrospective results, not substitute statuses. A derived Markdown test report never establishes a `TEST_*` status without validated authoritative evidence.
+
+## Repair Routing
+
+```text
+REVIEW_NEEDS_FIXES
+  → implement
+  → code-review
+  → test
+
+TEST_FAIL with repair_scope=test-infrastructure
+  → implement
+  → test
+
+TEST_FAIL with repair_scope=production|runtime|schema|dependency|public-interface
+  → implement
+  → code-review
+  → test
+
+TEST_FAIL with repair_scope=unknown
+  → conservative production route only when safe
+  → otherwise WORKFLOW_BLOCKED
+
+TEST_BLOCKED
+  → never make speculative production edits
+  → interactive execution stops with a prizmkit-test resume entry
+  → a trusted headless host may perform bounded environment recovery, then records WORKFLOW_BLOCKED if unresolved
+
+RETRO_BLOCKED
+  → WORKFLOW_BLOCKED
+WORKFLOW_BLOCKED
+  → resume only after the recorded blocker is resolved
+```
+
+The outer workflow permits at most three automatic repair rounds. These are cross-stage rounds (`repair_round` `0` through `3`). The code-review internal loop permits at most ten completed review rounds and is separate; review-internal repairs do not increment the outer counter.
+
+## Orchestrator Ownership and Handoff
+
+1. An atomic stage performs only its own stage, writes the truthful terminal result and `next_stage`, and returns control.
+2. When `orchestrator` is non-null, only that orchestrator invokes the next skill. The atomic stage must not auto-invoke it again.
+3. Direct stage use may report one deterministic next invocation but does not claim the next stage ran.
+4. Every handoff preserves the same `artifact_dir`.
+5. External automation invokes atomic stages directly and does not invoke `prizmkit-workflow` as a nested coordinator.
+6. Workflow state never replaces or absorbs an external host's checkpoint.
+
+## Commit Authorization
+
+Interactive execution:
+
+```text
+committer previews intended files and message
+→ waits for explicit confirmation from the current user
+→ creates the local commit
+```
+
+Trusted headless execution:
+
+```text
+a trusted host explicitly authorizes the current local task commit
+→ host injects mode=<host-defined-headless-mode>, owner=<trusted-host-identifier>,
+  local_commit_authorized=true, push_authorized=false
+→ committer verifies gates and commits automatically
+→ no question, wait, or push is permitted
+```
+
+A self-declared or otherwise untrusted headless context does not authorize a commit. Push is never implied by either mode.
+
+## Recovery
+
+When state is missing, stale, or inconsistent:
+
+1. Read `spec.md` and `plan.md` from `artifact_dir` only when they are not already available in current context.
+2. Inspect task markers and the current workspace.
+3. Read the latest review report and final result when needed to establish review authority.
+4. Validate authoritative test evidence and `repair_scope`.
+5. Validate `retrospective-result.json` when retrospective is claimed complete.
+6. Verify the commit when commit is claimed complete.
+7. When an external host is active, let that host validate its own checkpoint independently; never merge the schemas.
+8. Reconstruct the latest safe predecessor and report the reconstruction.
+9. Continue only from the first incomplete or invalid stage.
+
+Stale state never bypasses review, testing, retrospective, commit authorization, or external host checkpoint enforcement.

package/bundled/skills/prizmkit-init/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: "prizmkit-init"
-description: "Project takeover and bootstrap. Scans any project, generates Prizm docs and project brief. Use this skill whenever a user opens a new project for the first time, says 'initialize', 'set up PrizmKit', 'take over this project', 'bootstrap', 'scan this codebase', 'init', or when .prizmkit/prizm-docs/ doesn't exist yet. Also use when PrizmKit was just installed via npx but not yet initialized. (project)"
+description: "Recommended one-time project initialization for PrizmKit. Scans greenfield or brownfield projects, generates Prizm docs and a project brief, and prepares optional context for the formal requirement lifecycle. Use for initialize, bootstrap, take over this project, or first-time setup requests. (project)"
 ---
 
 # PrizmKit Init
 
-Project takeover and bootstrap skill. Scans any project (brownfield or greenfield), generates Prizm documentation and project brief. Supports Codex, Claude Code, CodeBuddy, and multi-platform installations.
+Recommended project initialization skill. Scans any brownfield or greenfield project, generates Prizm documentation and a project brief, and adapts to the current AI coding host when platform-specific instruction files are present.
 
 ### When to Use
 - Taking over a new project (brownfield or greenfield)
 - User says "initialize PrizmKit", "set up PrizmKit", "take over this project"
 - First time using PrizmKit on a project
-- After `npx prizmkit install` when project has no `.prizmkit/prizm-docs/`
+- After the PrizmKit skills are installed (for example with `npx skills add`) when the project has no `.prizmkit/prizm-docs/`
 
 ### When NOT to Use
 - All artifacts exist and are up to date → skip init; use `/prizmkit-prizm-docs` Status/Validate for health checks
@@ -26,7 +26,7 @@ Project takeover and bootstrap skill. Scans any project (brownfield or greenfiel
 ## Execution Steps
 
 **Phase 1: Platform Detection**
-1. Detect which platform is running (Codex, Claude Code, or CodeBuddy) via AI CLI environment.
+1. Detect the current AI coding host through available environment signals. Platform-specific files such as `AGENTS.md`, `CLAUDE.md`, or `CODEBUDDY.md` are non-exhaustive examples, not protocol identifiers.
 2. Hold detected platform value in memory — written to disk in Phase 6 along with other config fields.
 
 **Phase 2: Mode Detection**
@@ -140,7 +140,7 @@ Detect database and deployment signals, then ask 1-2 brief questions. This phase
    - If "SaaS platform": follow up with platform selection (Vercel / Railway / Fly.io / Cloudflare / AWS / Other)
 
 3. **Write results**:
-   - Append `### Infrastructure` section to the detected **main** platform instruction file (`AGENTS.md` for Codex, `CLAUDE.md` for Claude Code, `CODEBUDDY.md` for CodeBuddy). Do not write Infrastructure to `AGENTS.private.md`, `CLAUDE.private.md`, or `CODEBUDDY.private.md`; private files are reserved for PrizmKit framework protocol imports. Format:
+   - Append `### Infrastructure` to the detected host's main instruction file when that file exists. Use the host's conventional main instruction file; examples include `AGENTS.md`, `CLAUDE.md`, and `CODEBUDDY.md`. Do not write Infrastructure to private instruction files reserved for framework protocol imports. Format:
      ```markdown
      ### Infrastructure
 

package/bundled/skills/prizmkit-plan/SKILL.md

@@ -1,131 +1,158 @@
 ---
 name: "prizmkit-plan"
-description: "Specify and plan development tasks: natural language → change artifact with spec.md and plan.md. Works for features, bug fixes, refactors, migrations, and other non-trivial changes. Use before /prizmkit-implement when the task needs written scope, design, or executable tasks; use simplified planning for Fast path changes and full planning for high-risk or multi-module work. Trigger on: 'specify', 'plan', 'new task', 'I want to add/build...', 'architect', 'design', 'break it down', 'create tasks'. (project)"
+description: "Start the formal PrizmKit requirement lifecycle by turning a natural-language change into reviewed spec.md and plan.md artifacts, initializing workflow state, and handing off to prizmkit-implement. Works for features, bug fixes, refactors, migrations, tests, and other formal requirements. (project)"
 ---
 
 # PrizmKit Plan
 
-A universal spec + plan generator. It turns a natural-language development task into a **change artifact**: `spec.md` (WHAT/WHY) and `plan.md` (HOW + Tasks).
+`/prizmkit-plan` is the entry point for one formal requirement. It converts a natural-language change into a reviewed change artifact: `spec.md` defines WHAT and WHY; `plan.md` defines HOW and executable tasks.
 
-A change artifact is not feature-only. It can describe a feature, bug fix, refactor, migration, test improvement, or other scoped change.
+A change artifact can describe a feature, bug fix, refactor, migration, test improvement, or another scoped requirement.
 
-### When to Use
-- Any non-trivial development task that benefits from written scope and task breakdown
-- Before `/prizmkit-implement` when no suitable `plan.md` exists
-- Fast path changes that still need a simplified plan and resumable Tasks section
-- Full path changes involving multiple files/modules, public interfaces, data models, architecture, security, or unclear requirements
-- User says "specify", "plan", "new task", "I want to add...", "architect", "design", or "break it down"
+## When to Use
 
-### When NOT to Use
-- Direct edit: typo, pure formatting, small docs edit, or tiny config tweak with no behavior impact
-- User explicitly asks for a one-off direct edit and the risk is low
-- A current artifact directory already has an adequate `spec.md` + `plan.md` for the requested work
+- Starting any formal software requirement.
+- A non-trivial change benefits from written scope, acceptance criteria, and task breakdown.
+- No adequate current `spec.md` and `plan.md` exist for the requested work.
+- User says "specify", "plan", "new task", "I want to add...", "architect", "design", or "break it down".
 
-## Path Selection
+## When NOT to Use
 
-Choose the lightest planning depth that protects correctness:
+- Direct edit: typo, pure formatting, small documentation edit, or another explicitly low-risk non-requirement change.
+- The active artifact directory already has an adequate reviewed `spec.md` and `plan.md`; resume from the workflow state instead.
 
-| Path | Planning behavior |
-|---|---|
-| Direct edit | Skip `/prizmkit-plan`; edit directly and verify the specific change. |
-| Fast path | Create a concise `spec.md` and simplified `plan.md` with a Tasks section. |
-| Full path | Create full `spec.md` and `plan.md` with architecture, risks, tests, and executable tasks. |
+## Formal Lifecycle
 
-Use Full path for high-risk, multi-module, public API, data model, security, permission, payment, deployment-impacting, or ambiguous work. Use Fast path for small scoped behavior changes. Explain the chosen path briefly.
+A successful plan starts this fixed lifecycle:
+
+```text
+plan → implement → code-review → test → retrospective → committer
+```
+
+Planning depth may be concise or comprehensive, but no later formal lifecycle stage may be silently skipped.
 
 ## Input
 
 | Parameter | Required | Description |
-|-----------|----------|-------------|
-| `description` | Yes | Natural-language description of the task |
-| `artifact_dir` | No | Directory to write the change artifact into. If omitted, auto-generates under `.prizmkit/specs/` using a numbered slug. |
-
-## Execution
-
-### Phase 0: Specify (`spec.md`)
-
-Skip this phase if `spec.md` already exists in the artifact directory and still matches the requested change.
-
-Steps:
-
-1. Gather the task description. If missing and interactive, ask the user; otherwise abort with a clear error.
-2. Determine artifact directory:
-   - If `artifact_dir` is provided, use it directly.
-   - If omitted, scan `.prizmkit/specs/` for existing numbered directories and create `.prizmkit/specs/###-task-slug/`.
-   - The `.prizmkit/specs/` path is a generic change-artifact location; it is not limited to features.
-3. Load project context: read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs. If L2 is missing for an affected module, use relevant source files as fallback context.
-4. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
-   - Focus on WHAT and WHY, not HOW.
-   - Include only relevant sections.
-   - Every goal needs acceptance criteria.
-   - Mark genuine ambiguity with `[NEEDS CLARIFICATION]`.
-5. If changes involve persistence, add a Data Model section. Read existing schema files to learn naming conventions, ID strategy, constraints, and migration patterns.
-6. Resolve `[NEEDS CLARIFICATION]` markers:
-   - Interactive: ask targeted questions using `${SKILL_DIR}/references/clarify-guide.md`.
-   - Non-interactive: choose conservative defaults and annotate the decision.
-
-Internal ID hygiene: PrizmKit IDs, task IDs, session/run IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths are internal metadata. They may appear in change artifacts, but do not write them into `.prizmkit/prizm-docs/`, product UI copy, API responses, emails, notifications, or expected user-visible test strings.
-
-### Phase 1: Design (`plan.md`)
-
-Precondition: `spec.md` exists.
-
-Steps:
-
-1. Read `spec.md`.
-2. Load project context if not already loaded: root Prizm doc, relevant L1/L2 docs, and source fallback for missing L2 docs.
-3. Resolve any remaining clarification markers.
-4. Generate `plan.md` from `${SKILL_DIR}/assets/plan-template.md`:
-   - Change approach
-   - Component/file changes
-   - Data model changes and migration approach when relevant
-   - Interface/API contract design when relevant
-   - Testing strategy, using risk-triggered `/prizmkit-test` criteria
-   - Risk assessment
-   - Behavior preservation strategy for refactors or behavior-adjacent changes
-5. Cross-check every spec goal maps to a plan component.
-6. Check alignment with `.prizmkit/prizm-docs/root.prizm` RULES.
-
-### Phase 2: Task Generation
-
-1. Choose task strategy: MVP-first, incremental, or parallel. Ask in interactive mode when the choice affects execution; otherwise infer from risk and dependencies.
-2. Append `## Tasks` to `plan.md` using `${SKILL_DIR}/assets/plan-template.md`:
-   - Setup tasks
-   - Foundation tasks
-   - Core tasks mapped to goals or logical units
-   - Polish tasks when needed
-   - Checkpoint tasks between phases when integration risk exists
-3. Mark parallel tasks with `[P]` only when they can safely run independently.
-4. Run the verification checklist from `${SKILL_DIR}/references/verification-checklist.md` and fix issues before the planning quality gate.
-
-### Phase 3: Plan/Spec Review Loop
-
-Run this phase every time `spec.md` and `plan.md` are created or updated, before reporting the plan or handing off to implementation.
-
-1. Explicitly read `${SKILL_DIR}/references/review-plan-spec-loop.md`.
-2. Execute that guide against the current `spec.md` and `plan.md`.
-3. Apply all resolvable `BLOCKER` fixes and accepted `SHOULD_FIX` fixes directly to `spec.md` and/or `plan.md`.
+|---|---|---|
+| `description` | Yes | Natural-language description of the requirement. |
+| `artifact_dir` | No | Directory for the change artifact. If omitted, create a numbered slug under `.prizmkit/specs/`. |
+
+## Atomic Stage Boundary
+
+`prizmkit-plan` owns only specification, plan, task generation, and planning-quality review. It writes its truthful terminal result and `next_stage`, then returns control. It must not invoke `prizmkit-implement` itself, including when an external orchestrator is active. The active orchestrator owns the next-stage invocation.
+
+## Phase 0: Initialization Check and Context
+
+1. Check whether project context such as `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json`, or a project brief exists.
+2. If initialization context is missing:
+   - recommend `/prizmkit-init` and explain that it improves project context and cross-session continuity;
+   - do not block planning;
+   - if the user continues, load the README, manifests, project instruction files, source structure, and relevant source files as fallback.
+3. If Prizm docs exist, read `root.prizm`, relevant L1 docs, relevant L2 docs when present, and source fallback when L2 is absent.
+4. Resolve `artifact_dir` once and reuse it for every later lifecycle handoff. Do not re-detect another artifact during the same requirement.
+
+## Phase 1: Specify (`spec.md`)
+
+Skip regeneration when `spec.md` already exists and still matches the requested requirement.
+
+1. Gather the requirement description. If it is missing in an interactive run, ask the user; otherwise return a clear blocked result.
+2. Determine the artifact directory:
+   - use the caller-provided `artifact_dir` when present;
+   - otherwise scan `.prizmkit/specs/` for existing numbered directories and create `.prizmkit/specs/###-task-slug/`.
+3. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
+   - focus on WHAT and WHY, not HOW;
+   - include only relevant sections;
+   - give every goal acceptance criteria;
+   - mark genuine ambiguity with `[NEEDS CLARIFICATION]`.
+4. For persistence changes, inspect existing schemas and add a Data Model section using project conventions.
+5. Resolve clarification markers:
+   - interactive: use `${SKILL_DIR}/references/clarify-guide.md` and ask targeted questions;
+   - non-interactive: choose conservative defaults, annotate them, and block when a safe default is impossible.
+
+Internal ID hygiene: PrizmKit IDs, task/session/run IDs, branch names, absolute worktree paths, and internal artifact paths may exist in change artifacts but must not leak into `.prizmkit/prizm-docs/`, product UI copy, API responses, emails, notifications, or expected user-visible test strings.
+
+## Phase 2: Design (`plan.md`)
+
+Precondition: `spec.md` exists with no unresolved blocker.
+
+1. Read `spec.md` and relevant project context.
+2. Resolve remaining clarification markers.
+3. Choose a planning depth appropriate to the requirement:
+   - concise for small, well-scoped formal requirements;
+   - comprehensive for multi-module, public API, data model, security, permission, payment, deployment-impacting, or ambiguous requirements.
+4. Generate `plan.md` from `${SKILL_DIR}/assets/plan-template.md` with:
+   - change approach;
+   - component and file changes;
+   - data migration approach when relevant;
+   - interface/API contract design when relevant;
+   - test strategy for the mandatory `/prizmkit-test` stage;
+   - risks and mitigations;
+   - behavior-preservation strategy for refactors.
+5. Cross-check every spec goal against the plan.
+6. Check alignment with project rules and available Prizm documentation.
+
+## Phase 3: Task Generation
+
+1. Choose an MVP-first, incremental, or safe parallel task strategy.
+2. Append `## Tasks` to `plan.md` using `${SKILL_DIR}/assets/plan-template.md`.
+3. Include setup, foundation, core, polish, and checkpoint tasks only when applicable.
+4. Mark `[P]` only for tasks that can safely execute independently.
+5. Include implementation-local verification where useful, while preserving the later full code-review and test stages.
+6. Run `${SKILL_DIR}/references/verification-checklist.md` and repair plan defects.
+
+## Phase 4: Plan/Spec Review Loop
+
+Run every time `spec.md` or `plan.md` is created or changed.
+
+1. Read `${SKILL_DIR}/references/review-plan-spec-loop.md`.
+2. Review the current artifacts against the requirement and project context.
+3. Apply all resolvable `BLOCKER` fixes and accepted `SHOULD_FIX` fixes.
 4. Treat `OPTIONAL` findings as non-blocking.
-5. Rerun the review once when fixes were applied, respecting the guide's maximum of 2 total rounds.
-6. If unresolved `BLOCKER` findings remain, stop and ask targeted clarification questions in interactive mode; in non-interactive mode, record the blocker and stop. Do not escalate to a Critic agent.
-7. Only proceed to `/prizmkit-implement` handoff after the loop has no unresolved blockers.
+5. Rerun once when fixes were applied, with a maximum of two planning-review rounds.
+6. If a `BLOCKER` remains, ask targeted questions in interactive mode; otherwise record `PLAN_BLOCKED` and stop.
+7. Continue only when no unresolved blocker remains.
+
+The planning review must not implement code, run the full test stage, or launch external orchestration.
+
+## Phase 5: Workflow State and Handoff
+
+Read `${SKILL_DIR}/references/workflow-state-protocol.md` and create or update:
+
+```text
+.prizmkit/state/workflows/<requirement-slug>.json
+```
+
+Follow the bundled protocol. At minimum record:
+
+```json
+{
+  "schema_version": 1,
+  "artifact_dir": ".prizmkit/specs/001-example",
+  "stage": "plan",
+  "status": "PLAN_READY",
+  "completed_stages": ["plan"],
+  "repair_round": 0,
+  "repair_scope": null,
+  "next_stage": "implement",
+  "resume_from": "prizmkit-implement"
+}
+```
 
-The review loop is planning-only. It must not start implementation, run tests/builds, launch a pipeline, create a separate skill, or require a Critic agent.
+The state file is runtime metadata. Do not change the target project's Git or ignore policy.
 
 ## Output
 
-| Directory | Files |
-|---|---|
-| `artifact_dir` or auto-generated `.prizmkit/specs/###-slug/` | `spec.md` + `plan.md` |
+- `spec.md` and `plan.md` in the resolved artifact directory.
+- Workflow state with `PLAN_READY` or a truthful blocked result.
+- Planning depth, key decisions, task count, and checkpoint summary.
+- The same `artifact_dir` for every downstream stage.
 
-Report:
-- artifact directory
-- chosen path: Fast path or Full path
-- key decisions
-- task count and checkpoint summary
+## Handoff
 
-**HANDOFF:** `/prizmkit-implement`
+On `PLAN_READY`:
 
-## Examples
+1. If workflow state names an active `orchestrator`, return `PLAN_READY`, `stage_result=PLAN_READY`, `next_stage=implement`, the state path, and the same `artifact_dir` to that orchestrator; do not invoke the next stage independently.
+2. For direct stage use with no active orchestrator, report exactly one deterministic next action: `/prizmkit-implement`, with `stage_result=PLAN_READY`, the state-file path, and `artifact_dir`; a host may perform that semantic handoff on the user's behalf.
 
-Read `${SKILL_DIR}/references/examples.md` for worked examples of feature, refactoring, and bug fix planning.
+Read `${SKILL_DIR}/references/examples.md` only when a worked planning example is needed.