codeassembly-guidance 0.4.0 → 0.5.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 +329 -280
- package/CHANGELOG.md +16 -0
- package/README.md +7 -22
- package/content/_partials/guidance-change-since-capture.md +1 -1
- package/content/collections/recommended.md +1 -1
- package/content/guidance/rulebooks/shared-data-conventions.md +4 -2
- package/content/scripts/check-prose.mjs +38 -38
- package/content/skills/_data/artifact-conventions.md +2 -421
- package/content/skills/_partials/plan-template.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +1 -1
- package/content/skills/refine-guidance/SKILL.md +1 -1
- package/content/skills/save-artifact/SKILL.md +1 -1
- package/content/skills/triage-feedback/SKILL.md +1 -1
- package/content/subagents/feedback-triage-challenger.md +1 -1
- package/content/subagents/plan-reviewer.md +8 -7
- package/package.json +4 -4
- package/schemas/preferences.v1.json +1 -1
- package/schemas/work-types.v1.json +1 -1
|
@@ -183,8 +183,6 @@ When the ticket directory already contains artifacts for this change, reuse thei
|
|
|
183
183
|
|
|
184
184
|
Underscore separates all structural parts. Hyphens are free for use within any part (role names, artifact names, slugs).
|
|
185
185
|
|
|
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
186
|
Artifact ordering follows the timestamp prefix.
|
|
189
187
|
|
|
190
188
|
Example run directory (a review, the author's response, and a re-review):
|
|
@@ -365,372 +363,9 @@ This artifact uses the [universal artifact frontmatter](#universal-artifact-fron
|
|
|
365
363
|
|
|
366
364
|
`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
365
|
|
|
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?` |
|
|
711
|
-
|
|
712
|
-
### Run directory layout (v3)
|
|
366
|
+
## Run data format
|
|
713
367
|
|
|
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.
|
|
368
|
+
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
369
|
|
|
735
370
|
## Artifact types
|
|
736
371
|
|
|
@@ -966,57 +601,3 @@ Every level degrades gracefully:
|
|
|
966
601
|
- Missing global preferences -> fall back to the default base directory
|
|
967
602
|
- Missing `{base_dir}/` directory -> created automatically on first artifact save
|
|
968
603
|
- 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.
|
|
@@ -60,7 +60,7 @@
|
|
|
60
60
|
|
|
61
61
|
**Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the rulebook's browser check of each new or changed interactive element.
|
|
62
62
|
|
|
63
|
-
**Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge.
|
|
63
|
+
**Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge. When a verdict from an agent decides such a write, the acceptance criteria of the task that implements the verdict name the evidence and the script that checks it before the write. When the work adds or changes a skill that writes to shared state, `## Verification` runs the skill against the real data up to its approval checkpoint or as a dry run, and reviews each verdict that the run would act on.
|
|
64
64
|
|
|
65
65
|
**Per-task invoked-skill guidance:** When a task invokes a skill, read that skill while planning the task and record in the task's key decisions what the skill declares under three headings: its ordering relative to other skills, its default target when the task does not pass an argument, and the preconditions that it states. Read every skill that the plan's tasks name, and record a skill declaring none of the three as declaring none, so that a reader can tell a completed check from an absent one. A skill that cannot be read is recorded as unread, never as declaring none. When an ordering constraint names a skill that the plan's tasks do not invoke, add the task rather than record the constraint alone.
|
|
66
66
|
|
|
@@ -4,4 +4,4 @@
|
|
|
4
4
|
|
|
5
5
|
**Umbrella criterion convention:** When writing an umbrella ticket, whose children do the work, list "Every child is closed" as an acceptance criterion alongside any requirement of its own, so that what completes it is stated rather than inferred. When the split is decided, create a child for every planned piece, so that the criterion cannot hold while a planned piece remains: Link each child to the umbrella as a sub-issue, and through blocked-by relations to the pieces that must be merged before it. Specify the current piece fully, and keep each later piece short: its outcome, a few must-have criteria, and a note that it is refined when its work starts. Never leave a planned piece as an outline in the umbrella's body. To defer a planned piece, close its child as not planned.
|
|
6
6
|
|
|
7
|
-
**Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever happens first, the deploy or the migration.
|
|
7
|
+
**Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever happens first, the deploy or the migration. When the ticket adds or changes a skill that writes to shared state, include a criterion that the skill runs against the real data before merge and stops before the write, and when a verdict from an agent decides that write, a criterion that a script checks the verdict's evidence before the write.
|
|
@@ -60,7 +60,7 @@ Decide the mode, and give its reason in one sentence:
|
|
|
60
60
|
- **An existing rule states the lesson**: `strengthen`, `relocate`, or `illustrate` it, per "Choosing a kind" in the content specification.
|
|
61
61
|
- **The guidance does not state it**: a new artifact, `new {kind} in {content root}`, with the kind and the content root chosen per the same section.
|
|
62
62
|
|
|
63
|
-
Decide which repository owns the target. A file with a `<!-- codeassembly-` marker, or a file in the CodeAssembly guidance library, belongs to the CodeAssembly repository, per [deployed-file provenance](../_data/deployed-file-provenance.md); a project's `.agents/content` file or `AGENTS.md` belongs to that project's repository. When the owner is not the current repository, do not edit the file: Offer to file the lesson there with {skill:create-ticket} `--repo {repo}`, and stop.
|
|
63
|
+
Decide which repository owns the target. A file with a `<!-- codeassembly-` marker, or a file in the CodeAssembly guidance library, belongs to the CodeAssembly guidance repository (`williamthorsen/codeassembly-guidance`), per [deployed-file provenance](../_data/deployed-file-provenance.md); a project's `.agents/content` file or `AGENTS.md` belongs to that project's repository. When the owner is not the current repository, do not edit the file: Offer to file the lesson there with {skill:create-ticket} `--repo {repo}`, and stop.
|
|
64
64
|
|
|
65
65
|
Present the placement: the lesson, the mode and its reason, and the target file or the new artifact's path. Ask for confirmation before drafting.
|
|
66
66
|
|
|
@@ -29,7 +29,7 @@ An artifact belongs to the developer's audit trail, as [artifact-conventions.md]
|
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
- **timestamp**: UTC time in `YYYYMMDD-HHMMSSZ` format
|
|
32
|
-
- **role**: Kebab-case identifier; hyphens are free within the name, underscores are reserved as structural separators.
|
|
32
|
+
- **role**: Kebab-case identifier; hyphens are free within the name, underscores are reserved as structural separators. See [artifact-conventions.md](../_data/artifact-conventions.md#run-artifacts-review-workflow) for the current role list.
|
|
33
33
|
- **artifact**: Kebab-case identifier following the same naming conventions. See [artifact-conventions.md](../_data/artifact-conventions.md#artifact-types) for the artifact type list.
|
|
34
34
|
|
|
35
35
|
Run artifacts are saved by the skills that produce them (`review-branch`, `respond-to-review`), into the ticket's active run. See [artifact-conventions.md](../_data/artifact-conventions.md#run-directories) for how the active run is identified.
|
|
@@ -42,7 +42,7 @@ Each surfaced cluster takes one disposition:
|
|
|
42
42
|
|
|
43
43
|
A ticket disposition names the repository that owns its target:
|
|
44
44
|
|
|
45
|
-
- An artifact with a `<!-- codeassembly-` marker, or one in the CodeAssembly guidance library, belongs to the CodeAssembly repository, whose name the marker's provenance or the library's `Source:` line states.
|
|
45
|
+
- An artifact with a `<!-- codeassembly-` marker, or one in the CodeAssembly guidance library, belongs to the CodeAssembly guidance repository (`williamthorsen/codeassembly-guidance`), whose name the marker's provenance or the library's `Source:` line states.
|
|
46
46
|
- A project's `.agents/content` artifact belongs to that project's repository: Take it from the events' `repo` field, and confirm it with `gh repo view {repo} --json nameWithOwner`.
|
|
47
47
|
- A new or undecided target belongs to the current repository.
|
|
48
48
|
|
|
@@ -39,7 +39,7 @@ Work in rounds, where a round is one turn of tool calls. Batch every read and ch
|
|
|
39
39
|
For each cluster:
|
|
40
40
|
|
|
41
41
|
1. **Check the target.** Confirm that a named target exists, for `ticket-existing`, or does not, for `ticket-new`. Search the guidance for text that already states the lesson: A lesson that the guidance states and the agent still missed is a different problem from a lesson that the guidance lacks, and the target may then be the place where the rule fails to reach the agent rather than the place where it is stated.
|
|
42
|
-
2. **Check the repository.** An artifact with a `<!-- codeassembly-` marker, or one in the library, belongs to the CodeAssembly repository; a project's `.agents/content` artifact belongs to that project's repository. Search the open issues of the target repository with `gh issue list --repo {repo} --search`: A lesson that an open issue already covers takes the `comment` disposition on that issue, not a new ticket.
|
|
42
|
+
2. **Check the repository.** An artifact with a `<!-- codeassembly-` marker, or one in the library, belongs to the CodeAssembly guidance repository (`williamthorsen/codeassembly-guidance`); a project's `.agents/content` artifact belongs to that project's repository. Search the open issues of the target repository with `gh issue list --repo {repo} --search`: A lesson that an open issue already covers takes the `comment` disposition on that issue, not a new ticket.
|
|
43
43
|
3. **Check the guidance history.** Check whether the guidance that governs the lesson changed after the cluster's latest capture, per [Guidance history](#guidance-history).
|
|
44
44
|
4. **Argue against the priority.** Ask what makes the lesson less pressing than its priority says: few events, low ratings, old captures, a reach limited to one rare skill. When the guidance changed after the latest capture, argue that the events show nothing about the current guidance, name the change in the argument, and propose `low` unless evidence shows the failure recurring under the changed guidance. Argue the priority up when the signals support that instead. Read the three signals separately; do not combine them into one score.
|
|
45
45
|
5. **Argue against the disposition.** Ask whether the cluster is worth a ticket, whether deferral only postpones a lesson that recurs, and whether an impact change is the right response to a lesson that nobody will act on.
|
|
@@ -66,13 +66,14 @@ Each finding is tagged with a resolution type:
|
|
|
66
66
|
|
|
67
67
|
### Correctness criteria (X findings)
|
|
68
68
|
|
|
69
|
-
| Focus | Check
|
|
70
|
-
| ------------------------- |
|
|
71
|
-
| Factual accuracy | Referenced files, utilities, APIs exist?
|
|
72
|
-
| Structural soundness | Dependencies ordered? Steps scoped correctly?
|
|
73
|
-
| Requirements traceability | Every requirement has a step? Every step traces to a requirement?
|
|
74
|
-
| Blocker handling | Does a step or risk accept a degraded fallback when it should ask the user for a resource?
|
|
75
|
-
| Actor assignment | Does a task or verification check name the developer as its actor without a `**Residue:**` line stating what the agent cannot do and why?
|
|
69
|
+
| Focus | Check | Resolution |
|
|
70
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
|
|
71
|
+
| Factual accuracy | Referenced files, utilities, APIs exist? | `auto` |
|
|
72
|
+
| Structural soundness | Dependencies ordered? Steps scoped correctly? | `auto` |
|
|
73
|
+
| Requirements traceability | Every requirement has a step? Every step traces to a requirement? | `user` if intentionally omitted; `auto` if overlooked |
|
|
74
|
+
| Blocker handling | Does a step or risk accept a degraded fallback when it should ask the user for a resource? | `auto` |
|
|
75
|
+
| Actor assignment | Does a task or verification check name the developer as its actor without a `**Residue:**` line stating what the agent cannot do and why? | `auto` |
|
|
76
|
+
| Judged writes | When the change adds or changes a skill that writes to shared state, does `## Verification` run the skill against the real data before merge, stopping before the write at its approval checkpoint or as a dry run? When a verdict from an agent decides that write, does a task's acceptance criteria name the evidence and the script that checks it before the write? | `auto` if the verdict's inputs show what evidence fits; `user` otherwise |
|
|
76
77
|
|
|
77
78
|
<!-- guidance-hook: implementation-preferences -->
|
|
78
79
|
<!-- guidance-hook: writing-preferences -->
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "codeassembly-guidance",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "The CodeAssembly library of agent guidance: rulebooks, skills, and subagents that the codeassembly CLI deploys",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -9,13 +9,13 @@
|
|
|
9
9
|
"rulebooks",
|
|
10
10
|
"skills"
|
|
11
11
|
],
|
|
12
|
-
"homepage": "https://github.com/williamthorsen/codeassembly/tree/main/packages/guidance#readme",
|
|
12
|
+
"homepage": "https://github.com/williamthorsen/codeassembly-guidance/tree/main/packages/guidance#readme",
|
|
13
13
|
"bugs": {
|
|
14
|
-
"url": "https://github.com/williamthorsen/codeassembly/issues"
|
|
14
|
+
"url": "https://github.com/williamthorsen/codeassembly-guidance/issues"
|
|
15
15
|
},
|
|
16
16
|
"repository": {
|
|
17
17
|
"type": "git",
|
|
18
|
-
"url": "https://github.com/williamthorsen/codeassembly.git",
|
|
18
|
+
"url": "https://github.com/williamthorsen/codeassembly-guidance.git",
|
|
19
19
|
"directory": "packages/guidance"
|
|
20
20
|
},
|
|
21
21
|
"license": "ISC",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
-
"$id": "https://unpkg.com/codeassembly-guidance@0.
|
|
3
|
+
"$id": "https://unpkg.com/codeassembly-guidance@0.5.0/schemas/preferences.v1.json",
|
|
4
4
|
"title": "Preferences",
|
|
5
5
|
"description": "Configuration read by agent skills. Resolved from .agents/preferences.yaml at the project level, with ~/.agents/preferences.yaml as a global fallback.",
|
|
6
6
|
"type": "object",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
-
"$id": "https://unpkg.com/codeassembly-guidance@0.
|
|
3
|
+
"$id": "https://unpkg.com/codeassembly-guidance@0.5.0/schemas/work-types.v1.json",
|
|
4
4
|
"additionalProperties": false,
|
|
5
5
|
"description": "Canonical work-types taxonomy consumed by skill content and downstream changelog/release-notes tooling. Defines the work-type vocabulary, tier grouping, breaking-change policy, changelog-eligibility flags, and cross-cutting section markers (e.g., the breaking-changes indicator).",
|
|
6
6
|
"properties": {
|