@tcanaud/playbook 1.0.0

package/templates/commands/playbook.resume.md

@@ -0,0 +1,143 @@
+# /playbook.resume — Resume Interrupted Playbook Session
+
+**Input**: None — this command takes no arguments. It auto-detects the active session.
+
+You are the **Playbook Supervisor** resuming an interrupted session. Your job is to find the last active session, determine where it left off, and continue execution from the correct step.
+
+## 1. Find Repository Root
+
+Run `git rev-parse --show-toplevel` to find the repository root. All paths are relative to this root.
+
+## 2. Scan for In-Progress Sessions
+
+Scan `.playbooks/sessions/*/session.yaml` for sessions with `status: "in_progress"`.
+
+Read each `session.yaml` and check the `status` field.
+
+**If no in-progress sessions found**:
+> No active playbook session found. Start a new one with `/playbook.run {playbook} {feature}`.
+
+Stop execution.
+
+**If multiple in-progress sessions found**:
+- Pick the most recent by session ID (the timestamp prefix `YYYYMMDD` sorts chronologically, then the 3-char suffix breaks ties alphabetically)
+- Report which session was selected
+
+**If exactly one found**: Use that session.
+
+## 3. Load Session Context
+
+From the selected `session.yaml`, extract:
+- `session_id` — the session identifier
+- `playbook` — the playbook name
+- `feature` — the feature branch name
+- `args` — the resolved arguments
+- `current_step` — the step that was in progress when interrupted
+
+Report:
+> Resuming session `{session_id}` — playbook `{playbook}`, feature `{feature}`
+
+## 4. Read the Playbook
+
+Read the playbook YAML from `.playbooks/playbooks/{playbook}.yaml`.
+
+If the playbook file no longer exists, report error and stop:
+> Playbook `{playbook}` not found. Cannot resume session `{session_id}`.
+
+Parse the playbook to get the full step list. Resolve argument interpolation using the session's `args`.
+
+## 5. Read the Journal
+
+Read `.playbooks/sessions/{session_id}/journal.yaml` to determine execution state.
+
+For each step in the playbook, check the journal:
+- **Step has journal entry with `status: "done"`**: Skip — already completed
+- **Step has journal entry with `status: "skipped"`**: Skip — was intentionally skipped
+- **Step has journal entry with `status: "failed"`**: This is where we stopped — evaluate what to do
+- **Step has journal entry with `status: "in_progress"`**: This step was interrupted — check postconditions
+- **Step has no journal entry**: This step hasn't been attempted yet
+
+## 6. Determine Resume Point
+
+### If the last step has `status: "in_progress"`:
+
+Check its **postconditions**:
+
+| Condition | Check |
+|-----------|-------|
+| `spec_exists` | File exists: `specs/{feature}/spec.md` |
+| `plan_exists` | File exists: `specs/{feature}/plan.md` |
+| `tasks_exists` | File exists: `specs/{feature}/tasks.md` |
+| `agreement_exists` | File exists: `.agreements/{feature}/agreement.yaml` |
+| `agreement_pass` | File `.agreements/{feature}/check-report.md` contains `verdict: PASS` |
+| `qa_plan_exists` | File exists: `.qa/{feature}/test-plan.md` OR `.qa/{feature}/_index.yaml` |
+| `qa_verdict_pass` | File `.qa/{feature}/verdict.yaml` contains `verdict: PASS` |
+| `pr_created` | Run `gh pr list --head "{feature}" --json number --jq 'length'` — result > 0 |
+
+**If ALL postconditions pass**: The step actually completed before the crash. Update its journal entry to `done`, compute duration, and advance to the next step.
+
+**If ANY postcondition fails**: The step did not complete. Re-run it from scratch.
+
+### If the last step has `status: "failed"`:
+
+Report the failure and ask the user:
+> Step `{step_id}` previously failed with error: "{error}". Retry this step? (yes/skip/abort)
+
+### If there's no in-progress or failed step:
+
+Find the first step with no journal entry. That's the resume point.
+
+## 7. Report Resume Status
+
+Display a summary before continuing:
+
+```
+Session: {session_id}
+Playbook: {playbook} ({description})
+Feature: {feature}
+
+Progress:
+  {step_id}: done (auto) — {duration}s
+  {step_id}: done (gate) — {duration}s
+  {step_id}: in_progress → resuming
+  {step_id}: pending
+  ...
+
+Resuming from step: {step_id}
+```
+
+## 8. Continue Execution
+
+Resume the orchestration loop using the exact same logic as `/playbook.run`:
+
+For each remaining step (from the resume point):
+
+1. **Check preconditions** — evaluate each condition
+2. **Evaluate autonomy level** — auto, gate_on_breaking, gate_always, skip
+3. **Delegate via Task subagent** — fresh context per step
+4. **Check postconditions** — verify artifacts exist
+5. **Handle escalation triggers** — promote auto to gate if trigger fires
+6. **Apply error policy** — stop, retry_once, gate
+7. **Write journal entry** — record step outcome with all audit fields
+8. **Advance** — move to next step
+
+Update `session.yaml` `current_step` before each step execution.
+
+## 9. Completion
+
+When all remaining steps are done (or session is failed/aborted):
+
+1. Update `session.yaml`:
+   - `status`: `completed` | `failed` | `aborted`
+   - `completed_at`: current ISO 8601 timestamp
+   - `current_step`: empty
+
+2. Report final summary with full journal overview.
+
+## Rules
+
+- **No arguments required**: Auto-detect everything from the filesystem
+- **No duplicate execution**: Never re-run a step that has `status: "done"` in the journal
+- **Postcondition-based recovery**: Use postcondition checks to determine if an interrupted step actually completed
+- **Same orchestration logic**: The execution loop is identical to `/playbook.run` — same conditions, same gates, same error policies
+- **Journal continuity**: New journal entries are appended — never overwrite existing entries (except updating in_progress → done for recovered steps)

