@astrosheep/keiyaku 4.6.6 → 4.6.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -0
- package/build/{integrations/marketplace → plugins}/.agents/plugins/marketplace.json +1 -1
- package/build/plugins/.claude-plugin/marketplace.json +5 -0
- package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/.claude-plugin/plugin.json +1 -1
- package/build/{integrations/marketplace/plugins/keiyaku → plugins/codex}/.codex-plugin/plugin.json +1 -1
- package/build/plugins/codex/skills/keiyaku/SKILL.md +44 -0
- package/build/plugins/codex/skills/keiyaku-akuma/SKILL.md +130 -0
- package/build/plugins/codex/skills/keiyaku-akuma/references/automation.md +269 -0
- package/build/plugins/codex/skills/keiyaku-babysit/SKILL.md +65 -0
- package/build/plugins/codex/skills/keiyaku-bind/SKILL.md +216 -0
- package/build/plugins/codex/skills/keiyaku-bind/agents/openai.yaml +4 -0
- package/build/plugins/codex/skills/keiyaku-task/SKILL.md +104 -0
- package/build/plugins/codex/skills/keiyaku-workflow/SKILL.md +129 -0
- package/build/plugins/opencode/package.json +6 -0
- package/build/plugins/opencode/skills/keiyaku/SKILL.md +44 -0
- package/build/plugins/opencode/skills/keiyaku-akuma/SKILL.md +130 -0
- package/build/plugins/opencode/skills/keiyaku-akuma/references/automation.md +269 -0
- package/build/plugins/opencode/skills/keiyaku-babysit/SKILL.md +65 -0
- package/build/plugins/opencode/skills/keiyaku-bind/SKILL.md +216 -0
- package/build/plugins/opencode/skills/keiyaku-bind/agents/openai.yaml +4 -0
- package/build/plugins/opencode/skills/keiyaku-task/SKILL.md +104 -0
- package/build/plugins/opencode/skills/keiyaku-workflow/SKILL.md +129 -0
- package/build/skills/keiyaku/SKILL.md +44 -0
- package/build/skills/keiyaku-akuma/SKILL.md +130 -0
- package/build/skills/keiyaku-akuma/references/automation.md +269 -0
- package/build/skills/keiyaku-babysit/SKILL.md +65 -0
- package/build/skills/keiyaku-bind/SKILL.md +216 -0
- package/build/skills/keiyaku-bind/agents/openai.yaml +4 -0
- package/build/skills/keiyaku-task/SKILL.md +104 -0
- package/build/skills/keiyaku-workflow/SKILL.md +129 -0
- package/build/src/akuma/akuma-instance.js +7 -5
- package/build/src/akuma/akuma-observe.d.ts +4 -0
- package/build/src/akuma/akuma-observe.js +12 -0
- package/build/src/akuma/akuma-owner.d.ts +3 -2
- package/build/src/akuma/akuma-owner.js +28 -10
- package/build/src/akuma/akuma-selection-execution.d.ts +3 -1
- package/build/src/akuma/akuma-selection-execution.js +2 -1
- package/build/src/akuma/akuma-wait.d.ts +2 -1
- package/build/src/akuma/akuma-wait.js +4 -1
- package/build/src/akuma/body.d.ts +1 -0
- package/build/src/akuma/body.js +12 -23
- package/build/src/akuma/selection-owner-port.d.ts +1 -1
- package/build/src/akuma/selection-owner-port.js +16 -5
- package/build/src/akuma/selection-request.d.ts +2 -0
- package/build/src/akuma/selection-request.js +2 -1
- package/build/src/akuma-body.js +4 -2
- package/build/src/cli/commands/akuma.js +6 -12
- package/build/src/cli/commands/install.js +3 -3
- package/build/src/library/akuma-creation.js +21 -19
- package/build/src/library/selection.js +5 -2
- package/build/src/plugin/akuma-signals.d.ts +10 -11
- package/build/src/plugin/akuma-signals.js +36 -20
- package/build/src/plugin/public.d.ts +5 -0
- package/build/src/plugin/runtime.d.ts +1 -0
- package/build/src/plugin/runtime.js +34 -23
- package/package.json +7 -7
- package/build/integrations/marketplace/.claude-plugin/marketplace.json +0 -5
- package/build/integrations/marketplace/plugins/keiyaku/package.json +0 -17
- /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku/SKILL.md +0 -0
- /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-akuma/SKILL.md +0 -0
- /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-akuma/references/automation.md +0 -0
- /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-babysit/SKILL.md +0 -0
- /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-bind/SKILL.md +0 -0
- /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-bind/agents/openai.yaml +0 -0
- /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-task/SKILL.md +0 -0
- /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-workflow/SKILL.md +0 -0
- /package/build/{integrations/marketplace/plugins/keiyaku/opencode.js → plugins/opencode/index.js} +0 -0
- /package/build/{integrations → plugins}/pi/keiyaku.ts +0 -0
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: keiyaku-bind
|
|
3
|
+
description: >-
|
|
4
|
+
Must read before binding a `kei` (Contract). Use when deciding what belongs
|
|
5
|
+
in one `kei`, how to divide its work, and how to write or run `bind`.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Before Binding A Keiyaku
|
|
9
|
+
|
|
10
|
+
Bind records a Contract whose objective, design, and acceptance boundary are
|
|
11
|
+
settled. Do not use it to leave an open design for someone else to decide.
|
|
12
|
+
|
|
13
|
+
## 1. What Must Be Clear Before Binding
|
|
14
|
+
|
|
15
|
+
Settle these facts first:
|
|
16
|
+
|
|
17
|
+
- objective and intended outcome;
|
|
18
|
+
- architecture and module boundaries;
|
|
19
|
+
- detailed design and implementation approach;
|
|
20
|
+
- public interfaces, behavior, data, and persistence;
|
|
21
|
+
- ordering, concurrency, dependencies, and failure behavior;
|
|
22
|
+
- acceptance conditions;
|
|
23
|
+
- verification and required evidence;
|
|
24
|
+
- the affected Region;
|
|
25
|
+
- the one holder responsible for the `kei`.
|
|
26
|
+
|
|
27
|
+
The Design section is a detailed design document. It may contain subsections
|
|
28
|
+
such as:
|
|
29
|
+
|
|
30
|
+
- Architecture: components, module boundaries, ownership, and connections;
|
|
31
|
+
- Interfaces And Behavior: public surfaces, inputs, outputs, success, and
|
|
32
|
+
refusal behavior;
|
|
33
|
+
- Data And Persistence: data shape, identity, lifecycle facts, and persistence;
|
|
34
|
+
- Approach And Flow: implementation approach, dependencies, ordering,
|
|
35
|
+
concurrency, and failure handling;
|
|
36
|
+
- Pseudocode: algorithms and control flow.
|
|
37
|
+
|
|
38
|
+
Record every design decision the implementation must follow. Add other Design
|
|
39
|
+
subsections when needed. Do not bind while the architecture, design, approach,
|
|
40
|
+
or acceptance conditions are open.
|
|
41
|
+
|
|
42
|
+
### Contract Shape: Mandatory Acceptance Boundary Check
|
|
43
|
+
|
|
44
|
+
Before every bind, identify the independently acceptable outcomes. For each
|
|
45
|
+
proposed part, ask whether it can be reviewed and accepted while another part
|
|
46
|
+
remains unfinished. If it can, you MUST bind it as a separate `kei`. Do not bind
|
|
47
|
+
an aggregate Contract containing independently acceptable outcomes.
|
|
48
|
+
|
|
49
|
+
A shared request, audit, theme, product name, worker, verification command, or
|
|
50
|
+
overlapping Region does NOT justify combining acceptance boundaries. Worker
|
|
51
|
+
assignment and Contract boundaries are separate decisions: one worker may
|
|
52
|
+
serve several Contracts, and several workers may contribute to one outcome.
|
|
53
|
+
A request to "open a kei" does not by itself instruct you to combine outcomes.
|
|
54
|
+
|
|
55
|
+
Keep parts together only when they jointly establish one outcome that cannot
|
|
56
|
+
be meaningfully accepted in parts. State that inseparability in Context and
|
|
57
|
+
make Criteria judge the same outcome. Do not manufacture inseparability by
|
|
58
|
+
writing one broad Objective around unrelated fixes.
|
|
59
|
+
|
|
60
|
+
- Use an Arc only for a chapter inside that one acceptance boundary; an Arc is
|
|
61
|
+
not separately accepted and MUST NOT substitute for an independent `kei`.
|
|
62
|
+
- Use a Task for decomposition or dependency memory that must outlive the
|
|
63
|
+
current conversation.
|
|
64
|
+
|
|
65
|
+
A `kei` owns one independently acceptable outcome and its delivery lifecycle. A
|
|
66
|
+
Task records decomposition or dependency memory; it may exist without a `kei`,
|
|
67
|
+
and it does not create a second acceptance or lifecycle. Associate a `kei` with
|
|
68
|
+
an existing Task only when that Task has real scheduling or dependency value.
|
|
69
|
+
Do not create a Task just to mirror a `kei`.
|
|
70
|
+
|
|
71
|
+
### Parallel Work
|
|
72
|
+
|
|
73
|
+
Parallel work is the default.
|
|
74
|
+
|
|
75
|
+
- Bind and advance independent `kei`s in parallel. Each has its own acceptance
|
|
76
|
+
boundary and holder.
|
|
77
|
+
- Within one `kei`, run independent Tasks or Arc chapters in parallel whenever
|
|
78
|
+
their work can proceed independently. They converge on the one acceptance
|
|
79
|
+
boundary, which the holder owns.
|
|
80
|
+
|
|
81
|
+
Region overlap is planning information. It does not prevent parallel work and
|
|
82
|
+
is not a lock, ownership claim, exact diff, or dependency. Use `--after` only
|
|
83
|
+
when one result must exist before another can proceed because of a real logical
|
|
84
|
+
dependency. Do not add `--after` merely because work touches the same Region.
|
|
85
|
+
|
|
86
|
+
## 2. Bind Syntax
|
|
87
|
+
|
|
88
|
+
Read the command's help for the complete option grammar:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
keiyaku -C <repo> bind --help
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Inspect declared Regions when planning parallel work:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
keiyaku -C <repo> region
|
|
98
|
+
keiyaku -C <repo> region <kei/...>
|
|
99
|
+
keiyaku -C <repo> region --path 'src/**' --path 'tests/**'
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
These list active Regions, read one Contract's Region, or show active Regions
|
|
103
|
+
overlapping the supplied patterns. Overlap is coordination information only.
|
|
104
|
+
|
|
105
|
+
Bind from stdin with a heredoc or a saved Markdown file:
|
|
106
|
+
|
|
107
|
+
~~~~bash
|
|
108
|
+
keiyaku -C <repo> bind - <<'KEIYAKU'
|
|
109
|
+
# <Delivery name>
|
|
110
|
+
|
|
111
|
+
## Context
|
|
112
|
+
<Motivation, authority, baseline, and boundaries.>
|
|
113
|
+
|
|
114
|
+
## Objective
|
|
115
|
+
<One observable, independently acceptable outcome.>
|
|
116
|
+
|
|
117
|
+
## Design
|
|
118
|
+
### Architecture
|
|
119
|
+
<Components, module boundaries, ownership, and connections.>
|
|
120
|
+
|
|
121
|
+
### Interfaces And Behavior
|
|
122
|
+
<Public surfaces, inputs, outputs, success, and refusal behavior.>
|
|
123
|
+
|
|
124
|
+
### Data And Persistence
|
|
125
|
+
<Data shape, identity, lifecycle facts, and persistence decisions.>
|
|
126
|
+
|
|
127
|
+
### Approach And Flow
|
|
128
|
+
<Implementation approach, dependencies, ordering, concurrency, and failure.>
|
|
129
|
+
|
|
130
|
+
### Pseudocode
|
|
131
|
+
<Algorithms and control flow.>
|
|
132
|
+
|
|
133
|
+
## Region
|
|
134
|
+
<One repository-relative write pattern per nonblank line.>
|
|
135
|
+
|
|
136
|
+
## Criteria
|
|
137
|
+
### <observable acceptance condition>
|
|
138
|
+
<How to observe pass or refusal.>
|
|
139
|
+
|
|
140
|
+
## Verification
|
|
141
|
+
```bash timeout=5m
|
|
142
|
+
<commands runnable exactly as written>
|
|
143
|
+
```
|
|
144
|
+
KEIYAKU
|
|
145
|
+
~~~~
|
|
146
|
+
|
|
147
|
+
Use the narrowest justified Region patterns for likely writes. A trailing `/`
|
|
148
|
+
is directory shorthand for `/**`. Patterns may be fenced lines, list items, or
|
|
149
|
+
bare lines; those forms are combined. Region patterns are planning evidence,
|
|
150
|
+
not a prediction of the exact diff.
|
|
151
|
+
|
|
152
|
+
Verification is optional. Each declaration is a closed bash, zsh, or pwsh
|
|
153
|
+
fence containing commands runnable as written. Use separate fences when checks
|
|
154
|
+
need different timeouts or results. Use an explicit timeout for bounded
|
|
155
|
+
commands; `5m` is the normal baseline.
|
|
156
|
+
|
|
157
|
+
Verification runs only when the Contract selects the `verified` gate, against
|
|
158
|
+
the exact integration snapshot in a clean disposable worktree for that attempt.
|
|
159
|
+
`deliver` reuses current satisfied evidence or runs the declarations; unsatisfied
|
|
160
|
+
results and runtime stops prevent placement. `audit` runs declarations for a
|
|
161
|
+
prospective candidate. Without `verified`, no verb runs Verification and the
|
|
162
|
+
section is inert document text. `reviewed` independently requires review
|
|
163
|
+
evidence. Selected gates are checked at placement.
|
|
164
|
+
|
|
165
|
+
For an existing Task with real scheduling or dependency value:
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
keiyaku -C <repo> bind --task <task/...> - < CONTRACT.md
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
For a real logical dependency between Contracts:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
keiyaku -C <repo> bind --after <kei/...> - < CONTRACT.md
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Gate selection is part of binding:
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
keiyaku -C <repo> bind --gates <name,...> - < CONTRACT.md
|
|
181
|
+
keiyaku -C <repo> bind --gates "" - < CONTRACT.md
|
|
182
|
+
keiyaku -C <repo> bind --gates reviewed - < CONTRACT.md
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Omitting `--gates` uses `gates.default`, or `reviewed` when no default group
|
|
186
|
+
exists. `--gates ""` selects no gates. Gates are named acceptance obligations,
|
|
187
|
+
not work assignments. Named gate groups and worktree hooks live in Settings;
|
|
188
|
+
see the README Configuration section or `keiyaku settings --help`.
|
|
189
|
+
|
|
190
|
+
## 3. After Binding
|
|
191
|
+
|
|
192
|
+
Binding appoints one managed worktree for the `kei`. Read the receipt as the
|
|
193
|
+
handoff. Keep the complete `kei/...` identity and note:
|
|
194
|
+
|
|
195
|
+
- the holder;
|
|
196
|
+
- the appointed worktree path (absent when appointment lagged);
|
|
197
|
+
- the target;
|
|
198
|
+
- gates and prerequisites;
|
|
199
|
+
- whether the `kei` is ready or waiting.
|
|
200
|
+
|
|
201
|
+
Work in the appointed worktree. When appointment lags, the receipt carries no
|
|
202
|
+
path and the `kei` shows pending reconciliation instead. If the receipt is
|
|
203
|
+
waiting, the stated prerequisites remain; do not bind a duplicate Contract.
|
|
204
|
+
|
|
205
|
+
The holder now owns the lifecycle:
|
|
206
|
+
|
|
207
|
+
1. Start the work directly or delegate Tasks, Arc chapters, Akumas, or Contract roles.
|
|
208
|
+
2. Run independent work in parallel and let it converge on the one acceptance
|
|
209
|
+
boundary.
|
|
210
|
+
3. Prepare and deliver the candidate.
|
|
211
|
+
4. Coordinate verification, review evidence, gates, and prerequisites.
|
|
212
|
+
5. Continue until the `kei` is accepted, amend terms while keeping the same
|
|
213
|
+
objective and acceptance boundary, or abandon it when either has changed.
|
|
214
|
+
|
|
215
|
+
Continue with `keiyaku-workflow` for this lifecycle. For Akuma invocation,
|
|
216
|
+
telling, waiting, permissions, and history, read `keiyaku-akuma`.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: keiyaku-task
|
|
3
|
+
description: >-
|
|
4
|
+
Must read when using Tasks for durable work planning, decomposition, or
|
|
5
|
+
dependencies.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Keiyaku Task
|
|
9
|
+
|
|
10
|
+
A Task is durable planning memory. It records work, decomposition, and
|
|
11
|
+
relationships that must remain after the current conversation. Task is an
|
|
12
|
+
independent product; it is not a Contract, Arc, Akuma, permission, acceptance
|
|
13
|
+
boundary, or fulfillment lifecycle.
|
|
14
|
+
|
|
15
|
+
## 1. When To Use A Task
|
|
16
|
+
|
|
17
|
+
Use a Task when the plan or dependency must outlive the current conversation.
|
|
18
|
+
Skip it when the work is small and no durable planning memory is needed.
|
|
19
|
+
|
|
20
|
+
- Use a `kei` for one independently acceptable outcome.
|
|
21
|
+
- Use an Arc for a chapter inside one `kei`.
|
|
22
|
+
- Use a Task for decomposition or dependency memory.
|
|
23
|
+
- Do not create a Task just to mirror a `kei`.
|
|
24
|
+
|
|
25
|
+
A Task may exist without a Contract. Associating a Task with a `kei` does not
|
|
26
|
+
transfer the Contract's holder, acceptance, or lifecycle to the Task.
|
|
27
|
+
|
|
28
|
+
## 2. Relationships And Parallel Work
|
|
29
|
+
|
|
30
|
+
Independent Tasks may start and progress in parallel when their dependencies
|
|
31
|
+
allow it.
|
|
32
|
+
|
|
33
|
+
Use the relationships for their actual meanings:
|
|
34
|
+
|
|
35
|
+
- `needs` means this Task must wait for another Task to become terminal.
|
|
36
|
+
- `parent` groups decomposition; it does not create a dependency.
|
|
37
|
+
- `supersedes` points to work replaced by this Task.
|
|
38
|
+
- `relates` records a connection without affecting readiness.
|
|
39
|
+
|
|
40
|
+
Only `needs` orders work. Do not add it because Tasks touch the same Region or
|
|
41
|
+
because one Task is related to another. A terminal Task releases its dependents.
|
|
42
|
+
An `on_hold` Task is deliberately paused; it is neither ready nor blocked.
|
|
43
|
+
|
|
44
|
+
## 3. Task Commands
|
|
45
|
+
|
|
46
|
+
Create and inspect Tasks:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
keiyaku task add "<title>"
|
|
50
|
+
keiyaku task add "<title>" --priority 1 --needs <task-id>
|
|
51
|
+
keiyaku task show <task-id>
|
|
52
|
+
keiyaku task ls
|
|
53
|
+
keiyaku task ready
|
|
54
|
+
keiyaku task blocked
|
|
55
|
+
keiyaku task tree <task-id>
|
|
56
|
+
keiyaku task doctor
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Use complete Task IDs for targeted commands. `ls`, `ready`, and `blocked` use
|
|
60
|
+
the current namespace; use `--world` to inspect the complete Task world.
|
|
61
|
+
|
|
62
|
+
Change lifecycle state:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
keiyaku task start <task-id>...
|
|
66
|
+
keiyaku task stop <task-id>
|
|
67
|
+
keiyaku task hold <task-id>...
|
|
68
|
+
keiyaku task resume <task-id>
|
|
69
|
+
keiyaku task done <task-id>...
|
|
70
|
+
keiyaku task drop <task-id>... --note "<reason>"
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Use `done` when the Task is complete. Use `drop` when it will not be done.
|
|
74
|
+
Both terminal states release dependent Tasks. Use `hold` for a deliberate pause,
|
|
75
|
+
not for an unresolved dependency; unresolved `needs` appear in `blocked`.
|
|
76
|
+
|
|
77
|
+
Update a Task without changing its lifecycle:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
keiyaku task update <task-id> --title "<title>"
|
|
81
|
+
keiyaku task update <task-id> --body "<body>"
|
|
82
|
+
keiyaku task update <task-id> --needs <task-id>
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Use `task compose -` when several Tasks and their relationships should be
|
|
86
|
+
planned or admitted together. Use `--plan` to inspect the composition without
|
|
87
|
+
writing it.
|
|
88
|
+
|
|
89
|
+
## 4. After Creating A Task
|
|
90
|
+
|
|
91
|
+
Read the returned Task identity. Then:
|
|
92
|
+
|
|
93
|
+
1. Start ready work.
|
|
94
|
+
2. Run independent Tasks in parallel.
|
|
95
|
+
3. Add or remove relationships when the plan changes.
|
|
96
|
+
4. Hold work that is deliberately paused.
|
|
97
|
+
5. Mark completed work `done`, or mark abandoned work `drop` with a reason.
|
|
98
|
+
6. Use `ready`, `blocked`, `tree`, or `doctor` to rebuild the current view.
|
|
99
|
+
|
|
100
|
+
Task records planning memory. It does not perform the work, claim acceptance,
|
|
101
|
+
assign a holder, or decide what a Contract may accept.
|
|
102
|
+
|
|
103
|
+
Read `keiyaku-bind` for Contract authoring and `keiyaku-workflow` for Contract
|
|
104
|
+
lifecycle.
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: keiyaku-workflow
|
|
3
|
+
description: >-
|
|
4
|
+
Must read before binding a `kei` (Contract) or when acting as its holder.
|
|
5
|
+
Use when deciding when to bind a kei, how to shape and hold it, how to
|
|
6
|
+
delegate its work, and how to accept, amend, or end it.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Keiyaku Workflow
|
|
10
|
+
|
|
11
|
+
The holder runs one Contract's fulfillment loop from preparation to completion.
|
|
12
|
+
|
|
13
|
+
## 1. Prepare Before Binding
|
|
14
|
+
|
|
15
|
+
Before `bind`, settle the information that makes the `kei` truthful:
|
|
16
|
+
|
|
17
|
+
- objective and intended outcome;
|
|
18
|
+
- design and approach;
|
|
19
|
+
- affected Region;
|
|
20
|
+
- acceptance conditions;
|
|
21
|
+
- verification and required evidence;
|
|
22
|
+
- prerequisites;
|
|
23
|
+
- holder.
|
|
24
|
+
|
|
25
|
+
If the design, approach, or acceptance conditions are still open, do not bind.
|
|
26
|
+
Resolve them with their owner first. Private implementation details may remain
|
|
27
|
+
for the Deliverer; the public meaning and acceptance boundary may not.
|
|
28
|
+
|
|
29
|
+
Bind independent `kei`s in parallel. Do not split one acceptance boundary just
|
|
30
|
+
to create parallel work.
|
|
31
|
+
|
|
32
|
+
## 2. Split the Work
|
|
33
|
+
|
|
34
|
+
- Separate `kei`s have independently acceptable outcomes.
|
|
35
|
+
- An Arc is a chapter of one `kei`; it is not separately accepted.
|
|
36
|
+
- A Task stores decomposition or dependencies that outlive this conversation.
|
|
37
|
+
|
|
38
|
+
Use `after` only when one `kei` requires another to be accepted first. Ordinary
|
|
39
|
+
overlap is not a dependency.
|
|
40
|
+
|
|
41
|
+
## 3. Roles
|
|
42
|
+
|
|
43
|
+
A `kei` has three roles. They are responsibilities, not people, and one agent
|
|
44
|
+
may fill more than one of them, with one exception below.
|
|
45
|
+
|
|
46
|
+
- **Holder:** exactly one per `kei`. Owns the fulfillment loop and acceptance
|
|
47
|
+
until the Contract is accepted or abandoned. Handing work to others never
|
|
48
|
+
transfers this responsibility.
|
|
49
|
+
- **Deliverer:** produces the candidate in the appointed worktree and tenders
|
|
50
|
+
it with `deliver`.
|
|
51
|
+
- **Reviewer:** judges the complete Contract against its acceptance conditions
|
|
52
|
+
and records the verdict with `review`.
|
|
53
|
+
|
|
54
|
+
Review is independent when the Reviewer did not deliver the candidate under
|
|
55
|
+
review. That is the whole requirement. The holder may review its own `kei`; a
|
|
56
|
+
fresh Akuma is not what makes review independent. Keiyaku does not check who
|
|
57
|
+
reviews, so keeping the Reviewer apart from the Deliverer is the holder's duty.
|
|
58
|
+
|
|
59
|
+
Any role may be filled directly or handed to an Akuma. Hand one over when other
|
|
60
|
+
hands help the work, not to make review count.
|
|
61
|
+
|
|
62
|
+
## 4. Lifecycle
|
|
63
|
+
|
|
64
|
+
Each act changes a different part of the world:
|
|
65
|
+
|
|
66
|
+
- **Bind:** Journal gains the Contract and its terms. Workspace appointment
|
|
67
|
+
names one managed worktree; the receipt reports its path. Appointment lag
|
|
68
|
+
leaves the bind admitted without a path and reports pending reconciliation.
|
|
69
|
+
`reconcile` retries workspace realization.
|
|
70
|
+
- **Work:** Changes and commits belong in the appointed worktree. Another
|
|
71
|
+
lane's claim can move the target beneath it. Check target movement before
|
|
72
|
+
audit; when it matters, merge the target branch (main when selected) in the
|
|
73
|
+
worktree and resolve conflicts there before auditing.
|
|
74
|
+
- **Audit:** Previews the candidate and target without tendering or claiming.
|
|
75
|
+
With `verified` selected, Verification runs for the captured subject and can
|
|
76
|
+
record an attestation. Without that gate, the section is inert text and no
|
|
77
|
+
verb runs Verification. A stopped run records no new verdict.
|
|
78
|
+
- **Deliver:** Captures a tender and integration against the observed target;
|
|
79
|
+
journal gains a delivered candidate. Ready prerequisites and gates trigger
|
|
80
|
+
placement and claim in this invocation; otherwise the candidate waits.
|
|
81
|
+
Changed candidate content stales earlier review. Identical content retains
|
|
82
|
+
review across rebase or target movement.
|
|
83
|
+
- **Review:** Records verdict evidence for the current document and worktree
|
|
84
|
+
content, even before delivery. Satisfied review requests placement: with a
|
|
85
|
+
delivered candidate, current gates, and ready prerequisites, it accepts in
|
|
86
|
+
this invocation. Unsatisfied review records testimony without placement.
|
|
87
|
+
- **Abandon:** Records the alternate terminal outcome without accepting. Accepted
|
|
88
|
+
and abandoned Contracts cannot be reopened.
|
|
89
|
+
|
|
90
|
+
Placement judges declared gates, not the producer's identity. Review does not
|
|
91
|
+
replace Verification; audit never requests placement. Read the final receipt
|
|
92
|
+
for stops and reconciliation lag after an admitted act.
|
|
93
|
+
|
|
94
|
+
## 5. Handing A Role To An Akuma
|
|
95
|
+
|
|
96
|
+
This is the one commissioning map. `call --help` owns the exact action
|
|
97
|
+
vocabulary and default set. The flagship acting directly needs no grant.
|
|
98
|
+
Birth freezes an Akuma's actions; `--contract` records association, not
|
|
99
|
+
authority.
|
|
100
|
+
|
|
101
|
+
| Role | Grant at birth | Return |
|
|
102
|
+
| --- | --- | --- |
|
|
103
|
+
| Holder | The actions the delegated loop will perform; include `contract.review` when this holder will review. Commission with the `kei`, current Arc when one exists, appointed worktree, and holder duties. | Acceptance or abandonment, with receipts. |
|
|
104
|
+
| Deliverer | The ordinary baseline: every Task mutation, Contract audit and delivery, and Akuma management. `keiyaku -C <repo> call worker --alias @deliverer --contract <kei/...> --workdir <appointed-path> -` | The delivery receipt. |
|
|
105
|
+
| Reviewer | `--allowed contract.review`: `keiyaku -C <repo> call review-akuma --alias @reviewer --contract <kei/...> --workdir <appointed-path> --allowed contract.review -` | The verdict receipt. Without the grant, `not-allowed` refuses and no verdict is recorded. |
|
|
106
|
+
|
|
107
|
+
An Archetype's explicit allowed set replaces the ordinary baseline; check
|
|
108
|
+
`status` for effective actions. `tell` and `fork` cannot add a grant to a live
|
|
109
|
+
Akuma, so call a fresh one with the grant. Nested calls cannot exceed their
|
|
110
|
+
direct parent's actions.
|
|
111
|
+
|
|
112
|
+
Commission with a clear objective, current Arc when one exists, appointed
|
|
113
|
+
worktree, and expected result. Never ask the Akuma that delivered a candidate
|
|
114
|
+
to review it. Use `keiyaku-akuma` for invocation and observation, and command
|
|
115
|
+
help for exact syntax.
|
|
116
|
+
|
|
117
|
+
## 6. Decide What Happens Next
|
|
118
|
+
|
|
119
|
+
The holder checks candidate, verification, review, prerequisites, and gates.
|
|
120
|
+
|
|
121
|
+
- A ready delivered candidate claims automatically on delivery or satisfied
|
|
122
|
+
review; no separate claim command is needed.
|
|
123
|
+
- Missing evidence or unfinished work calls for another commission or chapter.
|
|
124
|
+
- Amend when the objective and acceptance boundary remain the same but terms
|
|
125
|
+
must change.
|
|
126
|
+
- Abandon and bind a new `kei` when the objective or acceptance boundary changes.
|
|
127
|
+
|
|
128
|
+
Read `keiyaku-bind` for authoring, `keiyaku-akuma` for delegation, and
|
|
129
|
+
`keiyaku-babysit` for supervising multiple lanes.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: keiyaku
|
|
3
|
+
description: >-
|
|
4
|
+
Keiyaku is a CLI that records plans, writes handoff terms for deliveries,
|
|
5
|
+
and calls delegates. Use this skill when you need to figure out which
|
|
6
|
+
Keiyaku skill or command to reach for.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Keiyaku
|
|
10
|
+
|
|
11
|
+
## Model
|
|
12
|
+
|
|
13
|
+
Keiyaku is three independent pillars, not a bundle: **Task** remembers plans
|
|
14
|
+
and dependencies, **Contract** makes acceptance standing and auditable,
|
|
15
|
+
**Akuma** invokes capability. Use any one alone; combine them only when the
|
|
16
|
+
work calls for it. Behind every Contract in flight there is one holder of its
|
|
17
|
+
fulfillment loop — whoever turns intent into commissions and returns into
|
|
18
|
+
decisions. The flagship holds it by default, and may hand a whole Contract's
|
|
19
|
+
loop to one Aku in a single commission; the harness serves both styles
|
|
20
|
+
equally. See `keiyaku-workflow` for the loop, `keiyaku-bind` for authoring,
|
|
21
|
+
`keiyaku-akuma` for invocation.
|
|
22
|
+
|
|
23
|
+
## Quick Start
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
keiyaku -C <repo> task add "title"
|
|
27
|
+
keiyaku -C <repo> task start <task-id>
|
|
28
|
+
keiyaku -C <repo> bind [--task <task-id>] -
|
|
29
|
+
keiyaku -C <repo> status
|
|
30
|
+
keiyaku -C <repo> deliver [<contract>|@<contract>]
|
|
31
|
+
keiyaku -C <repo> review [<contract>|@<contract>] --satisfied
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`-C` selects the invocation cwd and therefore the World. `--repo <path>` only
|
|
35
|
+
selects the Contract repository; it never retargets that World. `call
|
|
36
|
+
--workdir <path>` selects execution cwd (relative to the effective invocation
|
|
37
|
+
cwd). Without it, the call uses the invocation cwd; `--contract` associates a
|
|
38
|
+
Contract without selecting an execution directory.
|
|
39
|
+
|
|
40
|
+
`deliver`, `review`, and `audit` may take time after their leading admission.
|
|
41
|
+
Their witnessed progress is ephemeral stderr output; stdout remains one final
|
|
42
|
+
text or JSON result. Ctrl-C asks the owned operation to stop and waits for its
|
|
43
|
+
truthful final receipt, so it is not evidence that an already admitted action
|
|
44
|
+
was rolled back.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: keiyaku-akuma
|
|
3
|
+
description: >-
|
|
4
|
+
Use when the work involves Akuma or Aku, or when you want other hands on
|
|
5
|
+
it: delegating a job, or fanning out research, checks, or other parallel
|
|
6
|
+
work.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Keiyaku Akuma
|
|
10
|
+
|
|
11
|
+
Use Akumas to delegate work to another worker. `call` creates a new Akuma;
|
|
12
|
+
`tell` admits a Tell for an existing Akuma; `ask` admits one and observes its
|
|
13
|
+
exact answer. Keep the complete AkuId, such as `aku/worker/1234abcd`, when you
|
|
14
|
+
need to address the same worker later. An alias such as `@reviewer` is a
|
|
15
|
+
shorter, world-local name.
|
|
16
|
+
|
|
17
|
+
## Call a new Akuma
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
keiyaku call worker "Summarize the recent changes in src/cli"
|
|
21
|
+
keiyaku call worker --alias @reviewer --wait 10m - < brief.md
|
|
22
|
+
keiyaku call worker
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
The prompt is optional for prompt-free birth. Otherwise it is the new Akuma's
|
|
26
|
+
first prompt: give it as one argument, or use `-` to read stdin, never both.
|
|
27
|
+
Calls are detached by default: they return the new identity after birth without
|
|
28
|
+
waiting for the first answer. Use explicit `--wait <duration>` when this
|
|
29
|
+
invocation should block while observing that initial work. `--wait` only bounds
|
|
30
|
+
this command; it never stops the Akuma. Read `call --help` for flag syntax,
|
|
31
|
+
defaults, and action vocabulary.
|
|
32
|
+
To hand a Contract role to an Akuma, use the grant table in `keiyaku-workflow`.
|
|
33
|
+
|
|
34
|
+
The selected Akuma name is a reusable worker configuration, not an individual.
|
|
35
|
+
Calling it again creates an independent Akuma. Use different names for
|
|
36
|
+
capabilities, not merely for parallelism.
|
|
37
|
+
|
|
38
|
+
## Commission Context
|
|
39
|
+
|
|
40
|
+
`--contract` only records the association. It does not tell the Akuma the
|
|
41
|
+
Contract or worktree. Put them in the prompt explicitly:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
keiyaku call worker --contract kei/add-rate-limit-a1b2 --workdir /path/to/worktree - <<'EOF'
|
|
45
|
+
Contract: kei/add-rate-limit-a1b2
|
|
46
|
+
Worktree: /path/to/worktree
|
|
47
|
+
This Arc: implement the limiter and its tests
|
|
48
|
+
EOF
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`--contract` does not choose a worktree. Use `--workdir <path>` when needed.
|
|
52
|
+
|
|
53
|
+
## Tell or ask an existing Akuma
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
keiyaku tell @reviewer "The candidate moved; re-examine the worktree"
|
|
57
|
+
keiyaku tell @reviewer --interrupt - < new-priority.md
|
|
58
|
+
keiyaku ask @reviewer --wait 10m "What is your verdict?"
|
|
59
|
+
keiyaku ask @reviewer --schema verdict.schema.json - < question.md
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`tell` admits the next instruction and returns its admission receipt; it does
|
|
63
|
+
not await an answer. `ask` admits a Tell and observes that exact answer,
|
|
64
|
+
unbounded unless `--wait` limits observation. Both require a prompt and accept
|
|
65
|
+
`--interrupt` to put down current work before admitting the new Tell. Schema
|
|
66
|
+
belongs only to `ask`; `tell --schema` and `tell --wait` refuse and point to
|
|
67
|
+
`ask`. A deadline never withdraws an admitted Tell. Read `tell --help` and
|
|
68
|
+
`ask --help` for the complete flag grammar.
|
|
69
|
+
|
|
70
|
+
## Observe work
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
keiyaku wait @deliverer @reviewer
|
|
74
|
+
keiyaku wait --all --timeout 30m @deliverer @reviewer
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Use `wait` for one or more existing Akumas. The default is `--any`; use
|
|
78
|
+
`--all` for every selected Akuma. `--timeout` limits observation and does not
|
|
79
|
+
stop workers. A completed Akuma already counts, so repeating a wait can return
|
|
80
|
+
immediately. See `wait --help` for the complete grammar. Unlike `ask`, `wait`
|
|
81
|
+
observes existing Akuma-wide work, not the answer to a newly admitted Tell.
|
|
82
|
+
|
|
83
|
+
## Inspect and retrieve results
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
keiyaku status
|
|
87
|
+
keiyaku status @reviewer
|
|
88
|
+
keiyaku ls aku/
|
|
89
|
+
keiyaku ls "aku/*/*"
|
|
90
|
+
keiyaku history @reviewer --last
|
|
91
|
+
keiyaku history @reviewer --id turn/3
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`status` shows the roster or one Akuma's workdir and effective actions.
|
|
95
|
+
`ls aku/` shows callable names; `ls "aku/*/*"` shows born workers.
|
|
96
|
+
`history --last` reads the latest complete answer; `history --id` reads an
|
|
97
|
+
exact result named by status or wait. Use the complete AkuId when an alias may
|
|
98
|
+
move; see `history --help` for paging.
|
|
99
|
+
|
|
100
|
+
## Stop and branch
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
keiyaku kill @reviewer
|
|
104
|
+
keiyaku fork @reviewer --at turn/3
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`kill` stops current work without admitting a Tell, deleting the Akuma, or
|
|
108
|
+
removing its history. `fork` creates a new Akuma from one exact retained
|
|
109
|
+
answered history point; the source is unchanged, and providers that cannot
|
|
110
|
+
fork report that refusal. See `kill --help` and `fork --help` for the
|
|
111
|
+
complete grammar.
|
|
112
|
+
|
|
113
|
+
## JavaScript automation
|
|
114
|
+
|
|
115
|
+
Use [Automation With The Akuma API](references/automation.md) for a
|
|
116
|
+
task-specific JavaScript coordinator, structured answers, or multi-worker
|
|
117
|
+
orchestration. The CLI is enough for one commission and its return. A
|
|
118
|
+
prompt-free birth followed by one input-bound ask uses the same identity:
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
import { Akuma, Akumas, World } from "@astrosheep/keiyaku";
|
|
122
|
+
|
|
123
|
+
const root = await World.at(process.cwd());
|
|
124
|
+
const called = await Akumas.of(root).call({ archetype: "worker" });
|
|
125
|
+
const worker = Akuma.select(root, called.akuma);
|
|
126
|
+
const result = await worker.ask("Inspect the change");
|
|
127
|
+
console.log(result.observation);
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The automation guide covers schema-based answer handling and longer workflows.
|