diff --git a/docs/concepts/convoy.md b/docs/concepts/convoy.md index f096e71f..63c45aae 100644 --- a/docs/concepts/convoy.md +++ b/docs/concepts/convoy.md @@ -51,6 +51,7 @@ so you can see when it lands and what was included. |---------|-------------|-----|-------------| | **Convoy** | Yes | hq-cv-* | Tracking unit. What you create, track, get notified about. | | **Swarm** | No | None | Ephemeral. "The workers currently on this convoy's issues." | +| **Stranded Convoy** | Yes | hq-cv-* | A convoy with ready work but no polecats assigned. Needs attention. | When you "kick off a swarm", you're really: 1. Creating a convoy (the tracking unit) diff --git a/docs/concepts/molecules.md b/docs/concepts/molecules.md index 9f0fb198..8962b628 100644 --- a/docs/concepts/molecules.md +++ b/docs/concepts/molecules.md @@ -25,6 +25,7 @@ Protomolecule (frozen template) ─── Solid | **Molecule** | Active workflow instance with trackable steps | | **Wisp** | Ephemeral molecule for patrol cycles (never synced) | | **Digest** | Squashed summary of completed molecule | +| **Shiny Workflow** | Canonical polecat formula: design → implement → review → test → submit | ## Common Mistake: Reading Formulas Directly diff --git a/docs/reference.md b/docs/reference.md index bbe0f8dd..d9c6b676 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -545,6 +545,24 @@ gt stop --all # Kill all sessions gt stop --rig # Kill rig sessions ``` +### Health Check + +```bash +gt deacon health-check # Send health check ping, track response +gt deacon health-state # Show health check state for all agents +``` + +### Merge Queue (MQ) + +```bash +gt mq list [rig] # Show the merge queue +gt mq next [rig] # Show highest-priority merge request +gt mq submit # Submit current branch to merge queue +gt mq status # Show detailed merge request status +gt mq retry # Retry a failed merge request +gt mq reject # Reject a merge request +``` + ## Beads Commands (bd) ```bash diff --git a/internal/templates/roles/deacon.md.tmpl b/internal/templates/roles/deacon.md.tmpl index 12c98534..438f741c 100644 --- a/internal/templates/roles/deacon.md.tmpl +++ b/internal/templates/roles/deacon.md.tmpl @@ -152,7 +152,7 @@ gt mail inbox gt mol attach-from-mail # Step 3: Still nothing? Create patrol wisp (two-step: create then hook) -bd mol wisp create mol-deacon-patrol +bd mol wisp mol-deacon-patrol bd update --status=hooked --assignee=deacon ``` @@ -238,8 +238,8 @@ Then squash and decide: bd mol squash --summary="Patrol complete: checked inbox, scanned health, no issues" # Option A: Loop (low context) -bd mol wisp create mol-deacon-patrol -bd update --status=pinned --assignee=deacon +bd mol wisp mol-deacon-patrol +bd update --status=hooked --assignee=deacon # Continue to first step... # Option B: Exit (high context) diff --git a/internal/templates/roles/refinery.md.tmpl b/internal/templates/roles/refinery.md.tmpl index 4e19dde3..caa9815d 100644 --- a/internal/templates/roles/refinery.md.tmpl +++ b/internal/templates/roles/refinery.md.tmpl @@ -80,6 +80,14 @@ queue for your rig, merging polecat work to main one at a time with sequential r **The Scotty Test**: Before proceeding past any failure, ask yourself: "Would Scotty walk past a warp core leak because it existed before his shift?" +## Working Directory + +**IMPORTANT**: Always work from `{{ .WorkDir }}` directory. + +Identity detection (for mail, mol status, etc.) depends on your current working +directory. The refinery operates on the main branch worktree, so all commands work +from this directory. + ## 🔧 ZFC Compliance: Agent-Driven Decisions **You are the decision maker.** All merge/conflict decisions are made by you, the agent, @@ -153,8 +161,9 @@ Then check your hook: gt hook # Shows hooked work (if any) bd list --status=in_progress --assignee=refinery -# Step 2: If no patrol, spawn one -bd mol spawn mol-refinery-patrol --wisp --assignee=refinery +# Step 2: If no patrol, spawn one (two-step: create then hook) +bd mol wisp mol-refinery-patrol +bd update --status=hooked --assignee={{ .RigName }}/refinery ``` **No thinking. No "should I?" questions. Hook → Execute.** @@ -290,7 +299,8 @@ Then squash and decide: bd mol squash --summary="Patrol: merged 3 branches, no issues" # Option A: Loop (low context, more branches) -bd mol spawn mol-refinery-patrol --wisp --assignee=refinery +bd mol wisp mol-refinery-patrol +bd update --status=hooked --assignee={{ .RigName }}/refinery # Continue to inbox-check... # Option B: Exit (high context OR queue empty) @@ -335,7 +345,8 @@ gt mail send {{ .RigName }}/ -s "Rebase needed" \ ### Patrol - `gt hook` - Check for hooked patrol -- `bd mol spawn --wisp` - Spawn patrol wisp +- `bd mol wisp ` - Create patrol wisp +- `bd update --status=hooked --assignee=...` - Hook the wisp - `bd mol squash --summary="..."` - Squash completed patrol ### Git Operations diff --git a/internal/templates/roles/witness.md.tmpl b/internal/templates/roles/witness.md.tmpl index 8351c156..bbb370b6 100644 --- a/internal/templates/roles/witness.md.tmpl +++ b/internal/templates/roles/witness.md.tmpl @@ -111,6 +111,14 @@ Your job: - Close issues for work you didn't do - Skip mol steps or hallucinate completion +## Working Directory + +**IMPORTANT**: Always work from `{{ .WorkDir }}` directory. + +Identity detection (for mail, mol status, etc.) depends on your current working +directory. The witness monitors polecats in this rig, so all commands work +from this directory. + ## Tools Overview ### Polecat Inspection @@ -151,9 +159,9 @@ bd list --status=in_progress # Active work in rig --- -## 🚀 PROPULSION: The Universal Law +## Startup Protocol: Propulsion -> **If you find something on your hook, YOU RUN IT.** +> **The Universal Gas Town Propulsion Principle: If you find something on your hook, YOU RUN IT.** There is no decision logic. No "should I?" questions. Check your hook, execute: @@ -170,7 +178,7 @@ gt mail inbox gt mol attach-from-mail # Step 4: Still nothing? Create patrol wisp -bd mol wisp create mol-witness-patrol +bd mol wisp mol-witness-patrol bd update --status=hooked --assignee={{ .RigName }}/witness ```