[calvin-archastro]

Review on ArchCode

Merge order: after ArchAstro/firstlanding#19110, which makes the review page render Mermaid and context labels. Before that ships, diagrams show as their source text (readable, not broken).

Problem and author intent

Agents using the tasks skill write every field as prose, even when the content is a request flow, a state machine, or a matrix. On a real 9-task plan, reviewers faced long paragraphs that narrate sequences and nested bullets standing in for tables. The goal is plans a reviewer can scan: diagrams and tables where the content has that shape, prose elsewhere.

What changed

tasks/SKILL.md, section 2, gains "Write fields the review page can draw" (regenerated into all 8 harness plugins by tools/plugin-gen):

• A table mapping content shape to form: flow → sequenceDiagram (failing path in context, target path in implementation; only the target when nothing fails), state → stateDiagram-v2, components → flowchart LR, matrices and comparisons → Markdown tables, evidence → labelled lines (Observed <date>:, Current code:, Decision (<who>, <date>):, Precedent:, Hypothesis:, Prerequisite status:).
• Limits: at most 5 participants with short labels and about 4–8 messages; one- or two-line steps; file lists once in scope; diagrams optional for one-file or linear work.
• Mermaid rules that render (safe participant ids, no parentheses in labels, no second colon, braces, or ? in messages: ID instead of {id}).
• How to write a fenced or tabled field as a string array, with - markers for list items.
• The JSON example's export-api implementation now includes a sequence diagram.

Scope

Skill text only (docs). No CLI or installer change.

Risk

Low. Guidance only; diagrams stay optional and fall back to their source when they fail to parse.

User impact

Plans drafted with the skill review as diagrams, tables, and tagged context instead of paragraphs.

Testing

• tools/plugin-gen: npm run build, npm run check (140 generated files match the catalog), npm test (116 pass).
• End-to-end check of the guidance: two fresh agents, each given only this skill section and the original 9-task devbox plan, regenerated the plan. The first run's feedback (undated observations, decision dates, braces in paths, string arrays holding fences, ambiguous "current or failing path") went into the second revision. The final regeneration produced 13 diagrams and 4 tables, changed nothing outside context and implementation, and rendered through the built archdev CLI and the production review page with 0 Mermaid failures. Screenshots are in the firstlanding PR.
• No automated test covers the skill prose itself; plugin-gen checks only that the generated copies match.

Follow-ups

• Plugins pick this up on the next archdev plugin release.

🤖 Generated with Claude Code