@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.
@@ -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
- }