@markjaquith/agency 2.47.3 → 2.48.1
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 +14 -19
- package/package.json +1 -2
- package/src/cli-parser.test.ts +0 -7
- package/src/cli.test.ts +11 -3
- package/src/commands/init.test.ts +8 -6
- package/src/commands/integration.test.ts +1 -16
- package/src/commands/integration.ts +0 -2
- package/src/commands/work.test.ts +38 -4
- package/src/commands/work.ts +1 -1
- package/src/services/IntegrationService.test.ts +69 -76
- package/src/services/IntegrationService.ts +27 -52
- package/src/workbase/AGENTS.md +37 -8
- package/fixtures/protocol/skill-setup-commands.json +0 -18
- package/skills/agency/SKILL.md +0 -151
- package/skills/agency/references/commands.md +0 -188
- package/skills/agency/references/contracts.md +0 -322
- package/skills/agency/references/recipes.md +0 -264
- package/src/workbase/AGENCY_COMMAND.md +0 -48
- package/src/workbase/opencode-command-file.ts +0 -30
|
@@ -1,322 +0,0 @@
|
|
|
1
|
-
# Agency Data Contracts
|
|
2
|
-
|
|
3
|
-
Use Agency JSON output instead of scraping human tables. Entity IDs are directory
|
|
4
|
-
names; they are not duplicated in frontmatter.
|
|
5
|
-
|
|
6
|
-
## Context Contract
|
|
7
|
-
|
|
8
|
-
`agency context . --json` returns a versioned success envelope whose result
|
|
9
|
-
contains:
|
|
10
|
-
|
|
11
|
-
- `projection`: `compact` for root discovery by default, otherwise `complete`
|
|
12
|
-
unless compact entity context was explicitly requested;
|
|
13
|
-
- `workbase`: root, config path, and config version;
|
|
14
|
-
- `target`: resolved workbase, epic, task, or phase identity;
|
|
15
|
-
- `discovery`: at the workbase root, all valid epic, task, and phase documents;
|
|
16
|
-
- `documents`: ancestor frontmatter, paths, SHA-256 revisions, and prose;
|
|
17
|
-
- `graph`: parent, dependencies, dependents, readiness blockers, and progress;
|
|
18
|
-
- `authority`: `orchestration` or `execution`, one writable checkout or none,
|
|
19
|
-
and read-only references;
|
|
20
|
-
- `workspace`: code path, materialization and registration state, commits, and
|
|
21
|
-
inspection warnings;
|
|
22
|
-
- `pr`: recorded provider-neutral pull request identity and state; and
|
|
23
|
-
- `validation`: validity and issues.
|
|
24
|
-
|
|
25
|
-
Compact context retains identity, revisions, authority, paths, graph state,
|
|
26
|
-
materialization, and warnings while omitting prose and low-level Git details.
|
|
27
|
-
|
|
28
|
-
## Repository Declarations
|
|
29
|
-
|
|
30
|
-
Tracked `agency.json` may contain portable repository declarations:
|
|
31
|
-
|
|
32
|
-
```json
|
|
33
|
-
{
|
|
34
|
-
"version": 2,
|
|
35
|
-
"repositories": {
|
|
36
|
-
"frontend": { "remote": "git@example.com:team/frontend.git" }
|
|
37
|
-
}
|
|
38
|
-
}
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
Remotes are provider-neutral network Git remotes. Local paths, file URLs, and
|
|
42
|
-
credential-bearing HTTP URLs are invalid. `repos/`, task and phase `code/`, and
|
|
43
|
-
symlink targets are local-only and never part of this contract.
|
|
44
|
-
|
|
45
|
-
Repository inspection returns `declaredRemote`, the actual local `remote`, and
|
|
46
|
-
orthogonal `states`: `declared`, `materialized`, `linked`, `missing`, `invalid`,
|
|
47
|
-
and `remote-drifted`. Setup JSON contains `mode`, `actions`, `unresolved`, and the
|
|
48
|
-
post-operation `repositories`. Actions are `materialize` or `adopt`, with
|
|
49
|
-
`planned` or `applied` status. Dry-run never mutates. Apply never overwrites a
|
|
50
|
-
link or path and never repairs drift without an explicit remote choice.
|
|
51
|
-
|
|
52
|
-
## Frontmatter Shapes
|
|
53
|
-
|
|
54
|
-
### Epic
|
|
55
|
-
|
|
56
|
-
```yaml
|
|
57
|
-
---
|
|
58
|
-
ticketUrl: https://example.com/tickets/checkout
|
|
59
|
-
description: Coordinate checkout delivery.
|
|
60
|
-
repos:
|
|
61
|
-
- repo: frontend
|
|
62
|
-
ref: main
|
|
63
|
-
tasks:
|
|
64
|
-
- id: api
|
|
65
|
-
- id: ui
|
|
66
|
-
dependsOn:
|
|
67
|
-
- api
|
|
68
|
-
---
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
Epics have read-only `repos`, never a writable `repo`. Their `tasks` list owns
|
|
72
|
-
task ordering and task dependencies.
|
|
73
|
-
|
|
74
|
-
### Single-Phase Task
|
|
75
|
-
|
|
76
|
-
```yaml
|
|
77
|
-
---
|
|
78
|
-
ticketUrl: null
|
|
79
|
-
description: Refresh checkout copy.
|
|
80
|
-
epic: checkout
|
|
81
|
-
repo: frontend
|
|
82
|
-
repos:
|
|
83
|
-
- repo: backend
|
|
84
|
-
ref: main
|
|
85
|
-
branch: task/refresh-copy
|
|
86
|
-
base: main
|
|
87
|
-
pr: null
|
|
88
|
-
status: open
|
|
89
|
-
---
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
### Multi-Phase Task
|
|
93
|
-
|
|
94
|
-
```yaml
|
|
95
|
-
---
|
|
96
|
-
ticketUrl: null
|
|
97
|
-
description: Deliver checkout.
|
|
98
|
-
epic: checkout
|
|
99
|
-
phases:
|
|
100
|
-
- id: api
|
|
101
|
-
- id: ui
|
|
102
|
-
dependsOn:
|
|
103
|
-
- api
|
|
104
|
-
---
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
The task's `phases` list owns phase ordering and dependencies. Execution fields
|
|
108
|
-
belong in each phase document.
|
|
109
|
-
|
|
110
|
-
### Phase
|
|
111
|
-
|
|
112
|
-
```yaml
|
|
113
|
-
---
|
|
114
|
-
description: Build the checkout UI.
|
|
115
|
-
repo: frontend
|
|
116
|
-
repos:
|
|
117
|
-
- repo: backend
|
|
118
|
-
ref: main
|
|
119
|
-
branch: task/checkout-ui
|
|
120
|
-
base: task/checkout-api
|
|
121
|
-
pr: null
|
|
122
|
-
status: open
|
|
123
|
-
---
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
`ticketUrl` belongs to tasks and epics, not phases. `description` is optional but
|
|
127
|
-
must be non-empty when present. `pr` is `null`, a legacy GitHub PR URL, or a
|
|
128
|
-
provider-neutral record containing `provider`, `repository`, `identifier`, `url`,
|
|
129
|
-
`state`, `draft`, `merged`, and optional `mergeable`. Mergeability is `true`,
|
|
130
|
-
`false`, or `null` when the provider cannot determine it. New PR creation writes
|
|
131
|
-
the structured record.
|
|
132
|
-
Status is `open`, `working`, `delegated`, `done`, or `dropped`; `delegated` is
|
|
133
|
-
readable legacy state but cannot be newly assigned.
|
|
134
|
-
|
|
135
|
-
## Structural Invariants
|
|
136
|
-
|
|
137
|
-
- An execution unit has one writable `repo`; plural `repos` are read-only
|
|
138
|
-
`{ repo, ref }` entries and cannot repeat the writable alias.
|
|
139
|
-
- A writable `(repo, branch)` pair belongs to exactly one active execution unit.
|
|
140
|
-
- `done` represents an authoritative merged pull request and is reconciled by
|
|
141
|
-
`agency sync --apply`; committed or review-ready work remains `working`.
|
|
142
|
-
- Only `done` satisfies dependencies. `dropped` is terminal but blocks dependents.
|
|
143
|
-
- Epic task dependencies live in `EPIC.md`; phase dependencies live in `TASK.md`.
|
|
144
|
-
- IDs remain stable; use `dependsOn`, not numeric directory prefixes, for order.
|
|
145
|
-
- YAML duplicate keys, anchors, aliases, and custom tags are invalid.
|
|
146
|
-
- Use a commit SHA as a reference `ref` when reproducibility is required.
|
|
147
|
-
|
|
148
|
-
## Graph Contract
|
|
149
|
-
|
|
150
|
-
`agency graph --json` emits graph contract version 1. Stable node IDs are
|
|
151
|
-
`epic:<id>`, `task:<id>`, `phase:<task>/<phase>`,
|
|
152
|
-
`repository:<alias>`, and `execution-unit:<kind>/<id>`. Edge types are `owns`,
|
|
153
|
-
`depends_on`, `writes`, and `references`.
|
|
154
|
-
|
|
155
|
-
Every work node includes status, readiness, `blockedBy`, detailed blockers,
|
|
156
|
-
terminal state, reverse dependents, and aggregate progress. Filters run after
|
|
157
|
-
state computation. `--jsonl` emits a versioned `meta` record, node and edge
|
|
158
|
-
records, then an `end` record; together they reconstruct the JSON result.
|
|
159
|
-
|
|
160
|
-
## Machine Envelope
|
|
161
|
-
|
|
162
|
-
The published success fixture is normalized from
|
|
163
|
-
`agency init /work/agency --json`:
|
|
164
|
-
|
|
165
|
-
```json
|
|
166
|
-
{
|
|
167
|
-
"version": 1,
|
|
168
|
-
"ok": true,
|
|
169
|
-
"result": {
|
|
170
|
-
"root": "/work/agency"
|
|
171
|
-
}
|
|
172
|
-
}
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
The published error fixture is the output of `agency unknown --json`:
|
|
176
|
-
|
|
177
|
-
```json
|
|
178
|
-
{
|
|
179
|
-
"version": 1,
|
|
180
|
-
"ok": false,
|
|
181
|
-
"error": {
|
|
182
|
-
"code": "CLI_USAGE",
|
|
183
|
-
"message": "Unknown command 'unknown'.\n\nUsage: agency <command> [options]",
|
|
184
|
-
"fields": {
|
|
185
|
-
"detail": "Unknown command 'unknown'.",
|
|
186
|
-
"usage": "agency <command> [options]"
|
|
187
|
-
},
|
|
188
|
-
"retryable": false,
|
|
189
|
-
"remediation": "Correct the arguments using the usage value in error.fields."
|
|
190
|
-
}
|
|
191
|
-
}
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
These examples are exported from `fixtures/protocol/` and tested against real
|
|
195
|
-
CLI subprocess output. The Effect schemas are exported by the package and by
|
|
196
|
-
`@markjaquith/agency/protocol`. The distributable JSON Schemas are exported as
|
|
197
|
-
`@markjaquith/agency/schemas/agency-envelope-v1.json` and
|
|
198
|
-
`@markjaquith/agency/schemas/agency-graph-v1.json`.
|
|
199
|
-
|
|
200
|
-
Only the envelope and graph result have published JSON Schemas. The envelope's
|
|
201
|
-
`result` is intentionally unconstrained. Context, next, claim, prepare, sync,
|
|
202
|
-
repository setup, and PR result shapes are exercised by CLI tests but do not have independent
|
|
203
|
-
published schemas.
|
|
204
|
-
|
|
205
|
-
### Output And Exit Guarantees
|
|
206
|
-
|
|
207
|
-
- `--json` writes exactly one newline-terminated envelope to stdout on success
|
|
208
|
-
or failure. It disables interactive selection and takes precedence over
|
|
209
|
-
`--silent`; explicit entity selectors remain valid.
|
|
210
|
-
- Human output is not a machine contract. Do not parse tables, progress text, or
|
|
211
|
-
diagnostic wording.
|
|
212
|
-
- Progress and verbose diagnostics use stderr. Structured command warnings stay
|
|
213
|
-
inside the stdout result. Successful JSON mode does not promise empty stderr
|
|
214
|
-
when `--verbose` is requested.
|
|
215
|
-
- Success, help, and version output exit `0`. Usage errors and every command
|
|
216
|
-
failure exit `1`. Version 1 has no error-specific exit statuses; branch on
|
|
217
|
-
`error.code`.
|
|
218
|
-
- `graph --jsonl` is the one streaming exception. On success it writes a `meta`
|
|
219
|
-
record, node and edge records, and an `end` record rather than an envelope. A
|
|
220
|
-
JSONL failure still writes one error envelope and exits `1`.
|
|
221
|
-
- A command that emits zero machine results succeeds with `result: null`.
|
|
222
|
-
Multiple results are a `PROTOCOL_OUTPUT_ERROR`.
|
|
223
|
-
|
|
224
|
-
### Error Codes
|
|
225
|
-
|
|
226
|
-
| Code | Meaning |
|
|
227
|
-
| ------------------------- | -------------------------------------------------------------- |
|
|
228
|
-
| `CLI_USAGE` | Invalid command, option, argument, or combination |
|
|
229
|
-
| `WORKBASE_NOT_FOUND` | No workbase could be resolved |
|
|
230
|
-
| `WORKBASE_CONFIG_INVALID` | Invalid workbase configuration |
|
|
231
|
-
| `WORKBASE_REGISTRY_ERROR` | Invalid or inaccessible workbase registry |
|
|
232
|
-
| `FILE_NOT_FOUND` | A required path does not exist |
|
|
233
|
-
| `FILESYSTEM_ERROR` | A filesystem operation failed |
|
|
234
|
-
| `FRONTMATTER_INVALID` | Durable document frontmatter is invalid |
|
|
235
|
-
| `VALIDATION_FAILED` | Workbase validation reported issues |
|
|
236
|
-
| `REPOSITORY_ERROR` | Repository operation failed |
|
|
237
|
-
| `EPIC_ERROR` | Epic operation failed |
|
|
238
|
-
| `TASK_ERROR` | Task operation failed |
|
|
239
|
-
| `PHASE_ERROR` | Phase operation failed |
|
|
240
|
-
| `CLAIM_ERROR` | Claim input or lifecycle state is invalid |
|
|
241
|
-
| `CLAIM_CONFLICT` | Active or legacy ownership conflicts with an operation |
|
|
242
|
-
| `REVISION_CONFLICT` | A durable document changed since inspection |
|
|
243
|
-
| `CLAIM_OWNERSHIP` | The session does not own the active claim |
|
|
244
|
-
| `ARCHIVE_ERROR` | Archive or restore operation failed |
|
|
245
|
-
| `WORKTREE_ERROR` | Worktree operation failed |
|
|
246
|
-
| `PULL_REQUEST_ERROR` | Pull request operation failed |
|
|
247
|
-
| `CONTEXT_ERROR` | A context target or required document is invalid |
|
|
248
|
-
| `GRAPH_ERROR` | Graph construction or filtering failed |
|
|
249
|
-
| `EXECUTION_BLOCKED` | Readiness or lifecycle blockers prevent execution |
|
|
250
|
-
| `SYNC_ERROR` | Reconciliation validation, inspection, or provider data failed |
|
|
251
|
-
| `PROCESS_ERROR` | A child process failed |
|
|
252
|
-
| `PROTOCOL_OUTPUT_ERROR` | A command violated the one-result machine contract |
|
|
253
|
-
| `COMMAND_FAILED` | An otherwise unclassified failure |
|
|
254
|
-
|
|
255
|
-
`CLAIM_CONFLICT`, `REVISION_CONFLICT`, and `PROCESS_ERROR` are retryable in the
|
|
256
|
-
v1 metadata. Retryable means new evidence may change the result, not that blind
|
|
257
|
-
or non-idempotent retries are safe. Inspect `fields` and apply `remediation`
|
|
258
|
-
before retrying.
|
|
259
|
-
|
|
260
|
-
## Revisions And Concurrency
|
|
261
|
-
|
|
262
|
-
A document revision is the lowercase SHA-256 hash of the complete Markdown file,
|
|
263
|
-
including frontmatter and prose. It is per document, not a workbase-wide graph
|
|
264
|
-
revision. Context, graph, and entity reads expose revisions.
|
|
265
|
-
|
|
266
|
-
`claim`, `release`, and `finish` require `--revision <sha256>`. They lock and
|
|
267
|
-
recheck the execution document before an atomic replacement, then return
|
|
268
|
-
`previousRevision` and the new `revision`. Use the returned revision or inspect
|
|
269
|
-
again before the next mutation. Claim conflicts include the current revision and
|
|
270
|
-
ownership evidence in `error.fields`; revision conflicts include ownership only
|
|
271
|
-
when claim evidence applies.
|
|
272
|
-
|
|
273
|
-
Structural update, rename, move, and dependency commands accept optional
|
|
274
|
-
`--if-revision <sha256>`. Machine orchestrators should provide it. Multi-document
|
|
275
|
-
mutations recheck every affected file while holding the graph mutation lock.
|
|
276
|
-
|
|
277
|
-
## Selectors And Projections
|
|
278
|
-
|
|
279
|
-
`--workbase <id|name|path>` selects a registered workbase by ID, name, or path;
|
|
280
|
-
an existing path may also resolve an unregistered workbase directly. `--cwd
|
|
281
|
-
<path>` asks Agency to perform target inference as if invoked there. They are
|
|
282
|
-
mutually exclusive. Targeted commands accept `--epic`, `--task`, and `--phase`
|
|
283
|
-
where applicable; phase requires task, and entity selectors cannot be combined
|
|
284
|
-
with a positional target ID. Non-target positional values, such as a status
|
|
285
|
-
outcome, remain valid where the command syntax requires them.
|
|
286
|
-
|
|
287
|
-
`--json`, `--no-input`, and non-TTY execution disable interactive prompts and
|
|
288
|
-
selection. Supply every required value or explicit entity selector. Global
|
|
289
|
-
`--cwd` and `--workbase` selectors apply to `next` as they do to other discovery
|
|
290
|
-
commands.
|
|
291
|
-
|
|
292
|
-
At a workbase root, context defaults to a compact discovery catalog of epics,
|
|
293
|
-
tasks, and phases, includes no writable authority, and provides a hint for
|
|
294
|
-
requesting `--full`. Entity context defaults to the `complete` projection.
|
|
295
|
-
`--compact` omits prose and low-level Git details but retains identity, document
|
|
296
|
-
hashes, authority, paths, graph state, materialization, and validation warnings.
|
|
297
|
-
|
|
298
|
-
Graph projections are opt-in with repeatable
|
|
299
|
-
`--include <bodies|workspace|git|pr>`. Filters such as `--ready`, `--blocked`,
|
|
300
|
-
`--status`, `--repository`, and `--kind` are applied after readiness and graph
|
|
301
|
-
state are computed; returned edges always have both endpoints in the filtered
|
|
302
|
-
node set.
|
|
303
|
-
|
|
304
|
-
## Capability Boundaries
|
|
305
|
-
|
|
306
|
-
- There is no atomic find-ready-and-claim operation. `next` is observational,
|
|
307
|
-
and `claim` does not enforce dependency readiness. Inspect readiness, then
|
|
308
|
-
claim with the observed revision and handle conflicts.
|
|
309
|
-
- There is no `assign` command, remote queue, scheduler, heartbeat, claim renewal,
|
|
310
|
-
runner monitor, or cancellation API. `work` launches one local built-in or
|
|
311
|
-
configured runner without a claim; it is a process-launching, non-JSON flow
|
|
312
|
-
rather than a machine assignment API. External orchestrators claim with
|
|
313
|
-
claimant and runner IDs, then manage their runner themselves.
|
|
314
|
-
- Agency does not edit code, create commits, run repository checks, wait for PR
|
|
315
|
-
checks, merge PRs, or verify that a requested completion condition is true.
|
|
316
|
-
`finish` records the caller's asserted outcome after ownership checks.
|
|
317
|
-
- Reconciliation never discards changes, switches branches, resets reference
|
|
318
|
-
commits, moves conflicting worktrees, chooses among multiple PRs, or bypasses
|
|
319
|
-
active claims. Such conditions remain unresolved for a human or orchestrator.
|
|
320
|
-
- `delegated` is readable legacy state but cannot be newly assigned. `--force`
|
|
321
|
-
only overrides readiness for `work` and `pr create`; it is not general
|
|
322
|
-
reconciliation authority.
|
|
@@ -1,264 +0,0 @@
|
|
|
1
|
-
# Agency Recipes
|
|
2
|
-
|
|
3
|
-
For an entity target, run `agency context . --json` before selecting a recipe.
|
|
4
|
-
At the workbase root, use `agency next --json` or `agency graph --json` to choose
|
|
5
|
-
a target, then inspect it with explicit `--epic`, `--task`, and `--phase`
|
|
6
|
-
selectors or its returned document path. Graph node keys such as `task/<id>` and
|
|
7
|
-
`phase/<task>/<phase>` are not positional context targets.
|
|
8
|
-
|
|
9
|
-
The machine-orchestration forms in the inspect-through-recover recipes are
|
|
10
|
-
captured in `fixtures/protocol/orchestration-recipes.json` and tested against the
|
|
11
|
-
real CLI parser. Their lifecycle behavior is covered by CLI and service fixtures.
|
|
12
|
-
Replace angle-bracket placeholders with values from context or a prior machine
|
|
13
|
-
result; never scrape them from human output.
|
|
14
|
-
|
|
15
|
-
## Initialize A Workbase
|
|
16
|
-
|
|
17
|
-
For an existing local checkout, initialize the workbase and link the repository:
|
|
18
|
-
|
|
19
|
-
```bash
|
|
20
|
-
agency init <workbase-path>
|
|
21
|
-
agency --workbase <workbase-path> repo link <alias> <repository-path>
|
|
22
|
-
agency validate <workbase-path>
|
|
23
|
-
agency --workbase <workbase-path> repo verify <alias>
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
Use `repo add <alias> <remote>` instead when Agency should create and manage a
|
|
27
|
-
bare clone from a remote. Initialization and repository registration require
|
|
28
|
-
explicit user intent.
|
|
29
|
-
|
|
30
|
-
## Restore A Workbase On A New Machine
|
|
31
|
-
|
|
32
|
-
After cloning the tracked workbase, inspect repository setup before applying it:
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
agency repo setup --dry-run --json
|
|
36
|
-
agency repo setup --apply --json
|
|
37
|
-
agency validate
|
|
38
|
-
agency doctor --json
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
Apply clones only declared missing repositories. It does not overwrite linked
|
|
42
|
-
checkouts, repair invalid paths, or choose between drifted remotes. Resolve those
|
|
43
|
-
states explicitly, then rerun setup. A machine may replace an unused managed
|
|
44
|
-
clone with `repo link`; the portable declaration remains available to every
|
|
45
|
-
other machine.
|
|
46
|
-
|
|
47
|
-
## Inspect A Target
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
agency context --task <task-id> --phase <phase-id> --json
|
|
51
|
-
agency worktree inspect <task-id> <phase-id> --json
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
Confirm the target, current document revision, readiness, authority, checkout,
|
|
55
|
-
claim, PR, and validation state. Use `--compact` only when prose and detailed Git
|
|
56
|
-
evidence are not needed.
|
|
57
|
-
|
|
58
|
-
## Find Ready Work
|
|
59
|
-
|
|
60
|
-
Run this from the intended workbase:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
agency next --json
|
|
64
|
-
agency graph --ready --json
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
`next` ranks ready execution units and explains every excluded unit. It does not
|
|
68
|
-
reserve work. Another orchestrator may claim the same candidate before you do,
|
|
69
|
-
so always handle `CLAIM_CONFLICT` or `REVISION_CONFLICT`.
|
|
70
|
-
|
|
71
|
-
## Human: Create And Launch Work
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
agency task create refresh-copy --repo frontend --branch task/refresh-copy --base main
|
|
75
|
-
agency validate
|
|
76
|
-
agency work tasks/refresh-copy
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
For a multi-PR outcome:
|
|
80
|
-
|
|
81
|
-
```bash
|
|
82
|
-
agency task create checkout --multi-phase
|
|
83
|
-
agency phase create checkout api --repo backend --branch task/checkout-api --base main
|
|
84
|
-
agency phase create checkout ui --repo frontend --branch task/checkout-ui \
|
|
85
|
-
--base main --reference backend:main --depends-on api
|
|
86
|
-
agency validate
|
|
87
|
-
agency work tasks/checkout/phases/api
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
`agency work` is intentionally last: it synchronizes managed integration files,
|
|
91
|
-
checks readiness, materializes worktrees, marks this execution unit working
|
|
92
|
-
without a claim, and launches the runner. Run it again to relaunch unclaimed
|
|
93
|
-
working work. The runner opens without a prompt by default; add `--auto` only
|
|
94
|
-
when the generated context prompt should start autonomous execution.
|
|
95
|
-
OpenCode receives whole-workbase visibility through the managed project plugin;
|
|
96
|
-
this does not expand the writable checkout reported by `agency context`.
|
|
97
|
-
|
|
98
|
-
## Active Agent: Execute Assigned Work
|
|
99
|
-
|
|
100
|
-
```bash
|
|
101
|
-
agency context . --json
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
1. Verify context reports the expected execution target, valid structure, and
|
|
105
|
-
the current checkout as `authority.writable.checkoutPath`. Reject dependency
|
|
106
|
-
or validation blockers and conflicting active claims.
|
|
107
|
-
2. Read `TASK.md`, and `PHASE.md` for phase work.
|
|
108
|
-
3. Implement only in the writable checkout; treat all reference checkouts as
|
|
109
|
-
read-only.
|
|
110
|
-
4. Run repository formatting, checks, build, and focused tests.
|
|
111
|
-
5. Review and commit the diff.
|
|
112
|
-
6. If requested, run `agency validate`, then
|
|
113
|
-
`agency pr create <task-id> [phase-id]`.
|
|
114
|
-
7. Finish an active claim after its completion condition is true; otherwise set
|
|
115
|
-
the task or phase status directly.
|
|
116
|
-
|
|
117
|
-
Never invoke `agency work` merely because an execution checkout already exists;
|
|
118
|
-
that would start another agent rather than continue the current assignment.
|
|
119
|
-
|
|
120
|
-
## Claim Ready Work
|
|
121
|
-
|
|
122
|
-
Get the current document revision from context. Use stable claimant, runner, and
|
|
123
|
-
session IDs:
|
|
124
|
-
|
|
125
|
-
```bash
|
|
126
|
-
agency claim checkout ui \
|
|
127
|
-
--claimant orchestrator-1 --runner opencode --session-id session-123 \
|
|
128
|
-
--revision <sha256> --json
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
Claim records ownership and sets status to `working`; it does not launch a runner
|
|
132
|
-
or recheck dependency readiness. A machine orchestrator must launch and monitor
|
|
133
|
-
its runner separately. There is no atomic find-and-claim or `assign` command.
|
|
134
|
-
|
|
135
|
-
## Prepare Checkouts
|
|
136
|
-
|
|
137
|
-
Preview and then materialize without claiming, launching, or changing status:
|
|
138
|
-
|
|
139
|
-
```bash
|
|
140
|
-
agency work prepare --task checkout --phase ui --dry-run --json
|
|
141
|
-
agency work prepare --task checkout --phase ui --json
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
Use the returned checkout paths and resolved commits. Do not create or move
|
|
145
|
-
worktrees manually.
|
|
146
|
-
|
|
147
|
-
## Assign A Runner
|
|
148
|
-
|
|
149
|
-
For a human-operated local launch, Agency combines readiness checks, prepare,
|
|
150
|
-
status mutation, and runner launch without creating a claim:
|
|
151
|
-
|
|
152
|
-
```bash
|
|
153
|
-
agency work tasks/checkout/phases/ui --runner opencode
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
This is not a JSON assignment API. An external orchestrator instead claims with
|
|
157
|
-
its own `claimant`, `runner`, and `session-id`, starts the runner outside Agency,
|
|
158
|
-
and passes it the target and claim result. Agency has no queue, heartbeat,
|
|
159
|
-
monitoring, cancellation, or automatic claim-renewal service.
|
|
160
|
-
|
|
161
|
-
## Reconcile Durable And Local State
|
|
162
|
-
|
|
163
|
-
```bash
|
|
164
|
-
agency sync --dry-run --json
|
|
165
|
-
agency sync --apply --json
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
The first command is observational. Apply may materialize an unconflicted missing
|
|
169
|
-
checkout, release an expired claim, record one unambiguous matching PR, or mark
|
|
170
|
-
unclaimed work done after its authoritative PR merges. Review `warnings` and
|
|
171
|
-
`unresolved`; apply never discards or resets work and never chooses among
|
|
172
|
-
ambiguous PRs.
|
|
173
|
-
|
|
174
|
-
## Release Interrupted Work
|
|
175
|
-
|
|
176
|
-
After every claim mutation, use the returned revision or inspect again. Release
|
|
177
|
-
interrupted work back to open:
|
|
178
|
-
|
|
179
|
-
```bash
|
|
180
|
-
agency release checkout ui --session-id session-123 \
|
|
181
|
-
--revision <current-sha256> --json
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
## Finish Verified Work
|
|
185
|
-
|
|
186
|
-
After the claimed run completes successfully:
|
|
187
|
-
|
|
188
|
-
```bash
|
|
189
|
-
agency finish checkout ui --session-id session-123 \
|
|
190
|
-
--revision <current-sha256> --outcome done --json
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
Do not substitute a phase status mutation for `finish`; `finish` preserves
|
|
194
|
-
ownership history and revision safety. A `done` claim outcome leaves unmerged
|
|
195
|
-
execution work `working`. After the authoritative pull request merges, use
|
|
196
|
-
`agency sync --apply` to reconcile the execution unit to `done`.
|
|
197
|
-
|
|
198
|
-
## Create A Pull Request
|
|
199
|
-
|
|
200
|
-
```bash
|
|
201
|
-
agency validate
|
|
202
|
-
agency pr create checkout ui --json
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
Agency materializes a missing workspace, then requires the writable worktree to
|
|
206
|
-
be clean. It pushes the declared branch, invokes the configured delivery
|
|
207
|
-
provider's create command or falls back to `gh pr create --fill`, and records the
|
|
208
|
-
returned pull request record. Do not manually write a URL or record if creation
|
|
209
|
-
fails. A PR being open is not equivalent to completion when the assigned outcome
|
|
210
|
-
requires merge.
|
|
211
|
-
|
|
212
|
-
Agency does not create commits, run tests, wait for checks, merge the PR, or
|
|
213
|
-
verify completion. Those remain orchestrator responsibilities.
|
|
214
|
-
|
|
215
|
-
## Convert A Task To Phases
|
|
216
|
-
|
|
217
|
-
Name the phase that inherits the existing task's execution metadata:
|
|
218
|
-
|
|
219
|
-
```bash
|
|
220
|
-
agency phase create refresh-copy verification \
|
|
221
|
-
--first-phase implementation \
|
|
222
|
-
--repo frontend --branch task/refresh-copy-verification --base main \
|
|
223
|
-
--depends-on implementation
|
|
224
|
-
agency validate
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
Agency converts the task shape, creates both phase documents, and relocates
|
|
228
|
-
materialized worktrees. Do not perform those moves manually.
|
|
229
|
-
|
|
230
|
-
## Recover From Interrupted State
|
|
231
|
-
|
|
232
|
-
Inspect before applying changes:
|
|
233
|
-
|
|
234
|
-
```bash
|
|
235
|
-
agency doctor --json
|
|
236
|
-
agency sync --dry-run --json
|
|
237
|
-
agency worktree inspect <task-id> [phase-id] --json
|
|
238
|
-
agency worktree repair <task-id> [phase-id] --dry-run --json
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
Use `agency sync --apply` only with explicit user intent. It may safely
|
|
242
|
-
materialize an unconflicted missing checkout, release an expired claim, record a
|
|
243
|
-
single matching PR, refresh recorded PR state and mergeability, or mark work done
|
|
244
|
-
after its authoritative PR merged and no claim remains. It never modifies dirty
|
|
245
|
-
checkouts, switches branches, resets
|
|
246
|
-
references, chooses among PRs, or bypasses active claims.
|
|
247
|
-
|
|
248
|
-
For a worktree-specific issue, use `worktree repair --dry-run` before repair.
|
|
249
|
-
Repair is conservative and never discards work. Use remove or rebuild only after
|
|
250
|
-
reviewing the dry run and confirming every checkout is clean.
|
|
251
|
-
|
|
252
|
-
## Archive Or Restore
|
|
253
|
-
|
|
254
|
-
```bash
|
|
255
|
-
agency archive phase checkout ui --dry-run --json
|
|
256
|
-
agency archive phase checkout ui
|
|
257
|
-
agency restore phase checkout ui --dry-run --json
|
|
258
|
-
agency restore phase checkout ui
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
As an operating policy, archive only terminal work and only with explicit intent;
|
|
262
|
-
the CLI also permits safe archival of nonterminal work. Agency preserves the
|
|
263
|
-
branch and lifecycle provenance while enforcing graph, worktree, and destination
|
|
264
|
-
safety. Never move archived directories by hand.
|
|
@@ -1,48 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Operate Agency work with safe start, status, next, validate, and finish workflows
|
|
3
|
-
---
|
|
4
|
-
|
|
5
|
-
Operate the current Agency workbase using the managed Agency instructions.
|
|
6
|
-
|
|
7
|
-
Invocation inputs:
|
|
8
|
-
|
|
9
|
-
- Workflow: `$1`
|
|
10
|
-
- Optional target: `$2`
|
|
11
|
-
- Complete request: `$ARGUMENTS`
|
|
12
|
-
|
|
13
|
-
Use `status` when the workflow is empty. Treat words after the optional target as
|
|
14
|
-
additional user instructions. If the workflow is unknown, make no changes and
|
|
15
|
-
list the supported workflows.
|
|
16
|
-
|
|
17
|
-
Always follow these rules:
|
|
18
|
-
|
|
19
|
-
- Run `agency context . --json` first when no target is provided. With a target,
|
|
20
|
-
pass that target to `agency context` instead.
|
|
21
|
-
- Use the returned document paths, readiness, authority, checkout state, claim,
|
|
22
|
-
and validation result. Do not infer them from directory names.
|
|
23
|
-
- Stop on validation errors, dependency blockers, an unexpected writable
|
|
24
|
-
repository, or a conflicting active claim.
|
|
25
|
-
- Write code only in `authority.writable.checkoutPath`; references are read-only.
|
|
26
|
-
- Never run `agency work` to start the current agent again.
|
|
27
|
-
- Create a pull request only when the complete request explicitly asks for one.
|
|
28
|
-
|
|
29
|
-
Dispatch the workflow as follows:
|
|
30
|
-
|
|
31
|
-
- `start`: Read the returned task and phase documents, inspect the writable
|
|
32
|
-
checkout, then begin or resume the requested work in this session. Keep durable
|
|
33
|
-
decisions current and carry the work through focused verification.
|
|
34
|
-
- `status`: Make no changes. Summarize the target, readiness, authority, durable
|
|
35
|
-
status, claim and PR state, checkout state, current Git changes, blockers, and
|
|
36
|
-
the most useful next action.
|
|
37
|
-
- `next`: Run `agency next --json`, summarize ready and blocked execution units,
|
|
38
|
-
and recommend the highest-priority ready unit. Do not launch another agent.
|
|
39
|
-
- `validate`: Run Agency validation for the discovered workbase. Explain every
|
|
40
|
-
issue and, when safe and within authority, repair requested non-structural
|
|
41
|
-
problems before validating again.
|
|
42
|
-
- `finish`: Complete any remaining requested implementation first. Run focused
|
|
43
|
-
repository checks, refresh the task or phase delivery context, and run
|
|
44
|
-
`agency validate`. Finish an active claim with its current revision; otherwise
|
|
45
|
-
update unclaimed status only when the requested outcome and delivery work are
|
|
46
|
-
actually complete. Do not create a PR unless explicitly requested.
|
|
47
|
-
- `help`: Make no changes. Briefly explain these workflows and the positional
|
|
48
|
-
form `/agency <workflow> [target] [additional instructions]`.
|
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
import { createHash } from "node:crypto"
|
|
2
|
-
import commandTemplate from "./AGENCY_COMMAND.md" with { type: "text" }
|
|
3
|
-
|
|
4
|
-
const managedHeaderPattern =
|
|
5
|
-
/^---\r?\n# agency-managed: sha256=([a-f0-9]{64})\r?\n/
|
|
6
|
-
|
|
7
|
-
const checksum = (content: string) =>
|
|
8
|
-
createHash("sha256").update(content).digest("hex")
|
|
9
|
-
|
|
10
|
-
const canonicalBody = commandTemplate.endsWith("\n")
|
|
11
|
-
? commandTemplate
|
|
12
|
-
: `${commandTemplate}\n`
|
|
13
|
-
|
|
14
|
-
const renderManagedWorkbaseOpencodeCommand = (
|
|
15
|
-
content: string = canonicalBody,
|
|
16
|
-
) =>
|
|
17
|
-
content.replace(
|
|
18
|
-
/^---\n/,
|
|
19
|
-
`---\n# agency-managed: sha256=${checksum(content)}\n`,
|
|
20
|
-
)
|
|
21
|
-
|
|
22
|
-
export const managedWorkbaseOpencodeCommand =
|
|
23
|
-
renderManagedWorkbaseOpencodeCommand()
|
|
24
|
-
|
|
25
|
-
export const canUpdateManagedWorkbaseOpencodeCommand = (content: string) => {
|
|
26
|
-
const match = content.match(managedHeaderPattern)
|
|
27
|
-
if (!match?.[1]) return false
|
|
28
|
-
|
|
29
|
-
return checksum(content.replace(managedHeaderPattern, "---\n")) === match[1]
|
|
30
|
-
}
|