software-craft

Software Craft

You orchestrate a build and its craft review, or a craft review alone, and deliver verified findings. The rules live as atomic cards in references/craft-cards/ — one language-agnostic checkable claim each, an openable source each. A developer agent writes code by those cards: before each step it lists the cards for that step by facet and reads the ones whose titles apply. A deterministic pre-pass then matches each card's dispatch conditions — regular expressions against the added lines, or a structural signal it measures — against the agent's own working-tree diff and writes a dispatch plan; one Workflow runs a finder per (card by slice) plus a logic pass per slice, aggregates deterministically, and runs a skeptic per finding; confirmed findings go back to the developer once; a render script writes the two reports. Every finding cites concrete code from the diff — no anchor in the diff, no finding — and the skeptics exist to reject: the report carries only what survived refutation, the decision the design note research/2026-09-26_software-craft-cards.md at the repository root records.

Quick rules:

• One confirmation with the user, at the end of Scope; ask further questions only when every context source is empty or no base branch resolves.
• The developer agent edits only inside the write zone; this skill edits nothing (disallowed-tools), the review-run scripts (static-craft.py, bundle-run.py, render-reports.py) write only under craft/, the authoring scripts run at authoring time only and never in a build or a review, and the finders and skeptics read. A tree that changed during the review beyond the developer's reported changes is a compromised review, so the integrity check in Follow-ups is mandatory.
• No version-control write by anyone: the developer agent stops before a commit, and so does this skill; the operator commits.
• No stage runs on Fable; the tiers are claude-opus-5-5 at high, xhigh and max (design note §Review workflow contracts).
• The plan is never retyped: scripts/bundle-run.py embeds it, and the Workflow call names craft/run.js.
• Before committing a card, an agent prompt or this file: scripts/validate-craft-cards.py on the corpus, then the audit (repository Quality Gate).

Phases: Scope → Context → Build → Pre-pass → Workflow → Fix round → Follow-ups and report. A review-only run skips Build and the Fix round.

Runtime layout under the target repository's craft/ (or the config-set report path for the two reports):

craft/
|-- plan.json                       # pre-pass output: inventory with signals, card index, jobs, slices, candidates, project cards
|-- plan.log                        # every skip, merge, split and drop the pre-pass performed
|-- run.js                          # the workflow script with this run's arguments embedded (scripts/bundle-run.py)
|-- findings.json                   # aggregated findings after the find stage (the cross-session checkpoint)
|-- raw-<i>.json                    # the raw findings of find part i (a run in parts)
|-- verdicts.json                   # findings with verdicts (and rulings) after the verify stage
|-- build-report.md                 # the developer agent's report (build runs)
|-- craft-review-<task>.md          # deliverable 1
`-- craft-review-<task>-rejections.md   # deliverable 2

Paths below are relative to this skill's directory unless they start with craft/ (the target repository) or plugins/.