@astrosheep/keiyaku 0.1.79 → 0.1.81

package/README.md

@@ -1,6 +1,6 @@
 # Keiyaku
 
-MCP server. AI code changes run on an isolated branch. Tasks are written into the repo. Nothing closes without your sign-off.
+CLI for contract-style coding work in git repositories. AI code changes run on an isolated branch. Tasks are written into the repo. Nothing closes without your sign-off.
 
 ```bash
 npm install -g @astrosheep/keiyaku
@@ -13,62 +13,49 @@ npm install -g @astrosheep/keiyaku
 Missing any of these? Don't come crying.
 
 - **Git repo.** Clean worktree. Dirty = refused.
-- **MCP client.** Claude Desktop, Claude Code, anything stdio.
-- **Subagent CLI.** [`claude`](https://docs.anthropic.com/en/docs/claude-code), [`gemini`](https://github.com/google-gemini/gemini-cli), or [`codex`](https://github.com/openai/codex). Installed. Logged in. Keiyaku doesn't run code itself — it delegates everything to a subprocess. No CLI = nothing happens.
-
-  **Codex users, one extra step.** Codex clears env before spawning MCP servers. Add this to your `~/.codex/config.toml` or keiyaku won't know when it's running as a subagent:
-
-  ```toml
-  [mcp_servers.keiyaku]
-  # ... rest of your config ...
-  env_vars = ["KEIYAKU_DISABLE_SUBAGENT_SPAWN"]
-  ```
+- **Supported providers.** `codex-cli`, `codex-sdk`, `claude-agent-sdk`, `gemini-cli-core`, `opencode-sdk`. CLI-backed providers need their matching executable (`codex`, `gemini`, `opencode`). `claude-agent-sdk` uses the installed Agent SDK package and can optionally point at a `claude` executable override via `executable`.
 
 ---
 
 ## Setup
 
-Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "keiyaku": {
-      "command": "npx",
-      "args": ["-y", "@astrosheep/keiyaku"]
-    }
-  }
-}
-```
-
-Restart client. Open a git repo. Run `status`. Done.
+Open a git repo. Run `keiyaku guide` and `keiyaku zako list`. Then use `keiyaku <command> --help` for exact command formats.
 
 ---
 
 ## Flow
 
 ```
-ask (anytime)  |  summon → [drive | ask]* → petition
+bind → round open → [summon | amend | delivery work] → delivery commits → round close → [round open | amend | petition]
 ```
 
 ---
 
 ## Tools
 
-**`ask`** — For questions. No branch, no contract. Use it freely.
+**`summon`** — Calls in an agent to do scoped work. If a round is open, the round scope is injected. Add `--incognito` for a one-off run with no response history.
 
 ```
-Where's the retry logic? Run the unit tests for that file.
+Implement the retry tests. Report touched files and verification.
+```
+
+---
+
+**`zako list` / `zako show <name>`** — Inspect available helpers before choosing `summon --agent NAME`.
+
+```bash
+keiyaku zako list
+keiyaku zako show codex
 ```
 
 ---
 
-**`summon`** — Opens a branch, writes the contract. Repo must be clean.
+**`bind`** — Opens a branch and writes `KEIYAKU.md`. Repo must be clean.
 
 Vague criteria = vague results. Write "make it better" and don't blame anyone but yourself.
 
 ```
-summon:
+bind:
   title: "Retry logic for HTTP client"
   goal: "5xx failures retry up to 3 times with exponential backoff"
   criteria:
@@ -79,10 +66,28 @@ summon:
 
 ---
 
-**`drive`** — Next round. Review the diff, say what's wrong, run another round.
+**`round open`** — Frame a delivery round before work starts.
 
 ```
