@astrosheep/keiyaku 2.9.0 → 2.9.2

package/skills/keiyaku-workflow/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: keiyaku-workflow
+description: Use when driving a Keiyaku contract — bind to start isolated work, arc/renew mid-flight, petition for review, claim or forfeit to finish.
+allowed-tools: Bash(keiyaku *)
+---
+
+# Keiyaku Workflow
+
+How a contract lives. Running akuma is the `keiyaku-akuma` skill; task planning is `keiyaku-task`.
+
+## Mind model
+
+A contract = one branch + one worktree + a ledger (its record file in the repo). You work inside the worktree however you like; keiyaku only judges the result at petition. States:
+
+```
+bound → active → petitioned → claimed | forfeited
+```
+
+## The default flow
+
+```bash
+keiyaku bind --place fix-pump --objective "make the pump test pass" \
+             --scope "src/pump/**" --checks "pump tests green"
+# or the same four fields as Markdown: keiyaku bind < contract.md
+#   (# <name> / ## Objective / ## Scope / ## Checks)
+# or promote a ready task:            keiyaku bind --task k-xxxx
+
+cd .keiyaku/wt/fix-pump          # worktree lives at .keiyaku/wt/<place>; commit normally
+
+keiyaku petition <<'EOF'
+## Oath
+I made the pump test pass; ran the suite, all green.
+EOF
+# petition seals your work and runs the settlement pipeline itself —
+# passes → claimed (merged to main); a gate fails → fix, petition again.
+# The oath is required (OATH_MISSING otherwise) and checked for presence, not content.
+```
+
+That's the whole small case: bind → commit → petition.
+
+## Mid-flight commands (use when needed, skip otherwise)
+
+```bash
+keiyaku arc < arc.md         # optional iteration boundary: seals the current intent, opens
+                             #   the next. Markdown: # <title> / ## Objective / ## Brief.
+                             #   Only needed when one contract has multiple distinct pushes.
+keiyaku renew                # main moved under you → rebase onto it. Refuses on conflict
+                             #   instead of guessing; resolve, then renew again.
+keiyaku amend < amendment.md # scope/checks changed → update the paper before the code
+keiyaku log                  # this contract's history
+```
+
+Gotchas:
+- Base drift blocks petition — if main moved, `renew` first; petition tells you.
+- After an explicit `arc` seals, new loose commits need another `arc` before `renew`/`petition` accept them.
+- Not in the worktree? Address a contract with `--contract ADDR` (place, slug, or full id) or the `keiyaku @addr <verb>` prefix.
+
+## Ending it
+
+```bash
+keiyaku forfeit --reason "superseded by fix-pump-v2"
+# abandon: worktree destroyed, history kept. Manual only — nothing auto-forfeits.
+```
+
+There is no `claim` command: claiming is the tail of a passing petition.
+
+## Reading status
+
+```bash
+keiyaku status               # every contract row: state, place, what to do next
+```