@cleocode/playbooks 2026.4.92 → 2026.4.93

package/starter/ivtr.cantbook

@@ -0,0 +1,97 @@
+version: "1.0"
+name: ivtr
+description: >
+  IVTR execution loop — Implement, Validate, Test. Each stage is a distinct
+  agentic node wired in declaration order; failures retry in place up to
+  `max_iterations`, mimicking the classic build-lint-test cycle. The runtime
+  keeps per-node iteration counters so the total retry budget across the three
+  nodes is bounded by the sum of each node's cap (see T930 runtime semantics).
+
+inputs:
+  - name: taskId
+    required: true
+    description: Task id being executed (e.g. T934).
+  - name: maxAttempts
+    required: false
+    default: 3
+    description: >
+      Documentation-only hint — the runtime uses per-node max_iterations.
+
+nodes:
+  - id: implement
+    type: agentic
+    skill: ct-task-executor
+    role: worker
+    description: >
+      Implement {{inputs.taskId}} against its spec and acceptance criteria.
+      On failure, retries in place with the last error injected into context
+      (__lastError / __lastFailedNode). Cap: 3 attempts.
+    inputs:
+      taskId: "{{inputs.taskId}}"
+    ensures:
+      schema: implementation_diff
+    on_failure:
+      max_iterations: 3
+      escalate: false
+
+  - id: validate
+    type: agentic
+    skill: ct-validator
+    role: worker
+    description: >
+      Validate the implementation against the task spec — static checks,
+      schema compliance, and contract invariants. Retries in place on
+      failure; a sustained failure escalates back to implement via
+      `inject_into` so the worker can incorporate the validator's feedback.
+    requires:
+      from: implement
+      fields:
+        - diff
+    ensures:
+      schema: validation_report
+    on_failure:
+      max_iterations: 2
+      inject_into: implement
+
+  - id: test
+    type: agentic
+    skill: ct-task-executor
+    role: worker
+    description: >
+      Run the task's test suite and verify every acceptance criterion passes.
+      On failure, bounces back to implement with the failing test names in
+      context so the worker can address root cause rather than re-running.
+      Terminal stage of the IVTR loop.
+    requires:
+      from: validate
+      fields:
+        - passed
+    ensures:
+      schema: test_report
+    on_failure:
+      max_iterations: 2
+      inject_into: implement
+
+edges:
+  - from: implement
+    to: validate
+    contract:
+      requires:
+        - diff
+      ensures:
+        - passed
+  - from: validate
+    to: test
+    contract:
+      requires:
+        - passed
+      ensures:
+        - testsPassed
+
+error_handlers:
+  - on: iteration_cap_exceeded
+    action: hitl_escalate
+    message: "IVTR loop exhausted — implementation, validation, or tests keep failing."
+  - on: contract_violation
+    action: inject_hint
+    message: "Contract violated at stage boundary — check requires/ensures fields."

package/starter/rcasd.cantbook

@@ -0,0 +1,142 @@
+version: "1.0"
+name: rcasd
+description: >
+  RCASD planning pipeline — Research, Consensus, Architecture, Specification,
+  Decomposition. Linear five-stage agent chain that produces a fully-decomposed
+  epic ready for IVTR execution. Every stage merges its structured output into
+  the run context via the playbook runtime state machine (see T930).
+
+inputs:
+  - name: epicId
+    required: true
+    description: Parent epic id being planned (e.g. T999).
+  - name: scope
+    required: false
+    default: global
+    description: Planning scope (global|team|project).
+
+nodes:
+  - id: research
+    type: agentic
+    skill: ct-research-agent
+    role: lead
+    description: >
+      Gather context for {{inputs.epicId}} — prior art, patterns, alternatives,
+      and unknowns. Emits a structured research summary into the run context.
+    inputs:
+      topic: "{{inputs.epicId}}"
+      scope: "{{inputs.scope}}"
+    ensures:
+      schema: research_summary
+    on_failure:
+      max_iterations: 2
+      escalate: true
+
+  - id: consensus
+    type: agentic
+    skill: ct-validator
+    agent: consensus-lead
+    role: lead
+    description: >
+      Review research findings, validate approach, surface risks, and obtain
+      HITL alignment on direction before committing to architecture.
+    requires:
+      from: research
+      fields:
+        - summary
+        - risks
+    ensures:
+      schema: consensus_decision
+    on_failure:
+      max_iterations: 2
+
+  - id: architecture
+    type: agentic
+    skill: ct-spec-writer
+    agent: architecture-lead
+    role: lead
+    description: >
+      Choose concrete patterns, integration points, and data flows. Capture
+      decisions as ADR stubs referenced by the specification stage.
+    requires:
+      from: consensus
+      fields:
+        - decision
+    ensures:
+      schema: architecture_plan
+    on_failure:
+      max_iterations: 2
+
+  - id: specification
+    type: agentic
+    skill: ct-spec-writer
+    role: lead
+    description: >
+      Write a formal specification using RFC 2119 language, acceptance
+      criteria, contract invariants, and failure modes for {{inputs.epicId}}.
+    requires:
+      from: architecture
+      fields:
+        - patterns
+        - adrs
+    ensures:
+      schema: specification_document
+    on_failure:
+      max_iterations: 2
+
+  - id: decomposition
+    type: agentic
+    skill: ct-epic-architect
+    role: lead
+    description: >
+      Break {{inputs.epicId}} into atomic child tasks with dependencies,
+      acceptance gates, and size estimates (small|medium|large). Terminal
+      stage of the RCASD pipeline.
+    requires:
+      from: specification
+      fields:
+        - acceptance
+        - requirements
+    ensures:
+      schema: task_tree
+    on_failure:
+      max_iterations: 2
+      escalate: true
+
+edges:
+  - from: research
+    to: consensus
+    contract:
+      requires:
+        - summary
+      ensures:
+        - decision
+  - from: consensus
+    to: architecture
+    contract:
+      requires:
+        - decision
+      ensures:
+        - patterns
+  - from: architecture
+    to: specification
+    contract:
+      requires:
+        - patterns
+      ensures:
+        - acceptance
+  - from: specification
+    to: decomposition
+    contract:
+      requires:
+        - acceptance
+      ensures:
+        - children
+
+error_handlers:
+  - on: iteration_cap_exceeded
+    action: hitl_escalate
+    message: "RCASD stage exhausted retries — escalate to human for direction."
+  - on: agentic_timeout
+    action: inject_hint
+    message: "Narrow scope and retry."

