Handbook
Prompt-pack Element protocol
Dual-wiki: operator · system.
Updated
Laptop-only workcell prompt_pack_worker: share a zip of markdown prompts in the Element #cursor-plain room, approve execution on this machine, then optionally run an allowlisted deploy plan.
Executive capsule
Operator drops a freeform prompt zip. The bridge validates and registers the pack, pins Grok 4.7 (grok-4.7-high), runs Cursor after approve, applies a completion scan on pack evidence (decision, acceptance, checkpoint, deploy plan), may post CONTINUE for up to three turns, then posts IMPLEMENTED or FAILED, always followed by AUDIT. Deploy commands run only after a separate deploy reply.
This is not !agent task (Granite Roadrunner). General !agent new Agent mode remains approval-gated; only this workcell may spawn write-capable Cursor on the laptop.
Progress card
While a long pack step runs (implement, test, catchup, deploy, and similar), the bridge posts one in-thread message and edits it in place (m.replace). The card shows workcell id, phase, percent complete, ETA (after the first completed step), and a short label (for example the current pytest suite id). Final protocol messages (AUDIT, IMPLEMENTED, TEST, and so on) are unchanged and still arrive as separate events after the card reaches 100%.
Command grammar
- Upload a
.zipwith caption!agent pack, or upload then send!agent packwithin the media TTL. - Thread
ACK: pack id, digest, file list; replyapproveorreject <reason>. - After
approve:APPROVED→IMPLEMENTING→ Cursor (up to 3 turns). - If mandatory gates remain:
CONTINUElists unfinished ids and resumes on the laptop (same pack id). - When the completion scan passes:
IMPLEMENTED(summary + deploy plan). After 3 turns without pass:FAILED. AUDITfollowsIMPLEMENTEDorFAILED(deterministic collector + optional narrative); not a deploy. Replyauditin the pack thread to refresh. Run dir getsaudit-report.mdandremediation/(zip and!agent packfor follow-on scope).- Reply
deployto run allowlisted commands from the frozen snapshot →SUMMARY. - After implementation, these replies stay on the same pack and do not restart services:
testplantags each matrix row asacceptanceand groups scenarios into suites by component. It writestest-plan.jsonand does not run pytest.- After
testplanoraudit, the reply lists up to three next steps from files already on disk. Reply1(oryes) to run the recommended step. Element has no command buttons in this room. acceptanceruns only the rows taggedacceptance.testruns the suite groups. When the plan is large (4 or more suites, more than one pytest file, or 8 or more dirtyforge-marketpaths), each suite runs separately.dual-wikichecks thatsummary.mdnames the same decision aspromotion_decision.json, and that every zip acceptance id has a status row.fixstarts Cursor on the last test log. It does not commit.catchupstarts Cursor on the audit unfinished list andremediation/00_REMEDIATION_MASTER.md. It does not markNOT_RUNas pass.commitputs dirtyforge-market,forge-agents, andforge-squidtrees onfeature/prompt-pack-<id>withtype(scope): summary. It skips.env, keys, and databases. It does not pushmain.pushrunsgit push -u origin HEAD. On a non-fast-forward rejection it mergesorigin/<branch>and, for content conflicts, keeps this branch, completes the merge, and pushes again. A failed resolve aborts the merge so the tree is not left conflicted.
IMPLEMENTED means the completion scan passed (not merely that summary.md exists). AUDIT is an independent report; it does not restart Market Studio — use deploy for allowlisted systemctl restarts.
Governance
| Rule | Behavior |
|---|---|
| Model | grok-4.7-high only; fails closed if not in cursor-agent models |
| Zip | ≤20 MB, ≤200 files, .md / .txt only, no traversal or symlinks |
| Queue | One active pack until DONE, FAILED, or REJECTED |
| Deploy | Allowlisted scripts under Code / ~/forge-fleet; no ssh, &&, force-push, --no-verify |
| Completion | Scan promotion_decision.json, acceptance_status.json, CHECKPOINT.json, deploy plan (forge-market runtime changes require systemctl --user restart forge-market-studio.service in the plan) |
| Turns | Max 3 implement turns; then FAILED with unfinished list |
Runtime
- Bridge:
forge-cursor-bridge matrix-adapter(local transport) on the operator laptop - Data:
~/.local/share/forge-prompt-pack/<pack_id>/ - Ledger:
prompt-packs.dbbeside the bridge SQLite store
Related
- Repo-task Element protocol — Granite repo tasks
- Studio UX Element protocol — UX PDCA lane