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.
Files changed (78) hide show
  1. package/.meta/changelog.json +635 -280
  2. package/CHANGELOG.md +89 -0
  3. package/README.md +55 -19
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/_partials/guidance-change-since-capture.md +1 -1
  6. package/content/codeassembly-content.yaml +2 -0
  7. package/content/collections/recommended.md +6 -3
  8. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  9. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  10. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  12. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  13. package/content/guidance/rulebooks/shared-data-conventions.md +4 -2
  14. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  16. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  17. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  18. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  19. package/content/scripts/check-prose.mjs +38 -38
  20. package/content/scripts/describe-change.mjs +68 -68
  21. package/content/skills/_data/action-items.md +2 -2
  22. package/content/skills/_data/artifact-conventions.md +22 -431
  23. package/content/skills/_data/concision.md +1 -1
  24. package/content/skills/_data/entry-points.md +37 -0
  25. package/content/skills/_data/recommendation-gradient.md +6 -6
  26. package/content/skills/_data/spike-conventions.md +13 -3
  27. package/content/skills/_data/ticket-source-resolution.md +21 -4
  28. package/content/skills/_data/title-templates.md +4 -4
  29. package/content/skills/_partials/commit-title-rendering.md +2 -1
  30. package/content/skills/_partials/next-steps-after-plan.md +4 -3
  31. package/content/skills/_partials/option-format.md +8 -8
  32. package/content/skills/_partials/plan-template.md +4 -2
  33. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  34. package/content/skills/_partials/split-launch-prompts.md +1 -1
  35. package/content/skills/_partials/ticket-criteria-conventions.md +3 -1
  36. package/content/skills/analyze-performance/SKILL.md +102 -0
  37. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  38. package/content/skills/assess-code-health/SKILL.md +16 -14
  39. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  40. package/content/skills/assess-usability/SKILL.md +5 -3
  41. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  42. package/content/skills/create-commit/SKILL.md +10 -5
  43. package/content/skills/create-pr/SKILL.md +11 -11
  44. package/content/skills/create-ticket/SKILL.md +1 -0
  45. package/content/skills/design-and-plan/SKILL.md +2 -2
  46. package/content/skills/implement-plan/SKILL.md +1 -28
  47. package/content/skills/index-prototypes/SKILL.md +36 -17
  48. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  49. package/content/skills/investigate-spike/SKILL.md +48 -0
  50. package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
  51. package/content/skills/refine-guidance/SKILL.md +1 -1
  52. package/content/skills/refine-plan/SKILL.md +7 -4
  53. package/content/skills/refine-prototype/SKILL.md +5 -5
  54. package/content/skills/review-branch/SKILL.md +7 -7
  55. package/content/skills/review-criteria/SKILL.md +3 -3
  56. package/content/skills/review-gh-pr/SKILL.md +1 -1
  57. package/content/skills/revise-prose/SKILL.md +9 -8
  58. package/content/skills/revise-prose/revise-prose.mjs +2 -2
  59. package/content/skills/save-artifact/SKILL.md +1 -1
  60. package/content/skills/start-ticket/SKILL.md +27 -0
  61. package/content/skills/summarize-change/SKILL.md +17 -9
  62. package/content/skills/testing-conventions/SKILL.md +12 -1
  63. package/content/skills/triage-feedback/SKILL.md +1 -1
  64. package/content/skills/triage-spike-findings/SKILL.md +31 -12
  65. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  66. package/content/subagents/_data/claude.yaml +3 -0
  67. package/content/subagents/code-health-assessor.md +4 -4
  68. package/content/subagents/disposition-challenger.md +3 -4
  69. package/content/subagents/entry-drafter.md +2 -2
  70. package/content/subagents/feedback-triage-challenger.md +1 -1
  71. package/content/subagents/handoff-reviewer.md +1 -1
  72. package/content/subagents/plan-reviewer.md +8 -7
  73. package/content/subagents/prototype-builder.md +69 -0
  74. package/content/subagents/usability-assessor.md +1 -1
  75. package/package.json +8 -7
  76. package/schemas/preferences.v1.json +1 -1
  77. package/schemas/work-types.v1.json +1 -1
  78. 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
- The failure prevented by this convention is not bad formatting. It is an ask that the agent never recognized as an ask. The formatting rules never applied to it. Before ending a turn, scan the draft for anything that invites a response and move every hit into the block.
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 holds 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 holds 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.
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 stood 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:
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 extension:
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
- ## run-index.json
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
- ### Run directory layout (v3)
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 surfaced 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)
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 costs 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 that full cost, never against its line length.
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, costs every reader attention once that cost outweighs the decision that it enables.
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 reached) when only the conclusion serves the reader.
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.