-Backoff is 1.5x, should be 2x. Fix it, update the tests too.
+# Retry backoff
+
+## Objective
+Implement retries with exponential backoff.
+
+## Brief
+Keep the public API unchanged. Commit the delivery work before closing the round.
+```
+
+---
+
+**`round close`** — Record a completed round from git commits.
+
+```
+## Commits
+- abc1234
+
+## Report
+Retry tests pass and backoff is now 2x.
 ```
 
 ---
@@ -91,13 +96,13 @@ Backoff is 1.5x, should be 2x. Fix it, update the tests too.
 
 `CLAIM` = verified, all criteria pass. `FORFEIT` = abandon, throw everything away.
 
-Scores required (0–10). Oath required. The gates will actually reject you. Don't show up without checking.
+Oath required unless you explicitly bypass gates. Configured verification and reviewer gates will reject weak claims.
 
 ---
 
 **`status`** — Current state and what's blocking you.
 
-**`help`** — Full reference.
+**`keiyaku guide`** — Full reference.
 
 ---
 
@@ -106,9 +111,8 @@ Scores required (0–10). Oath required. The gates will actually reject you. Don
 | File | |
 |------|--|
 | `KEIYAKU.md` | Active contract |
-| `KEIYAKU_TRACE.md` | Per-round log |
-| `KEIYAKU.draft.md` | Recovery draft if summon fails |
-| `.keiyaku/response/*.md` | Per-round output |
+| `.keiyaku/draft/*.md` | Recovery input if bind/stdin execution fails |
+| `.keiyaku/response/*.md` | Tool response history |
 
 Don't want these tracked:
 
@@ -125,24 +129,58 @@ Don't want these tracked:
 keiyaku dump-env
 ```
 
+Per-agent runtime settings live in `.keiyaku/settings.json` and use `provider` / `executable`:
+
+```json
+{
+  "agents": {
+    "claude": {
+      "provider": "claude-agent-sdk",
+      "model": "claude-sonnet-4-5",
+      "executable": "claude",
+      "description": "Claude-side Zako for review and integration.",
+      "systemPromptFile": ".keiyaku/claude-system.md"
+    },
+    "codex": {
+      "provider": "codex-sdk",
+      "executable": "codex",
+      "description": "Default Codex-side Zako.",
+      "config": {
+        "developer_instructions": "Adapter-level instructions appended to Codex sessions."
+      }
+    },
+    "gemini": {
+      "provider": "gemini-cli-core",
+      "model": "gemini-2.5-pro",
+      "description": "Gemini-side Zako for preview and synthesis.",
+      "systemPromptFile": ".keiyaku/gemini-system.md"
+    }
+  },
+  "default": "codex",
+  "reviewer": "codex"
+}
+```
+
+Claude defaults:
+- `settingSources: ["project"]`
+- `permissionMode: "bypassPermissions"`
+- `resumePath` resumes via persisted provider session metadata
+
+Codex SDK notes:
+- `config` is passed through to Codex. Use `developer_instructions` for adapter-level instructions.
+- `model_instructions_file` is also accepted through `config`, but it replaces Codex built-in instructions.
+
+Gemini notes:
+- `systemPromptFile` is passed to Gemini CLI core as `GEMINI_SYSTEM_MD`, which replaces Gemini's base system prompt.
+
+`keiyaku zako list` and `keiyaku zako ls` show each profile's description when present.
+
 | Variable | Default | |
 |----------|---------|--|
-| `KEIYAKU_MCP_TRANSPORT` | `stdio` | `stdio` or `streamable-http` |
-| `KEIYAKU_MCP_HTTP_PORT` | `3000` | HTTP port |
 | `KEIYAKU_SUBAGENT_EXEC_TIMEOUT_MS` | — | Execution timeout |
 | `KEIYAKU_SUBAGENT_EXEC_IDLE_TIMEOUT_MS` | — | Idle timeout |
-| `KEIYAKU_INCREMENTAL_DIFF_MODE` | `targeted` | `targeted` \| `stat` \| `unified` |
 | `KEIYAKU_FAKE_SUBAGENT` | `0` | `1` = test stub |
 
-HTTP transport:
-
-```bash
-KEIYAKU_MCP_TRANSPORT=streamable-http \
-KEIYAKU_MCP_HTTP_HOST=127.0.0.1 \
-KEIYAKU_MCP_HTTP_PORT=3000 \
-npx -y @astrosheep/keiyaku
-```
-
 ---
 
 MIT