package/templates/commands/playbook.run.md

@@ -0,0 +1,214 @@
+# /playbook.run — Playbook Supervisor
+
+**Input**: `$ARGUMENTS` — `{playbook} {feature}` (e.g., `auto-feature 012-playbook-supervisor`)
+
+You are the **Playbook Supervisor**. You orchestrate a sequence of workflow steps defined in a YAML playbook, delegating each step to a Task subagent with fresh context. You are NOT an executor — you are the orchestrator. You use the same slash commands as manual execution. No bypass, no shortcut.
+
+## 1. Parse Arguments
+
+Extract from `$ARGUMENTS`:
+- `PLAYBOOK` — first word (playbook name, e.g., `auto-feature`)
+- `FEATURE` — second word (feature branch name, e.g., `012-playbook-supervisor`)
+
+If either is missing, ask the user: "Usage: /playbook.run {playbook} {feature}"
+
+## 2. Read Playbook
+
+Read the playbook YAML from `.playbooks/playbooks/{PLAYBOOK}.yaml`.
+
+If the file does not exist, report error and stop:
+> Playbook `{PLAYBOOK}` not found at `.playbooks/playbooks/{PLAYBOOK}.yaml`
+
+Parse the playbook manually — extract:
+- `name`, `description`, `version`
+- `args[]` — declared arguments with names and required flags
+- `steps[]` — ordered list of step definitions
+
+Resolve argument interpolation: replace all `{{feature}}` references in step `args` with the actual `FEATURE` value. Do the same for any other declared args.
+
+Validate that all required args are provided. If a required arg is missing, ask the user.
+
+## 3. Session Management
+
+### Check for existing session
+
+Scan `.playbooks/sessions/*/session.yaml` for a session where:
+- `playbook` matches `PLAYBOOK`
+- `feature` matches `FEATURE`
+- `status` is `in_progress`
+
+**If found**: Resume that session (skip to step 5 with the existing session).
+
+### Create new session
+
+If no existing session found:
+
+1. Generate session ID: `{YYYYMMDD}-{3char}` (e.g., `20260219-a7k`) where 3char is random lowercase alphanumeric
+2. Create directory `.playbooks/sessions/{id}/`
+3. Write `session.yaml`:
+   ```yaml
+   session_id: "{id}"
+   playbook: "{PLAYBOOK}"
+   feature: "{FEATURE}"
+   args:
+     feature: "{FEATURE}"
+   status: "in_progress"
+   started_at: "{ISO 8601 now}"
+   completed_at: ""
+   current_step: ""
+   worktree: ""
+   ```
+4. Write `journal.yaml`:
+   ```yaml
+   entries: []
+   ```
+5. Report: `Session {id} created for playbook {PLAYBOOK}`
+
+## 4. Pre-flight Validation
+
+Before executing any steps, verify:
+- All slash commands referenced in steps exist (check `.claude/commands/` for the command files, or trust that they are available as skills)
+- Report any missing commands and stop
+
+## 5. Orchestration Loop
+
+For each step in the playbook (in order):
+
+### 5a. Check Preconditions
+
+For each condition in the step's `preconditions[]`, evaluate:
+
+| Condition | Check |
+|-----------|-------|
+| `spec_exists` | File exists: `specs/{FEATURE}/spec.md` |
+| `plan_exists` | File exists: `specs/{FEATURE}/plan.md` |
+| `tasks_exists` | File exists: `specs/{FEATURE}/tasks.md` |
+| `agreement_exists` | File exists: `.agreements/{FEATURE}/agreement.yaml` |
+| `agreement_pass` | File `.agreements/{FEATURE}/check-report.md` contains `verdict: PASS` |
+| `qa_plan_exists` | File exists: `.qa/{FEATURE}/test-plan.md` OR `.qa/{FEATURE}/_index.yaml` |
+| `qa_verdict_pass` | File `.qa/{FEATURE}/verdict.yaml` contains `verdict: PASS` |
+| `pr_created` | Run `gh pr list --head "{FEATURE}" --json number --jq 'length'` — result > 0 |
+
+If ANY precondition fails:
+- Report which precondition failed and what artifact is missing
+- **Do NOT proceed with this step** — halt and explain what needs to happen first
+- If a previous step should have produced this artifact, investigate why it didn't
+
+### 5b. Evaluate Autonomy Level
+
+| Autonomy | Behavior |
+|----------|----------|
+| `auto` | Execute without asking. Proceed directly to delegation. |
+| `gate_on_breaking` | Check if a breaking change is detected (for agreement checks). If breaking: halt and ask. If not: proceed like auto. |
+| `gate_always` | Always halt. Present context and ask before proceeding. |
+| `skip` | Do not execute. Log as skipped. Move to next step. |
+
+**Gate Protocol** (when halting):
+1. Present a clear summary: step name, command, what it will do
+2. Ask: "Proceed with step '{id}' ({command})? (yes/no/abort)"
+3. Wait for user response
+4. If "yes" or "continue": proceed with delegation
+5. If "no" or "skip": log as skipped, move to next step
+6. If "abort": mark session as aborted, stop execution
+
+### 5c. Delegate to Task Subagent
+
+Record the step start time.
+
+Update `session.yaml`: set `current_step` to the step ID.
+
+Use the **Task tool** to delegate the step:
+- Launch a subagent with `subagent_type: "general-purpose"`
+- The prompt MUST include:
+  - The slash command to execute (e.g., "Execute /speckit.plan")
+  - The arguments (with resolved interpolation)
+  - The feature context
+  - Instruction to use the Skill tool to invoke the slash command
+- Each subagent gets **fresh context** — no accumulated state from previous steps
+
+**Parallel phases**: If multiple steps share the same `parallel_group`, launch ALL of them in a single message using multiple Task tool calls. Wait for all to complete before continuing.
+
+### 5d. Check Postconditions
+
+After the subagent completes, evaluate each condition in `postconditions[]` using the same checks as preconditions (table in 5a).
+
+If ALL postconditions pass: mark step as **done**.
+
+If ANY postcondition fails: check escalation triggers.
+
+### 5e. Handle Escalation Triggers
+
+If a postcondition failed AND the step has escalation triggers:
+
+| Trigger | Fires When |
+|---------|-----------|
+| `postcondition_fail` | Any postcondition check fails |
+| `verdict_fail` | QA verdict file contains FAIL |
+| `agreement_breaking` | Agreement check found breaking changes |
+| `subagent_error` | The Task subagent returned an error |
+
+If a trigger fires on an `auto` step: **promote to gate**. Present the failure to the user and ask for a decision.
+
+### 5f. Apply Error Policy
+
+If the step failed (postcondition fail, subagent error):
+
+| Policy | Behavior |
+|--------|----------|
+| `stop` | Mark session as failed. Stop all execution. Report the failure. |
+| `retry_once` | Re-execute the step ONE time. If it fails again, apply `stop`. |
+| `gate` | Escalate to the user. Present the failure context. Ask: "Fix and continue, or abort?" |
+
+### 5g. Write Journal Entry
+
+After each step (whether done, failed, or skipped), append a journal entry to `journal.yaml`:
+
+```yaml
+  - step_id: "{id}"
+    status: "done"           # done | failed | skipped
+    decision: "auto"         # auto | gate | escalated | skipped
+    started_at: "{ISO 8601}"
+    completed_at: "{ISO 8601}"
+    duration_seconds: {N}
+    trigger: ""              # escalation trigger if any
+    human_response: ""       # user's response at gate if any
+    error: ""                # error message if failed
+```
+
+Only include `trigger`, `human_response`, and `error` fields when they have values.
+
+### 5h. Advance to Next Step
+
+Move to the next step in the playbook and repeat from 5a.
+
+## 6. Completion
+
+When all steps are done (or the session is failed/aborted):
+
+1. Update `session.yaml`:
+   - `status`: `completed` (all done) | `failed` (step failed with stop) | `aborted` (user aborted)
+   - `completed_at`: current ISO 8601 timestamp
+   - `current_step`: empty
+
+2. Report final summary:
+   ```
+   Playbook {PLAYBOOK} — {status}
+
+   Steps: {done}/{total}
+   Duration: {total duration}
+
+   Journal: .playbooks/sessions/{id}/journal.yaml
+
+   Step results:
+     {step_id}: {status} ({decision}) — {duration}s
+     ...
+   ```
+
+## Rules
+
+- **Same commands as manual**: You execute the same slash commands a developer would type manually. No bypass.
+- **Fresh context per step**: Each Task subagent starts clean. No state leaks between steps.
+- **Journal is the truth**: Every decision, every gate response, every error is recorded in the journal.
+- **Deterministic behavior**: Autonomy levels, conditions, error policies are a fixed vocabulary. Follow them exactly.
+- **No invention**: Do not add steps, skip conditions, or modify the playbook at runtime.
+- **Idempotent resume**: If this command is re-run with the same playbook and feature, it finds the existing session and resumes.

