codeassembly-guidance 0.4.0 → 0.6.0
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/.meta/changelog.json +635 -280
- package/CHANGELOG.md +89 -0
- package/README.md +55 -19
- package/content/_partials/finding-grades.md +4 -0
- package/content/_partials/guidance-change-since-capture.md +1 -1
- package/content/codeassembly-content.yaml +2 -0
- package/content/collections/recommended.md +6 -3
- package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
- package/content/guidance/rulebooks/cli-conventions.md +17 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
- package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +4 -2
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +68 -68
- package/content/skills/_data/action-items.md +2 -2
- package/content/skills/_data/artifact-conventions.md +22 -431
- package/content/skills/_data/concision.md +1 -1
- package/content/skills/_data/entry-points.md +37 -0
- package/content/skills/_data/recommendation-gradient.md +6 -6
- package/content/skills/_data/spike-conventions.md +13 -3
- package/content/skills/_data/ticket-source-resolution.md +21 -4
- package/content/skills/_data/title-templates.md +4 -4
- package/content/skills/_partials/commit-title-rendering.md +2 -1
- package/content/skills/_partials/next-steps-after-plan.md +4 -3
- package/content/skills/_partials/option-format.md +8 -8
- package/content/skills/_partials/plan-template.md +4 -2
- package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
- package/content/skills/_partials/split-launch-prompts.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -1
- package/content/skills/analyze-performance/SKILL.md +102 -0
- package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
- package/content/skills/assess-code-health/SKILL.md +16 -14
- package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
- package/content/skills/assess-usability/SKILL.md +5 -3
- package/content/skills/convert-agent-prompt/SKILL.md +60 -0
- package/content/skills/create-commit/SKILL.md +10 -5
- package/content/skills/create-pr/SKILL.md +11 -11
- package/content/skills/create-ticket/SKILL.md +1 -0
- package/content/skills/design-and-plan/SKILL.md +2 -2
- package/content/skills/implement-plan/SKILL.md +1 -28
- package/content/skills/index-prototypes/SKILL.md +36 -17
- package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
- package/content/skills/investigate-spike/SKILL.md +48 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
- package/content/skills/refine-guidance/SKILL.md +1 -1
- package/content/skills/refine-plan/SKILL.md +7 -4
- package/content/skills/refine-prototype/SKILL.md +5 -5
- package/content/skills/review-branch/SKILL.md +7 -7
- package/content/skills/review-criteria/SKILL.md +3 -3
- package/content/skills/review-gh-pr/SKILL.md +1 -1
- package/content/skills/revise-prose/SKILL.md +9 -8
- package/content/skills/revise-prose/revise-prose.mjs +2 -2
- package/content/skills/save-artifact/SKILL.md +1 -1
- package/content/skills/start-ticket/SKILL.md +27 -0
- package/content/skills/summarize-change/SKILL.md +17 -9
- package/content/skills/testing-conventions/SKILL.md +12 -1
- package/content/skills/triage-feedback/SKILL.md +1 -1
- package/content/skills/triage-spike-findings/SKILL.md +31 -12
- package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
- package/content/subagents/_data/claude.yaml +3 -0
- package/content/subagents/code-health-assessor.md +4 -4
- package/content/subagents/disposition-challenger.md +3 -4
- package/content/subagents/entry-drafter.md +2 -2
- package/content/subagents/feedback-triage-challenger.md +1 -1
- package/content/subagents/handoff-reviewer.md +1 -1
- package/content/subagents/plan-reviewer.md +8 -7
- package/content/subagents/prototype-builder.md +69 -0
- package/content/subagents/usability-assessor.md +1 -1
- package/package.json +8 -7
- package/schemas/preferences.v1.json +1 -1
- package/schemas/work-types.v1.json +1 -1
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
|
@@ -8,7 +8,7 @@ The render contract comes first; the doctrine behind it follows. Skills that clo
|
|
|
8
8
|
|
|
9
9
|
## Sweep before sending
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
This convention prevents an ask that the agent never recognized as an ask, and to which the formatting rules therefore never applied. Before ending a turn, scan the draft for anything that invites a response and move every hit into the block.
|
|
12
12
|
|
|
13
13
|
Soft offers are the hardest form to spot. Each phrases a question as a statement:
|
|
14
14
|
|
|
@@ -25,7 +25,7 @@ Soft offers are the hardest form to spot. Each phrases a question as a statement
|
|
|
25
25
|
|
|
26
26
|
Each is an action item. Restate it in the block as the concrete action that it proposes, and strike the offer from the prose. The observation that prompted it may stay; that is signal. The ask may not.
|
|
27
27
|
|
|
28
|
-
The sweep runs in both directions. Having moved every ask into the block, read the block back and ask of each item whether it is really a question: An item whose answer follows from evidence that the agent already
|
|
28
|
+
The sweep runs in both directions. Having moved every ask into the block, read the block back and ask of each item whether it is really a question: An item whose answer follows from evidence that the agent already has is a decision that it declined to make, and handing it back makes the user evaluate what a clause would have stated. Strike it, state the decision in the prose with its reason, and leave the block to the items that only the user can settle. An item that the agent could perform is a step that it declined to take: Run it, and leave in the block only the part that the agent cannot perform, named with its reason. A plan's "the owner exercises `/lab/book-row` by keyboard and on a touch device" is the counterexample: The agent drives the route through a debug browser, and the block contains at most how the control feels on a physical phone. A block emptied this way is a turn without an ask, which is a report rather than a failure.
|
|
29
29
|
|
|
30
30
|
An overload signal from the user, such as "I can't do this any more" or a count of the commands that they have run, empties the block in every turn until the user asks for something; the "Prompt formatting" section of the collaboration preferences states the rule.
|
|
31
31
|
|
|
@@ -4,7 +4,7 @@ Standards for AI-generated artifact storage, naming, and lifecycle.
|
|
|
4
4
|
|
|
5
5
|
## Purpose
|
|
6
6
|
|
|
7
|
-
The artifact directory is the developer's audit trail of development. Its plans, reviews, change summaries, pull-request and merge records, devlogs, and chat summaries record what an agent produced and when, each as it
|
|
7
|
+
The artifact directory is the developer's audit trail of development. Its plans, reviews, change summaries, pull-request and merge records, devlogs, and chat summaries record what an agent produced and when, each as it was at the moment of writing (see [Mutability](#mutability)). The directory is not a source of truth, and it is not a home for durable content:
|
|
8
8
|
|
|
9
9
|
- **Durable content.** Put instructions, a procedure, or a reference that a later session must find in the repository (its docs, `AGENTS.md`, or a README), or in a skill or rulebook when they apply across repositories. A later session looks there, not in the artifact directory.
|
|
10
10
|
- **Authority.** An artifact is not authority on the current state of code, design, or decisions. Treat what a search of artifacts turns up as history, and verify it against the repository, the tickets, and the pull requests.
|
|
@@ -33,6 +33,9 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
|
|
|
33
33
|
│ │ ├── sense.json
|
|
34
34
|
│ │ ├── {lens}/report.md
|
|
35
35
|
│ │ └── {lens}/proposals.json
|
|
36
|
+
│ ├── performance/ ← a performance analysis's measurements and summary, kept by `analyze-performance`
|
|
37
|
+
│ │ ├── summary.json
|
|
38
|
+
│ │ └── raw/ ← the helper's run directory: `manifest.json` and each page's raw responses
|
|
36
39
|
│ ├── triage/ ← a findings triage's working files, kept by `triage-spike-findings`
|
|
37
40
|
│ │ ├── findings.md
|
|
38
41
|
│ │ ├── inventory.md
|
|
@@ -86,6 +89,10 @@ A `project.ticket_ref_prefix` other than `#` is part of the ticket ID, so it nam
|
|
|
86
89
|
|
|
87
90
|
`code-health/` contains the working files of the ticket's code-health assessment: the sense document with each check's log beside it, the test reports that the sensors read, each lens's report and checked proposals, and the merged proposals. The `code-health-findings` artifact cites code by paths relative to the repository root, so it does not depend on these files; they record what the run measured.
|
|
88
91
|
|
|
92
|
+
### Performance measurements
|
|
93
|
+
|
|
94
|
+
`performance/` contains the working files of the ticket's performance analysis: `raw/`, the run directory that the `analyze-performance` helper writes, with its manifest and every PSI response, Lighthouse report, and CrUX record, and `summary.json`, the helper's summary of that directory. The `performance-findings` artifact cites raw files by paths relative to the ticket directory, so the measurements stay in the ticket directory.
|
|
95
|
+
|
|
89
96
|
### Triage working files
|
|
90
97
|
|
|
91
98
|
`triage/` contains the working files of a triage of the ticket's findings: a local copy of the findings when they came from an artifact URL, the inventory, the recommendations that the challenger reads, the challenger's reply, the dispositions record from which the `dispositions` artifact is rendered, and the comments rendered from that record: `preview/` with placeholders for the confirmation, `rendered/` with every number for posting. The record stays here as a working file; the artifact is the rendered text.
|
|
@@ -183,8 +190,6 @@ When the ticket directory already contains artifacts for this change, reuse thei
|
|
|
183
190
|
|
|
184
191
|
Underscore separates all structural parts. Hyphens are free for use within any part (role names, artifact names, slugs).
|
|
185
192
|
|
|
186
|
-
Each role has a **roleType** classifying its workflow function. See the [roleType taxonomy](#roletype-taxonomy) in the run-index.json section below.
|
|
187
|
-
|
|
188
193
|
Artifact ordering follows the timestamp prefix.
|
|
189
194
|
|
|
190
195
|
Example run directory (a review, the author's response, and a re-review):
|
|
@@ -232,7 +237,7 @@ Keys inside the `provenance:` block use **camelCase** (e.g., `baseSha`, `isInter
|
|
|
232
237
|
|
|
233
238
|
### Field definitions
|
|
234
239
|
|
|
235
|
-
The table below lists only the universal fields. Artifact-specific extensions (`provenance.iteration`, `session_type`, `tickets_created`, `title`, `scope`, `type`, `responding_to`, etc.) are documented in the per-artifact sections below.
|
|
240
|
+
The table below lists only the universal fields. Artifact-specific extensions (`provenance.iteration`, `provenance.parent`, `session_type`, `tickets_created`, `title`, `scope`, `type`, `responding_to`, etc.) are documented in the per-artifact sections below.
|
|
236
241
|
|
|
237
242
|
| Field | Required | Description |
|
|
238
243
|
| -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -263,7 +268,7 @@ The table below lists only the universal fields. Artifact-specific extensions (`
|
|
|
263
268
|
|
|
264
269
|
Most skills and subagents produce frontmatter by running `resolve-frontmatter.sh` in its default YAML mode and prepending the output verbatim. Two sites are deliberate exceptions and compose the YAML block themselves:
|
|
265
270
|
|
|
266
|
-
- `refine-plan`: The `provenance:` block is case-branched on the input artifact's existing provenance (preserving `skill`, `baseSha`, `isInteractive`, and `iteration` from the original authoring skill, with fallbacks when the input does not have provenance). The shell flag surface cannot express this conditional logic cleanly.
|
|
271
|
+
- `refine-plan`: The `provenance:` block is case-branched on the input artifact's existing provenance (preserving `skill`, `baseSha`, `isInteractive`, and `iteration` from the original authoring skill, with fallbacks when the input does not have provenance), and `parent` is set from the input's file name. The shell flag surface cannot express this conditional logic cleanly.
|
|
267
272
|
- `wrap-up` (deferred-findings artifact): `tickets_created` is a list of `{id, items}` objects, a structure that does not have a clean CLI expression and is best composed in the skill's own logic.
|
|
268
273
|
|
|
269
274
|
Both read the script's JSON output and write the YAML frontmatter themselves. The pattern is intentional, not a workaround; keep new skills on the YAML mode path unless they have a similarly structural reason to deviate.
|
|
@@ -286,11 +291,12 @@ When authoring a new skill that needs session-context fields: Invoke the bundled
|
|
|
286
291
|
|
|
287
292
|
## Plan provenance
|
|
288
293
|
|
|
289
|
-
This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific
|
|
294
|
+
This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extensions:
|
|
290
295
|
|
|
291
|
-
| Field | Required | Description
|
|
292
|
-
| ---------------------- | -------- |
|
|
293
|
-
| `provenance.iteration` | no | Refinement iteration counter. Absent on first authoring; set to `2` on first refinement, incremented on subsequent refinements.
|
|
296
|
+
| Field | Required | Description |
|
|
297
|
+
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
298
|
+
| `provenance.iteration` | no | Refinement iteration counter. Absent on first authoring; set to `2` on first refinement, incremented on subsequent refinements. |
|
|
299
|
+
| `provenance.parent` | no | File name of the plan that this plan was revised from. Absent on first authoring; set by `refine-plan` on every revision and never carried forward, so that each revision names its own predecessor. |
|
|
294
300
|
|
|
295
301
|
Plan-specific `provenance.skill` values include `design-and-plan`, `plan`, `plan-mode`, and `unknown` (when the authoring skill cannot be determined). `refinedBy` is the skill that last processed the plan (typically `refine-plan`).
|
|
296
302
|
|
|
@@ -365,372 +371,9 @@ This artifact uses the [universal artifact frontmatter](#universal-artifact-fron
|
|
|
365
371
|
|
|
366
372
|
`align-ticket-with-implementation`, `create-ticket`, and `design-and-plan` write the field, each from what it already knows at save time about that agreement; each states its own condition. All three emit it through the frontmatter script's `--extra copies_remote=true` flag, the extension surface that the consumer fields above already use.
|
|
367
373
|
|
|
368
|
-
##
|
|
369
|
-
|
|
370
|
-
Machine-readable metadata for a run directory. The retired orchestration engine wrote it; the current skills do not. `run-core` parses it.
|
|
371
|
-
|
|
372
|
-
Every example and value list in this section and in [V3 format](#v3-format-event-sourced-runs) describes runs written by the retired engine, so its roles, agents, phases, and modes are historical values.
|
|
373
|
-
|
|
374
|
-
### Schema
|
|
375
|
-
|
|
376
|
-
> **Note:** The following examples show v2 format. The engine's last runs use v3 (event-sourced) -- see the [V3 format](#v3-format-event-sourced-runs) section below.
|
|
377
|
-
|
|
378
|
-
**Initial write** (at run start):
|
|
379
|
-
|
|
380
|
-
```json
|
|
381
|
-
{
|
|
382
|
-
"version": 2,
|
|
383
|
-
"context": {
|
|
384
|
-
"runId": "20260221-034100Z-orchestrated",
|
|
385
|
-
"projectSlug": "williamthorsen-configs-macos",
|
|
386
|
-
"ticketId": "MAC-68",
|
|
387
|
-
"projectRoot": "/Users/william/repos/configs/macos",
|
|
388
|
-
"branch": "mac-68/feat/improve-artifact-naming",
|
|
389
|
-
"task": "Implement artifact naming improvements",
|
|
390
|
-
"startedAt": "2026-02-21T03:41:00Z",
|
|
391
|
-
"completedAt": null,
|
|
392
|
-
"status": "in_progress",
|
|
393
|
-
"phases": {},
|
|
394
|
-
"phaseDecisions": {}
|
|
395
|
-
},
|
|
396
|
-
"config": {
|
|
397
|
-
"pipeline": ["architecture", "planning", "implementation", "review-cycle"],
|
|
398
|
-
"externalPlan": false,
|
|
399
|
-
"mergeBaseSha": "abc1234",
|
|
400
|
-
"diffBase": "main",
|
|
401
|
-
"maxReviewRounds": 3,
|
|
402
|
-
"effort": "medium",
|
|
403
|
-
"approvalThreshold": "medium",
|
|
404
|
-
"budgetThreshold": "medium",
|
|
405
|
-
"mode": "orchestrated",
|
|
406
|
-
"model": "claude-opus-4-6"
|
|
407
|
-
},
|
|
408
|
-
"artifacts": []
|
|
409
|
-
}
|
|
410
|
-
```
|
|
411
|
-
|
|
412
|
-
**Final state** (at run completion):
|
|
413
|
-
|
|
414
|
-
```json
|
|
415
|
-
{
|
|
416
|
-
"version": 2,
|
|
417
|
-
"context": {
|
|
418
|
-
"runId": "20260221-034100Z-orchestrated",
|
|
419
|
-
"projectSlug": "williamthorsen-configs-macos",
|
|
420
|
-
"ticketId": "MAC-68",
|
|
421
|
-
"projectRoot": "/Users/william/repos/configs/macos",
|
|
422
|
-
"branch": "mac-68/feat/improve-artifact-naming",
|
|
423
|
-
"task": "Implement artifact naming improvements",
|
|
424
|
-
"startedAt": "2026-02-21T03:41:00Z",
|
|
425
|
-
"completedAt": "2026-02-21T04:16:00Z",
|
|
426
|
-
"status": "completed",
|
|
427
|
-
"phaseDecisions": {
|
|
428
|
-
"architecture": { "run": true, "disposition": "executed", "reason": "External plan requires validation" },
|
|
429
|
-
"planning": { "run": true, "disposition": "executed", "reason": "External plan present" },
|
|
430
|
-
"implementation": { "run": true, "disposition": "executed" },
|
|
431
|
-
"review-cycle": { "run": true, "disposition": "executed" },
|
|
432
|
-
"parallelReview": { "run": true, "disposition": "executed" },
|
|
433
|
-
"codeSimplifier": { "run": true, "disposition": "executed" },
|
|
434
|
-
"holisticReview": { "run": true, "disposition": "executed" }
|
|
435
|
-
},
|
|
436
|
-
"phases": {
|
|
437
|
-
"architecture": {
|
|
438
|
-
"status": "completed",
|
|
439
|
-
"impactLevel": "moderate",
|
|
440
|
-
"startedAt": "2026-02-21T03:41:30Z",
|
|
441
|
-
"completedAt": "2026-02-21T03:42:00Z"
|
|
442
|
-
},
|
|
443
|
-
"planning": {
|
|
444
|
-
"status": "completed",
|
|
445
|
-
"stepCount": 5,
|
|
446
|
-
"startedAt": "2026-02-21T03:42:10Z",
|
|
447
|
-
"completedAt": "2026-02-21T03:43:00Z"
|
|
448
|
-
},
|
|
449
|
-
"implementation": {
|
|
450
|
-
"status": "completed",
|
|
451
|
-
"startedAt": "2026-02-21T03:43:10Z",
|
|
452
|
-
"completedAt": "2026-02-21T03:45:00Z"
|
|
453
|
-
},
|
|
454
|
-
"parallelReview": {
|
|
455
|
-
"status": "completed",
|
|
456
|
-
"startedAt": "2026-02-21T03:45:10Z",
|
|
457
|
-
"completedAt": "2026-02-21T04:10:00Z",
|
|
458
|
-
"aggregatedCriticality": "medium",
|
|
459
|
-
"reviewers": {
|
|
460
|
-
"reviewer": {
|
|
461
|
-
"status": "completed",
|
|
462
|
-
"criticality": "medium",
|
|
463
|
-
"reReviewCriticality": "low",
|
|
464
|
-
"startedAt": "2026-02-21T03:45:10Z",
|
|
465
|
-
"completedAt": "2026-02-21T03:47:00Z"
|
|
466
|
-
},
|
|
467
|
-
"silent-failure-reviewer": {
|
|
468
|
-
"status": "completed",
|
|
469
|
-
"criticality": "low",
|
|
470
|
-
"startedAt": "2026-02-21T03:45:10Z",
|
|
471
|
-
"completedAt": "2026-02-21T03:47:00Z"
|
|
472
|
-
},
|
|
473
|
-
"test-reviewer": { "status": "skipped", "reason": "no source or test files changed" },
|
|
474
|
-
"code-reviewer": {
|
|
475
|
-
"status": "completed",
|
|
476
|
-
"criticality": "medium",
|
|
477
|
-
"reReviewCriticality": "none",
|
|
478
|
-
"startedAt": "2026-02-21T03:45:10Z",
|
|
479
|
-
"completedAt": "2026-02-21T03:47:00Z"
|
|
480
|
-
}
|
|
481
|
-
},
|
|
482
|
-
"coderFixCycleRan": true,
|
|
483
|
-
"selectiveReReview": {
|
|
484
|
-
"ran": true,
|
|
485
|
-
"reviewersDispatched": ["reviewer", "code-reviewer"],
|
|
486
|
-
"additionalFixCycleRan": false
|
|
487
|
-
},
|
|
488
|
-
"iterations": [
|
|
489
|
-
{
|
|
490
|
-
"reviewers": ["reviewer", "silent-failure-reviewer", "code-reviewer"],
|
|
491
|
-
"dispatchedAt": "2026-02-21T03:45:10Z",
|
|
492
|
-
"reviewsCompletedAt": "2026-02-21T03:47:00Z",
|
|
493
|
-
"coderFixStartedAt": "2026-02-21T03:47:30Z",
|
|
494
|
-
"coderFixCompletedAt": "2026-02-21T04:00:00Z"
|
|
495
|
-
},
|
|
496
|
-
{
|
|
497
|
-
"reviewers": ["reviewer", "code-reviewer"],
|
|
498
|
-
"dispatchedAt": "2026-02-21T04:00:30Z",
|
|
499
|
-
"reviewsCompletedAt": "2026-02-21T04:10:00Z"
|
|
500
|
-
}
|
|
501
|
-
]
|
|
502
|
-
},
|
|
503
|
-
"codeSimplifier": {
|
|
504
|
-
"status": "completed",
|
|
505
|
-
"ran": true,
|
|
506
|
-
"actionableFindings": true,
|
|
507
|
-
"coderFixCycleRan": true,
|
|
508
|
-
"startedAt": "2026-02-21T04:10:10Z",
|
|
509
|
-
"completedAt": "2026-02-21T04:12:00Z"
|
|
510
|
-
},
|
|
511
|
-
"holisticReview": {
|
|
512
|
-
"status": "completed",
|
|
513
|
-
"criticality": "none",
|
|
514
|
-
"startedAt": "2026-02-21T04:12:10Z",
|
|
515
|
-
"completedAt": "2026-02-21T04:15:00Z"
|
|
516
|
-
}
|
|
517
|
-
}
|
|
518
|
-
},
|
|
519
|
-
"config": {
|
|
520
|
-
"pipeline": ["architecture", "planning", "implementation", "review-cycle"],
|
|
521
|
-
"externalPlan": false,
|
|
522
|
-
"mergeBaseSha": "abc1234",
|
|
523
|
-
"diffBase": "main",
|
|
524
|
-
"maxReviewRounds": 3,
|
|
525
|
-
"effort": "medium",
|
|
526
|
-
"approvalThreshold": "medium",
|
|
527
|
-
"budgetThreshold": "medium",
|
|
528
|
-
"mode": "orchestrated",
|
|
529
|
-
"model": "claude-opus-4-6"
|
|
530
|
-
},
|
|
531
|
-
"artifacts": [
|
|
532
|
-
{
|
|
533
|
-
"filename": "01_orchestrator_run-manifest.md",
|
|
534
|
-
"role": "orchestrator",
|
|
535
|
-
"roleType": "orchestrator",
|
|
536
|
-
"agent": "orchestrator",
|
|
537
|
-
"type": "run-manifest",
|
|
538
|
-
"phase": "initialization",
|
|
539
|
-
"createdAt": "2026-02-21T03:41:00Z"
|
|
540
|
-
},
|
|
541
|
-
{
|
|
542
|
-
"filename": "02_architect_architecture.md",
|
|
543
|
-
"role": "architect",
|
|
544
|
-
"roleType": "analyst",
|
|
545
|
-
"agent": "orchestrated-architect",
|
|
546
|
-
"type": "architecture",
|
|
547
|
-
"phase": "architecture",
|
|
548
|
-
"createdAt": "2026-02-21T03:42:00Z"
|
|
549
|
-
},
|
|
550
|
-
{
|
|
551
|
-
"filename": "03_planner_orchestration-plan.md",
|
|
552
|
-
"role": "planner",
|
|
553
|
-
"roleType": "planner",
|
|
554
|
-
"agent": "orchestrated-planner",
|
|
555
|
-
"type": "orchestration-plan",
|
|
556
|
-
"phase": "planning",
|
|
557
|
-
"createdAt": "2026-02-21T03:43:00Z"
|
|
558
|
-
},
|
|
559
|
-
{
|
|
560
|
-
"filename": "04_coder_change-summary.md",
|
|
561
|
-
"role": "coder",
|
|
562
|
-
"roleType": "author",
|
|
563
|
-
"agent": "orchestrated-coder",
|
|
564
|
-
"type": "change-summary",
|
|
565
|
-
"phase": "implementation",
|
|
566
|
-
"createdAt": "2026-02-21T03:45:00Z"
|
|
567
|
-
},
|
|
568
|
-
{
|
|
569
|
-
"filename": "05_reviewer_review.md",
|
|
570
|
-
"role": "reviewer",
|
|
571
|
-
"roleType": "reviewer",
|
|
572
|
-
"agent": "orchestrated-reviewer",
|
|
573
|
-
"type": "review",
|
|
574
|
-
"phase": "parallelReview",
|
|
575
|
-
"createdAt": "2026-02-21T03:47:00Z",
|
|
576
|
-
"iteration": 1
|
|
577
|
-
},
|
|
578
|
-
{
|
|
579
|
-
"filename": "06_silent-failure-reviewer_silent-failure-review.md",
|
|
580
|
-
"role": "silent-failure-reviewer",
|
|
581
|
-
"roleType": "reviewer",
|
|
582
|
-
"agent": "aspect-silent-failure-reviewer",
|
|
583
|
-
"type": "silent-failure-review",
|
|
584
|
-
"phase": "parallelReview",
|
|
585
|
-
"createdAt": "2026-02-21T03:47:00Z",
|
|
586
|
-
"iteration": 1
|
|
587
|
-
},
|
|
588
|
-
{
|
|
589
|
-
"filename": "07_code-reviewer_code-review.md",
|
|
590
|
-
"role": "code-reviewer",
|
|
591
|
-
"roleType": "reviewer",
|
|
592
|
-
"agent": "aspect-code-reviewer",
|
|
593
|
-
"type": "code-review",
|
|
594
|
-
"phase": "parallelReview",
|
|
595
|
-
"createdAt": "2026-02-21T03:47:00Z",
|
|
596
|
-
"iteration": 1
|
|
597
|
-
},
|
|
598
|
-
{
|
|
599
|
-
"filename": "08_coder_change-summary.md",
|
|
600
|
-
"role": "coder",
|
|
601
|
-
"roleType": "author",
|
|
602
|
-
"agent": "orchestrated-coder",
|
|
603
|
-
"type": "change-summary",
|
|
604
|
-
"phase": "parallelReview",
|
|
605
|
-
"createdAt": "2026-02-21T04:00:00Z",
|
|
606
|
-
"note": "Addresses aggregated findings from iteration 1"
|
|
607
|
-
},
|
|
608
|
-
{
|
|
609
|
-
"filename": "09_reviewer_review.md",
|
|
610
|
-
"role": "reviewer",
|
|
611
|
-
"roleType": "reviewer",
|
|
612
|
-
"agent": "orchestrated-reviewer",
|
|
613
|
-
"type": "review",
|
|
614
|
-
"phase": "parallelReview",
|
|
615
|
-
"createdAt": "2026-02-21T04:15:00Z",
|
|
616
|
-
"iteration": 2
|
|
617
|
-
},
|
|
618
|
-
{
|
|
619
|
-
"filename": "10_orchestrator_run-summary.md",
|
|
620
|
-
"role": "orchestrator",
|
|
621
|
-
"roleType": "orchestrator",
|
|
622
|
-
"agent": "orchestrator",
|
|
623
|
-
"type": "run-summary",
|
|
624
|
-
"phase": "summary",
|
|
625
|
-
"createdAt": "2026-02-21T04:16:00Z"
|
|
626
|
-
}
|
|
627
|
-
]
|
|
628
|
-
}
|
|
629
|
-
```
|
|
630
|
-
|
|
631
|
-
**Backward compatibility:** Old `run-index.json` data without top-level `status` fields on phase objects (e.g., `parallelReview` without a `status` field) is treated as completed by the factory visualization. The factory only blocks advancement past a phase when `status` is explicitly `"in_progress"`.
|
|
632
|
-
|
|
633
|
-
### roleType taxonomy
|
|
634
|
-
|
|
635
|
-
Each role maps to one of five workflow-function types. Only the retired orchestration engine wrote the `orchestrator`, `analyst`, and `planner` types, and every `reviewer` role but `reviewer`:
|
|
636
|
-
|
|
637
|
-
| roleType | Description | Example roles |
|
|
638
|
-
| -------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
639
|
-
| `orchestrator` | Coordinates phases and manages run state | `orchestrator` |
|
|
640
|
-
| `analyst` | Assesses impact and provides architectural guidance | `architect` |
|
|
641
|
-
| `planner` | Produces implementation plans | `planner` |
|
|
642
|
-
| `author` | Writes or modifies project code | `coder` |
|
|
643
|
-
| `reviewer` | Evaluates code and produces findings | `reviewer`, `code-reviewer`, `code-simplification-reviewer`, `silent-failure-reviewer`, `test-reviewer` |
|
|
644
|
-
|
|
645
|
-
### Artifact entry fields
|
|
646
|
-
|
|
647
|
-
| Field | Required | Description |
|
|
648
|
-
| ----------- | -------- | -------------------------------------------------------------------------------------- |
|
|
649
|
-
| `filename` | yes | Artifact filename (without directory path) |
|
|
650
|
-
| `role` | yes | Filename role segment (e.g., `reviewer`, `code-reviewer`) |
|
|
651
|
-
| `roleType` | yes | Workflow function (one of: `orchestrator`, `analyst`, `planner`, `author`, `reviewer`) |
|
|
652
|
-
| `agent` | yes | {tool:Task} `subagent_type` value (e.g., `plan-reviewer`) |
|
|
653
|
-
| `type` | yes | Artifact type (e.g., `review`, `change-summary`) |
|
|
654
|
-
| `phase` | yes | Phase that produced this artifact (camelCase, matches `phases` object keys) |
|
|
655
|
-
| `createdAt` | yes | ISO 8601 timestamp |
|
|
656
|
-
| `iteration` | no | Review iteration number (for `parallelReview` phase) |
|
|
657
|
-
| `note` | no | Free-text context about the artifact |
|
|
658
|
-
|
|
659
|
-
### Phase values
|
|
660
|
-
|
|
661
|
-
Phase values use camelCase and match the keys in the `phases` object. Only the retired orchestration engine wrote them:
|
|
662
|
-
|
|
663
|
-
- `initialization`: Run setup and manifest creation
|
|
664
|
-
- `architecture`: Architectural impact assessment
|
|
665
|
-
- `planning`: Implementation planning
|
|
666
|
-
- `implementation`: Code authoring
|
|
667
|
-
- `parallelReview`: Parallel review and fix cycles
|
|
668
|
-
- `codeSimplifier`: Code simplification pass
|
|
669
|
-
- `holisticReview`: Final comprehensive review
|
|
670
|
-
- `summary`: Run summary generation
|
|
671
|
-
|
|
672
|
-
### Version field
|
|
673
|
-
|
|
674
|
-
The `version` field distinguishes schema formats: absent = v1 (`status.json` era), `2` = v2 (inline state in `run-index.json`), `3` = v3 (event-sourced). The engine's last runs use v3. Runs in v1 and v2 remain valid.
|
|
675
|
-
|
|
676
|
-
## V3 format: Event-sourced runs
|
|
677
|
-
|
|
678
|
-
V3 separates static run metadata from dynamic state. The `run-index.json` file contains only the header; all state transitions are recorded as events in a companion `run-log.jsonl` file. V3 is a read-only format: Only the retired orchestration engine wrote it, and run-core and the factory read it.
|
|
679
|
-
|
|
680
|
-
### V3 header schema
|
|
681
|
-
|
|
682
|
-
`run-index.json` with `version: 3` contains only the header, without `phases`, `phaseDecisions`, `status`, or `completedAt` fields in `context`. `completedAt`, present once the run completed, is at the top level.
|
|
683
|
-
|
|
684
|
-
Context fields: `runId`, `projectSlug`, `ticketId?`, `projectRoot`, `branch`, `task`, `startedAt`.
|
|
685
|
-
|
|
686
|
-
Config fields: `externalPlan?`, `mergeBaseSha?`, `diffBase?`, `maxReviewRounds?`, `effort?`, `approvalThreshold?`, `budgetThreshold?`, `mode?`, `model?`. Additional fields are preserved (loose schema).
|
|
687
|
-
|
|
688
|
-
### Run-log.jsonl
|
|
689
|
-
|
|
690
|
-
Companion file in the same run directory. Each line is a JSON object (JSONL format) representing one `RunEvent`. The engine appended events in order, timestamped each with field `t` (ISO 8601), and validated each against the `runEventSchema` discriminated union on the `event` field before appending it.
|
|
691
|
-
|
|
692
|
-
### Event types
|
|
693
|
-
|
|
694
|
-
All 13 valid event types and their required fields. Fields suffixed with `?` are optional. Only the retired orchestration engine wrote these events. Usage fields (`tokens`, `toolUses`, `durationMs`) are present on its later runs, which recorded {tool:Task} result metrics; older runs omit them:
|
|
695
|
-
|
|
696
|
-
| Event type | Key fields |
|
|
697
|
-
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
698
|
-
| `run_started` | _(none beyond `t`, `event`)_ |
|
|
699
|
-
| `run_completed` | `status` (`completed`\|`failed`\|`needs_manual_review`) |
|
|
700
|
-
| `run_failed` | `status`, `reason?` |
|
|
701
|
-
| `phase_decision` | `phase` (string), `run` (boolean), `reason?` |
|
|
702
|
-
| `phase_started` | `phase` (one of: `architecture`\|`planning`\|`implementation`\|`review`\|`simplifier`\|`holistic`) |
|
|
703
|
-
| `phase_completed` | `phase`, `status` (one of: `completed`\|`skipped`\|`failed`\|`in_progress`\|`approved`), `data?` (record), `tokens?`, `toolUses?`, `durationMs?` |
|
|
704
|
-
| `reviewer_dispatched` | `reviewer` (string) |
|
|
705
|
-
| `reviewer_completed` | `reviewer`, `status` (`completed`\|`skipped`\|`failed`), `criticality` (`none`\|`low`\|`medium`\|`high`), `tokens?`, `toolUses?`, `durationMs?` |
|
|
706
|
-
| `coder_fix_started` | `iteration` (number) |
|
|
707
|
-
| `coder_fix_completed` | `iteration` (number), `tokens?`, `toolUses?`, `durationMs?` |
|
|
708
|
-
| `re_review_dispatched` | `reviewers` (string array) |
|
|
709
|
-
| `re_review_completed` | `criticalities` (record: reviewer name -> criticality), `tokens?`, `toolUses?`, `durationMs?` |
|
|
710
|
-
| `artifact_written` | `filename`, `role`, `roleType`, `agent`, `type`, `phase`, `iteration?`, `note?` |
|
|
374
|
+
## Run data format
|
|
711
375
|
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
```
|
|
715
|
-
{base_dir}/projects/{projectSlug}/tickets/{ticketId}/{runId}/
|
|
716
|
-
run-index.json <- v3 header (top-level completedAt once the run completed)
|
|
717
|
-
run-log.jsonl <- append-only event log (one JSON object per line)
|
|
718
|
-
{NN}_{role}_{artifact}.md <- artifact files (sequential counter)
|
|
719
|
-
```
|
|
720
|
-
|
|
721
|
-
Runs are always nested under a ticket ID directory. When its caller did not provide a ticket ID, the engine generated one in the format `{YYYYMMDD}-{4 random hex}` (e.g., `20260302-a3f2`). Caller-supplied ticket IDs with a leading `#` were sanitized to bare numbers before use in file paths (e.g., `#152` became `152`).
|
|
722
|
-
|
|
723
|
-
### Run ID format (v3)
|
|
724
|
-
|
|
725
|
-
`{yyyymmdd}-{hhmmss}Z`, generated by the engine. This differs from the historical v2 format `{yyyymmdd}-{hhmmss}Z-orchestrated`.
|
|
726
|
-
|
|
727
|
-
### Event folding
|
|
728
|
-
|
|
729
|
-
Full run state (phases, artifacts, review rounds, criticalities) is reconstructed from `run-log.jsonl` by run-core's `foldEvents` function, which returns a `CanonicalRunStatus`.
|
|
730
|
-
|
|
731
|
-
### Backward compatibility
|
|
732
|
-
|
|
733
|
-
The run-core parser, `parseRunData`, still reads the v2 `run-index.json` format and the v1 `status.json` format.
|
|
376
|
+
The files that describe a run directory, `run-index.json`, `run-log.jsonl`, and the v1 `status.json`, are specified in [run data format](https://github.com/williamthorsen/codeassembly/blob/main/packages/run-core/docs/run-data-format.md), beside the run-core schemas that implement them. The retired orchestration engine wrote them; the current skills do not.
|
|
734
377
|
|
|
735
378
|
## Artifact types
|
|
736
379
|
|
|
@@ -758,15 +401,17 @@ The first `coder_change-summary` in a run does not have dispositions (nothing to
|
|
|
758
401
|
- `dispositions`: The rendered dispositions of a triage of findings, the text that `triage-spike-findings` posts on the triage ticket: every item with its disposition, its confidence and value, where it went, and its reason, with the challenge's summary; the JSON record from which it is rendered stays in `triage/`
|
|
759
402
|
- `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
|
|
760
403
|
- `feedback-curation`: The record of a `curate-feedback` run: the count of events in each bin, the guidance commits against which the judges read, each mark with its result, and every event with its bin, reference, and reason; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
|
|
761
|
-
- `feedback-triage`: The record of a `triage-feedback` run: each
|
|
404
|
+
- `feedback-triage`: The record of a `triage-feedback` run: each reported cluster of feedback events with its signals, priority, challenge, disposition, and result, and the remainder left in the pool. A deferred event's `addressed-by` names the artifact, whose filename timestamp dates the deferral; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
|
|
762
405
|
- `idea-decisions`: The idea table of a round of prototypes with the decision on each idea filled; `prepare-prototype-brief` saves it after the developer decides each idea, and the end vision cites it
|
|
763
406
|
- `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
|
|
407
|
+
- `performance-findings`: The measured performance of a site and the improvements ranked by expected effect, with field and lab data reported separately, each improvement's evidence, metric, and effort, what was left unmeasured, and the method; `analyze-performance` saves it, and `triage-spike-findings` reads it
|
|
764
408
|
- `plan`: Implementation plan document
|
|
765
409
|
- `plan-review`: Plan review findings (completeness and correctness analysis)
|
|
766
410
|
- `plan-v2`: Refined implementation plan after review and revision
|
|
767
411
|
- `pull-request`: PR description file; `capture-lede-decision` reads its `## What` as the agent's side of a lede episode
|
|
768
412
|
- `refinement-log`: The accepted changes of one session of `refine-prototype`, grouped under the id of the version that each one entered, with the transplants' sources and the open forks; the end vision reads it with the `idea-decisions` artifact
|
|
769
413
|
- `review`: Code review (ticket-level, commit scope)
|
|
414
|
+
- `spike-findings`: The findings and recommendation of a spike: the answer to each of the ticket's questions to answer, the recommendation on each decision to enable, the residual unknowns, the evidence, and any proposed work; `investigate-spike` saves it, and `triage-spike-findings` reads it
|
|
770
415
|
- `ticket`: Issue ticket
|
|
771
416
|
- `usability-brief`: The brief that every lens of a usability assessment reads: the medium, the targets and their write rules, the lenses with their minimum use cases, and the exclusions; `assess-usability` saves it at its checkpoint
|
|
772
417
|
- `usability-findings`: The merged findings of a usability assessment, ranked by effect and reach, with the use-case outcomes, the ideas, the proposed groupings, the residual unknowns, and the lens reports; `assess-usability` saves it, and `triage-spike-findings` reads it
|
|
@@ -841,9 +486,9 @@ A finding therefore has one of exactly two shapes, and consumers may rely on the
|
|
|
841
486
|
|
|
842
487
|
A named change still has to be worth making. Decide at this gate whether it is, having established at the [Proposed-change gate](#proposed-change-gate) that a change exists.
|
|
843
488
|
|
|
844
|
-
A finding
|
|
489
|
+
A finding consumes more than its line length: the reader's time, the tokens spent asking you to reconsider it, the author's triage, and every later reader who reads both the finding and its rejection. Treat emitting any finding as taking on a burden of proof, weighed against everything that it consumes, never against its line length.
|
|
845
490
|
|
|
846
|
-
This gate is the [concision principle](./concision.md) applied to findings: A finding, like any detail,
|
|
491
|
+
This gate is the [concision principle](./concision.md) applied to findings: A finding, like any detail, wastes every reader's attention once the attention that it takes outweighs the decision that it enables.
|
|
847
492
|
|
|
848
493
|
**Hedging language is a delete trigger, not a softening device.** If a finding's own qualifiers make it irrelevant, it does not belong. Drop it. If the condition genuinely holds now, drop the qualifier instead and state the finding plainly. Disqualifying signs include:
|
|
849
494
|
|
|
@@ -966,57 +611,3 @@ Every level degrades gracefully:
|
|
|
966
611
|
- Missing global preferences -> fall back to the default base directory
|
|
967
612
|
- Missing `{base_dir}/` directory -> created automatically on first artifact save
|
|
968
613
|
- Missing `project.slug` in preferences -> use the bare directory name of the working directory
|
|
969
|
-
|
|
970
|
-
## Migration from status.json (v1) to run-index.json (v2)
|
|
971
|
-
|
|
972
|
-
The retired orchestration engine wrote both formats. This section records how they differ, for readers of historical runs.
|
|
973
|
-
|
|
974
|
-
### File rename
|
|
975
|
-
|
|
976
|
-
`status.json` → `run-index.json`. The new name reflects the file's expanded role as an artifact registry, not just a status tracker.
|
|
977
|
-
|
|
978
|
-
### Schema changes
|
|
979
|
-
|
|
980
|
-
- **New `version` field** (value: `2`). Enables schema detection; absent version = v1.
|
|
981
|
-
- **`context` section** groups: `runId`, `projectSlug`, `ticketId`, `projectRoot`, `branch`, `task`, `startedAt`, `completedAt`, `status`, `phases`, `phaseDecisions`.
|
|
982
|
-
- **`config` section** groups: `externalPlan`, `mergeBaseSha` (new), `diffBase` (new), `maxReviewRounds` (new), `effort` (new), `approvalThreshold` (new), `budgetThreshold` (new), `mode`, `model`.
|
|
983
|
-
- **`phaseDecision` → `context.phaseDecisions`** (now keyed by phase name, each value is a `{ run, reason? }` object). Each entry now includes an optional `disposition` field (`executed` | `skipped` | `absent`).
|
|
984
|
-
- **New `pipeline` field in `config`**. Ordered list of phase names from the engine's pipeline specification (e.g., `["architecture", "planning", "implementation", "review-cycle"]`). Records which phases were configured for the run (intent, not outcome). The `review-cycle` pipeline entry is a module that expands into sub-phase keys (`parallelReview`, `codeSimplifier`, `holisticReview`) in `context.phaseDecisions` and `context.phases` at runtime.
|
|
985
|
-
- **New `artifacts` array**. Each entry includes `roleType` for workflow-function classification. See [artifact entry fields](#artifact-entry-fields) for the full schema.
|
|
986
|
-
|
|
987
|
-
### Role and reviewer renames
|
|
988
|
-
|
|
989
|
-
Reviewer keys in `context.phases.parallelReview.reviewers`:
|
|
990
|
-
|
|
991
|
-
| v1 key | v2 key |
|
|
992
|
-
| ----------------------- | ------------------------- |
|
|
993
|
-
| `core` | `reviewer` |
|
|
994
|
-
| `aspect-silent-failure` | `silent-failure-reviewer` |
|
|
995
|
-
| `aspect-test` | `test-reviewer` |
|
|
996
|
-
| `aspect-code` | `code-reviewer` |
|
|
997
|
-
|
|
998
|
-
Role segments in artifact filenames:
|
|
999
|
-
|
|
1000
|
-
| v1 role | v2 role |
|
|
1001
|
-
| -------- | ------------------------------ |
|
|
1002
|
-
| `aspect` | `silent-failure-reviewer` |
|
|
1003
|
-
| `aspect` | `test-reviewer` |
|
|
1004
|
-
| `aspect` | `code-reviewer` |
|
|
1005
|
-
| `aspect` | `code-simplification-reviewer` |
|
|
1006
|
-
|
|
1007
|
-
### Timestamp format
|
|
1008
|
-
|
|
1009
|
-
All timestamps (run IDs and artifact filenames): `YYYYMMDD-HHMMZ` → `YYYYMMDD-HHMMSSZ` (adds seconds).
|
|
1010
|
-
|
|
1011
|
-
### Known consumers (codeassembly)
|
|
1012
|
-
|
|
1013
|
-
The following codeassembly files reference the run metadata schema and will need updates:
|
|
1014
|
-
|
|
1015
|
-
- `project-scanner.ts`: Filename patterns for artifact discovery
|
|
1016
|
-
- `status-adapter.ts`: Schema parsing and normalization
|
|
1017
|
-
- `runs.ts`: Artifact filtering and run enumeration
|
|
1018
|
-
- `canonical.ts`: Type definitions
|
|
1019
|
-
|
|
1020
|
-
### Backward compatibility
|
|
1021
|
-
|
|
1022
|
-
During the transition period, scanners should check for both `run-index.json` and `status.json`. The presence of a `version` field distinguishes v2 from v1.
|
|
@@ -12,7 +12,7 @@ A load-bearing decision is worth elaborating; a routine one is worth a clause. A
|
|
|
12
12
|
|
|
13
13
|
## What to cut
|
|
14
14
|
|
|
15
|
-
Intros, hedging, restated context, exhaustive enumeration. Process narration (how the work or decision was
|
|
15
|
+
Intros, hedging, restated context, exhaustive enumeration. Process narration (how the work was done or how the decision was made) when only the conclusion serves the reader.
|
|
16
16
|
|
|
17
17
|
## Self-test
|
|
18
18
|
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Entry points
|
|
2
|
+
|
|
3
|
+
The skill that opens the work in a ticket's worktree follows from the ticket's state and the artifacts in its ticket directory. This file states that rule once; {skill?:start-ticket} applies it when a session starts, and the split report of every plan skill names that skill rather than choosing an entry point of its own.
|
|
4
|
+
|
|
5
|
+
## Inputs
|
|
6
|
+
|
|
7
|
+
- **The ticket's state**: open or closed, from the platform fetch in [ticket source resolution](ticket-source-resolution.md#platform-specific-fetch).
|
|
8
|
+
- **The branch's pull request**: `pr_url` from the session-context manifest, or else the pull request whose head is `branch_name` in any state (on GitHub, `gh pr list --head {branch_name} --state all --json url,state`). `pr_url` is usually null on a ticket branch, so the lookup is the common case.
|
|
9
|
+
- **The ticket directory**: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`, and the artifact types that [artifact conventions](artifact-conventions.md) defines. The newest plan is the one that the plan resolution of {skill?:implement-plan} selects (its [process](../implement-plan/SKILL.md#process), step 2): the greatest filename prefix across `*_plan.md` and `*_plan-v*.md`, never `*_plan-review.md`. The newest artifact of any other type is the one with the greatest filename prefix.
|
|
10
|
+
|
|
11
|
+
## Routes
|
|
12
|
+
|
|
13
|
+
Check the routes in order and stop at the first match. Each route names the skill, the arguments that it passes, and the reason that the announcement states.
|
|
14
|
+
|
|
15
|
+
1. **Done.** The ticket is closed, or the branch has a pull request that is open or merged: Stop, and report in one line `{ticket_ref} is {state}; PR {url} is {state}.`, with each clause only when it applies. A closed pull request that was not merged does not match, because the work may restart.
|
|
16
|
+
|
|
17
|
+
2. **Unsettled plan.** The newest plan contains a list entry inside its `## Decisions taken` section whose text starts with 🔲: {skill?:refine-plan} with the plan path and the ticket. Reason: the plan contains a decision that no checkpoint approved. A 🔲 elsewhere in the plan, or one that a decision mentions rather than starts with, does not match.
|
|
18
|
+
|
|
19
|
+
3. **Spike.** The ticket body, in its newest ticket artifact or on the platform, contains the `## Question` section and the `### Questions to answer` tier of the [spike ticket template](spike-conventions.md#spike-ticket-template), or the newest plan contains `## Investigation steps`:
|
|
20
|
+
- The ticket directory contains a `dispositions` artifact, which {skill?:triage-spike-findings} saves once its last write succeeds: Stop, and report the findings artifact and the dispositions. The spike is finished.
|
|
21
|
+
- The ticket directory contains `triage/dispositions.json` without a `dispositions` artifact: {skill?:triage-spike-findings} with the findings path, which resumes the interrupted triage from that record.
|
|
22
|
+
- A `spike-findings` artifact newer than the plan proposes work, judged by reading it with the test of {skill?:investigate-spike} step 8: {skill?:triage-spike-findings} with the findings path.
|
|
23
|
+
- A `spike-findings` artifact newer than the plan does not propose any work: Stop, and report it, with the closing post as the step that remains, which {skill?:investigate-spike} offers.
|
|
24
|
+
- The newest plan is a spike plan: {skill?:investigate-spike} with `--plan={path}` and `--ticket={ticket_ref}`.
|
|
25
|
+
- Otherwise: routes 5c and 5d, with `as a spike` after the ticket ref. That phrase is the explicit entry into spike mode that [spike conventions](spike-conventions.md) requires.
|
|
26
|
+
|
|
27
|
+
4. **Prototype round.** The ticket directory contains a prototype set (`prototypes/manifest.json`, per [the set](../index-prototypes/SKILL.md#the-set)), or a `brief`, `comparison`, `idea-decisions`, or `refinement-log` artifact, or the ticket calls for two or more competing prototypes of one idea, judged by reading it:
|
|
28
|
+
- A `refinement-log` artifact: {skill?:design-and-plan} with the ticket ref, for the end vision and the ticket. {skill?:refine-prototype} saves the log when the refinement closes, so the log marks the refinement as done.
|
|
29
|
+
- An `idea-decisions` artifact that is newer than the newest `comparison` and does not contain an `open` row: {skill?:refine-prototype}.
|
|
30
|
+
- A `comparison` artifact, with an `idea-decisions` artifact newer than it that contains an `open` row, or none newer than it: {skill?:prepare-prototype-brief} with the ticket ref and the scope note `decide the ideas (step 7)`.
|
|
31
|
+
- Otherwise: {skill?:prepare-prototype-brief} with the ticket ref, adding the scope note `resume the round from the saved brief` when a `brief` artifact exists.
|
|
32
|
+
|
|
33
|
+
5. **Feature.**
|
|
34
|
+
- a. Route 2 covers a plan that contains an unsettled decision.
|
|
35
|
+
- b. Any other plan: {skill?:implement-plan} with `--plan={path}` and `--ticket={ticket_ref}`.
|
|
36
|
+
- c. The ticket is ready: It states a problem, a proposed solution, and acceptance criteria, and applying [ticket evaluation](ticket-evaluation.md) does not find any divergence that needs a design conversation. This is a judgment, and the announcement states its reason. {skill?:plan} with the ticket ref.
|
|
37
|
+
- d. Otherwise: {skill?:design-and-plan} with the ticket ref.
|