@jterrats/open-orchestra 0.5.4 → 0.5.5

package/docs/autonomous-workflow.md

@@ -35,7 +35,7 @@ When a gate is reached, the run writes a review artifact to `.agent-workflow/app
 
 ## Provider-Backed Phase Execution
 
-By default, workflow phases remain deterministic because the default provider is `none`. When a role or default provider route is configured to a non-`none` provider, each phase builds a prompt from task context, rendered skills, and prior handoff content, then writes the provider output to `.agent-workflow/runs/<task>/<phase>/`.
+By default, workflow phases remain deterministic because the default provider is `none`. When a role or default provider route is configured to a non-`none` provider, each phase builds a prompt from task context, rendered skills, the active phase playbook, and prior handoff content, then writes the provider output to `.agent-workflow/runs/<task>/<phase>/`.
 
 ```bash
 orchestra model set-role --role architect --provider fake --model fake-model
@@ -45,6 +45,39 @@ orchestra model provenance list --task FEAT-001 --json
 
 Provider execution records `MODEL_PROVENANCE_RECORDED` events. The benchmark layer uses those events to report token and cost signals.
 
+## Phase Playbooks
+
+`orchestra init` creates editable phase playbooks in `.agent-workflow/playbooks/`:
+
+```text
+.agent-workflow/playbooks/
+  pm.md
+  po.md
+  architect.md
+  developer.md
+  qa.md
+  release.md
+```
+
+Use playbooks for phase-specific guidance that should not live in always-loaded runtime instructions. Examples: QA evidence expectations, release go/no-go criteria, architecture decision format, or developer handoff requirements.
+
+Playbooks are provider-agnostic. They are loaded into provider-backed phase prompts, `workflow render --phase <phase>`, runtime briefs, and runtime delegation packets. Only the active phase playbook is loaded.
+
+Configuration is convention-over-config by default, with optional overrides:
+
+```json
+{
+  "workflow": {
+    "playbooksDir": ".agent-workflow/playbooks",
+    "phasePlaybooks": {
+      "developer": "custom-developer.md"
+    }
+  }
+}
+```
+
+If a playbook file is missing, Orchestra uses deterministic fallback guidance and surfaces a warning in rendered content.
+
 ## Architect Sizing Gate
 
 Regardless of `--gates` mode, the architect phase always requires a sizing decision before the developer phase starts. In provider-backed mode the architect phase can record that decision automatically; otherwise, if no sizing decision is found, the run stops with the exact command to resolve it:
@@ -77,6 +110,15 @@ orchestra workflow run --task FEAT-001 --gates phase
 # Resume a paused run after approving a gate
 orchestra workflow run --task FEAT-001 --resume <run-id>
 
+# Start a fresh run from an already-claimed phase
+orchestra workflow run --task FEAT-001 --from-phase developer
+
+# Resume an existing run from an explicit phase when automatic resume needs an override
+orchestra workflow run --task FEAT-001 --resume <run-id> --from-phase qa
+
+# Render a runtime brief with the active phase playbook
+orchestra workflow render --task FEAT-001 --phase developer
+
 # Cap the number of QA→developer retry iterations (default: 5)
 orchestra workflow run --task FEAT-001 --gates none --max-iterations 3
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "type": "module",
   "workspaces": [
     "site"