package/templates/core/_index.yaml

@@ -0,0 +1,15 @@
+# Playbook Index
+# Auto-generated by @tcanaud/playbook init/update
+# Lists all available playbooks in this project.
+
+generated: "{{TIMESTAMP}}"
+
+playbooks:
+  - name: "auto-feature"
+    file: "playbooks/auto-feature.yaml"
+    description: "Full feature workflow from plan to PR"
+    steps: 8
+  - name: "auto-validate"
+    file: "playbooks/auto-validate.yaml"
+    description: "QA validation: plan and run"
+    steps: 2

package/templates/core/playbook.tpl.yaml

@@ -0,0 +1,88 @@
+# Playbook Template
+# Copy this file and customize it for your workflow.
+# Validate with: npx @tcanaud/playbook check <file>
+#
+# ── Schema Reference ────────────────────────────────────
+#
+# Top-level fields (all required):
+#   name:        Unique identifier [a-z0-9-]+
+#   description: Human-readable purpose
+#   version:     Schema version (e.g., "1.0")
+#
+# args (required, may be empty array):
+#   - name:        Argument name, referenced as {{name}} in step args
+#     description: Purpose of the argument
+#     required:    true | false
+#
+# steps (required, min 1):
+#   - id:                  Unique within playbook [a-z0-9-]+
+#     command:             Slash command to execute (e.g., "/speckit.plan")
+#     args:                Optional — supports {{arg}} interpolation
+#     autonomy:            Decision mode (see below)
+#     preconditions:       Optional list of artifact checks (see below)
+#     postconditions:      Optional list of artifact checks (see below)
+#     error_policy:        Behavior on failure (see below)
+#     escalation_triggers: Optional list of triggers (see below)
+#     parallel_group:      Optional — steps with same group run concurrently
+#
+# ── Autonomy Levels ─────────────────────────────────────
+#   auto             Execute without human interaction
+#   gate_on_breaking Gate only when a breaking change is detected
+#   gate_always      Always halt for human decision
+#   skip             Skip execution, log as skipped
+#
+# ── Error Policies ──────────────────────────────────────
+#   stop             Halt all execution, mark session as failed
+#   retry_once       Re-execute once; if still fails, stop
+#   gate             Escalate to human decision with failure context
+#
+# ── Escalation Triggers ────────────────────────────────
+#   postcondition_fail   Any postcondition fails after step execution
+#   verdict_fail         QA verdict file contains FAIL
+#   agreement_breaking   Agreement check detects breaking changes
+#   subagent_error       Task subagent returns error or crashes
+#
+# ── Conditions (Pre/Post) ──────────────────────────────
+#   spec_exists       specs/{feature}/spec.md exists
+#   plan_exists       specs/{feature}/plan.md exists
+#   tasks_exists      specs/{feature}/tasks.md exists
+#   agreement_exists  .agreements/{feature}/agreement.yaml exists
+#   agreement_pass    .agreements/{feature}/check-report.md verdict: PASS
+#   qa_plan_exists    .qa/{feature}/test-plan.md exists
+#   qa_verdict_pass   .qa/{feature}/verdict.md verdict: PASS
+#   pr_created        gh pr list --head {branch} returns non-empty
+#
+# ════════════════════════════════════════════════════════
+
+name: "my-workflow"
+description: "Describe your workflow here"
+version: "1.0"
+
+args:
+  - name: "feature"
+    description: "Feature branch name"
+    required: true
+
+steps:
+  - id: "step-1"
+    command: "/speckit.plan"
+    args: ""
+    autonomy: "auto"
+    preconditions:
+      - "spec_exists"
+    postconditions:
+      - "plan_exists"
+    error_policy: "stop"
+    escalation_triggers: []
+
+  # Add more steps below following the same structure.
+  # Use parallel_group to run steps concurrently:
+  #
+  # - id: "step-a"
+  #   command: "/some.command"
+  #   parallel_group: "phase-2"
+  #   ...
+  # - id: "step-b"
+  #   command: "/other.command"
+  #   parallel_group: "phase-2"
+  #   ...