package/starter/release.cantbook

@@ -0,0 +1,99 @@
+version: "1.0"
+name: release
+description: >
+  Release pipeline — bump version, update the changelog, pause at a HITL
+  approval gate, then publish. The approval node uses the `conservative`
+  policy so the runtime always requires human sign-off (it returns
+  `terminalStatus=pending_approval` with a signed HMAC resume token per
+  approval.ts).
+
+inputs:
+  - name: targetVersion
+    required: true
+    description: Target semver or CalVer to publish (e.g. 2026.4.92).
+  - name: channel
+    required: false
+    default: latest
+    description: npm dist-tag (latest|next|canary).
+
+nodes:
+  - id: version_bump
+    type: agentic
+    skill: ct-dev-workflow
+    agent: release-lead
+    role: lead
+    description: >
+      Bump package.json versions to {{inputs.targetVersion}} across the
+      monorepo (pnpm run version:bump or equivalent orchestrator call).
+    inputs:
+      targetVersion: "{{inputs.targetVersion}}"
+    ensures:
+      schema: version_bump_report
+    on_failure:
+      max_iterations: 2
+
+  - id: changelog
+    type: agentic
+    skill: ct-documentor
+    agent: release-lead
+    role: lead
+    description: >
+      Update CHANGELOG.md with an entry for {{inputs.targetVersion}}, summarize
+      the commits since the last tag, and categorize (feat/fix/chore/docs).
+    requires:
+      from: version_bump
+      fields:
+        - versionBumped
+    ensures:
+      schema: changelog_entry
+    on_failure:
+      max_iterations: 2
+
+  - id: approval
+    type: approval
+    policy: conservative
+    prompt: >
+      Approve release of {{inputs.targetVersion}} to {{inputs.channel}}?
+      Review the changelog entry and version bump before clicking approve.
+    description: >
+      HITL gate — runtime pauses here and returns a signed HMAC resume token.
+      A human (or automated owner) must call approveGate() / rejectGate() and
+      then resumePlaybook() to continue past this node.
+
+  - id: publish
+    type: agentic
+    skill: ct-dev-workflow
+    agent: release-lead
+    role: lead
+    description: >
+      Publish to npm (pnpm run release:publish --tag {{inputs.channel}}).
+      Terminal node — completes the release pipeline.
+    ensures:
+      schema: publish_report
+    on_failure:
+      max_iterations: 1
+      escalate: true
+
+edges:
+  - from: version_bump
+    to: changelog
+    contract:
+      requires:
+        - versionBumped
+      ensures:
+        - changelogUpdated
+  - from: changelog
+    to: approval
+  - from: approval
+    to: publish
+    contract:
+      ensures:
+        - published
+
+error_handlers:
+  - on: iteration_cap_exceeded
+    action: hitl_escalate
+    message: "Release stage exhausted retries — stop and investigate before retrying."
+  - on: contract_violation
+    action: abort
+    message: "Release contract violated — halt to avoid publishing a broken artifact."