package/templates/playbooks/auto-feature.yaml

@@ -0,0 +1,100 @@
+name: "auto-feature"
+description: "Full feature workflow from plan to PR"
+version: "1.0"
+
+args:
+  - name: "feature"
+    description: "Feature branch name (e.g., 012-playbook-supervisor)"
+    required: true
+
+steps:
+  - id: "plan"
+    command: "/speckit.plan"
+    args: ""
+    autonomy: "auto"
+    preconditions:
+      - "spec_exists"
+    postconditions:
+      - "plan_exists"
+    error_policy: "stop"
+    escalation_triggers: []
+
+  - id: "tasks"
+    command: "/speckit.tasks"
+    args: ""
+    autonomy: "auto"
+    preconditions:
+      - "plan_exists"
+    postconditions:
+      - "tasks_exists"
+    error_policy: "stop"
+    escalation_triggers: []
+
+  - id: "agreement"
+    command: "/agreement.create"
+    args: "{{feature}}"
+    autonomy: "auto"
+    preconditions:
+      - "tasks_exists"
+    postconditions:
+      - "agreement_exists"
+    error_policy: "gate"
+    escalation_triggers:
+      - "subagent_error"
+
+  - id: "implement"
+    command: "/speckit.implement"
+    args: ""
+    autonomy: "auto"
+    preconditions:
+      - "agreement_exists"
+    postconditions: []
+    error_policy: "retry_once"
+    escalation_triggers:
+      - "postcondition_fail"
+      - "subagent_error"
+
+  - id: "agreement-check"
+    command: "/agreement.check"
+    args: "{{feature}}"
+    autonomy: "gate_on_breaking"
+    preconditions: []
+    postconditions:
+      - "agreement_pass"
+    error_policy: "gate"
+    escalation_triggers:
+      - "agreement_breaking"
+
+  - id: "qa-plan"
+    command: "/qa.plan"
+    args: "{{feature}}"
+    autonomy: "auto"
+    preconditions:
+      - "agreement_pass"
+    postconditions:
+      - "qa_plan_exists"
+    error_policy: "stop"
+    escalation_triggers: []
+
+  - id: "qa-run"
+    command: "/qa.run"
+    args: "{{feature}}"
+    autonomy: "auto"
+    preconditions:
+      - "qa_plan_exists"
+    postconditions:
+      - "qa_verdict_pass"
+    error_policy: "gate"
+    escalation_triggers:
+      - "verdict_fail"
+
+  - id: "pr"
+    command: "/feature.pr"
+    args: "{{feature}}"
+    autonomy: "gate_always"
+    preconditions:
+      - "qa_verdict_pass"
+    postconditions:
+      - "pr_created"
+    error_policy: "stop"
+    escalation_triggers: []

package/templates/playbooks/auto-validate.yaml

@@ -0,0 +1,31 @@
+name: "auto-validate"
+description: "QA validation: plan and run"
+version: "1.0"
+
+args:
+  - name: "feature"
+    description: "Feature branch name (e.g., 012-playbook-supervisor)"
+    required: true
+
+steps:
+  - id: "qa-plan"
+    command: "/qa.plan"
+    args: "{{feature}}"
+    autonomy: "auto"
+    preconditions:
+      - "spec_exists"
+    postconditions:
+      - "qa_plan_exists"
+    error_policy: "stop"
+    escalation_triggers: []
+
+  - id: "qa-run"
+    command: "/qa.run"
+    args: "{{feature}}"
+    autonomy: "auto"
+    preconditions:
+      - "qa_plan_exists"
+    postconditions:
+      - "qa_verdict_pass"
+    error_policy: "stop"
+    escalation_triggers: []