@ikon85/agent-workflow-kit

v1.0.3

Published

a month ago

Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.

0High
0Medium
0Low

ikon85

agent-workflow-kit

A complete shipping loop for coding agents — plan → execute → land → learn.

Maintainer build

The public repository is the source of truth. A fresh clone needs Node 20 or newer, Python 3, and no Python packages:

npm install --ignore-scripts
npm test
npm run kit:build
npm run kit:staleness
npm pack --dry-run

kit:build assembles dist-kit/ only from files in this checkout and writes a sha256 manifest. kit:staleness compares that fresh manifest with the checked-in install manifest. The frozen v0.9.0 manifest remains under test/fixtures/ as the historical golden baseline; current builds intentionally include later SSOT changes.

Maintainers prepare releases with /kit-release. It derives the shipped delta from a fresh manifest, recommends Semver, applies only the confirmed target, regenerates the checked-in manifest, and runs the full test and pack gates. Landing remains owned by /make-landable + /land and only integrates the prepared version. After a separate publication confirmation, a matching annotated v<version> tag on canonical main starts the trusted publish flow. Manual dispatch requires an explicit existing tag and only reconciles an incomplete release.

These are the skills, helper scripts, and conventions one team actually uses to take work from a vague idea to a merged, verified PR with Claude Code and Codex. One npx command drops them into any repo; /setup-workflow wires them to your tracker and board. Edit anything — updates never clobber your changes.

Quickstart

# from the root of the repo you want to add the workflow to
npx github:iKon85/agent-workflow-kit init

init copies the skills + helper scripts in, and seeds empty project-layer stubs. It never overwrites a file you already have.
Run /setup-workflow once (in Claude Code / Codex). A guided, idempotent skill that detects your issue tracker, writes your label + domain + deploy config, and — for a GitHub Projects board — discovers the field IDs into a board profile. See Configuration.
Start working. Trigger skills by name (/grill-with-docs, /tdd, /land, …) — the workflow below explains when each one earns its keep. Unsure which one fits? Run /ask-matt — it routes you to the right skill.

The workflow it installs

The skills aren't a grab-bag — they're four phases of one loop, entered through a single funnel no matter where your work starts. Each phase below names the failure mode it removes and the skills that remove it.

view the workflow map →

1. Plan — turn a vague idea into shaped, tracked work

Agents dive into code before the problem is sharp, then build the wrong thing well. The plan phase makes you earn a clear spec first.

One funnel, many doors, one shape. There's no single front door. You enter wherever your work actually starts — a vague idea, a plan you already wrote, a PRD pasted from another tool, a raw issue, or a whole backlog — and every door funnels into the same shaped artefact: a Draft-PRD that, once sliced, becomes either one atomic issue or a wave anchor with child slices. What counts downstream is the shape of the artefact, never where it came from — so each step can be entered cold and extracts or synthesizes what's missing instead of assuming an earlier step ran. The entry key is just "is there an issue yet?": a loose artefact (no issue) enters at to-prd; an existing issue or file-bundle enters at to-issues directly. Inside that facade, the explicit PRD identity — Feature or Program — is the only mode selector; a cold source must establish one before a remote write.

Grill as deep as the work deserves — it's optional. grill-me / grill-with-docs interrogate the intent (and your domain docs) until the real requirement surfaces, instead of latching onto the first framing. Skip it for a mechanical change, run a light grill for a normal feature, add +codex (below) for something high-stakes. Your call, per piece of work.
to-prd turns whatever you bring — idea, plan, external spec — into a short Draft-PRD issue, extracting the template sections from what already exists. A required section it genuinely can't derive becomes an honest Open points block, never a silent "looks complete" placeholder.
to-issues is the single public Planning facade. Explicit Feature identity selects tracer-bullet decomposition and picks the shape: 1 slice → one atomic issue the PR closes; ≥2 slices → a wave anchor with linked child slices. Explicit Program identity selects the existing internal graph engine and preserves its complete chat preview before any board write. Missing or contradictory identity stops before a write; size, prose, and model judgment never select the mode. Any unresolved Open points travel through as a build-blocking gate (the profile's configurable vorBau heading, see Configuration) that never vanishes silently.
board-to-waves clusters an existing backlog into themed campaigns when you need to find the next wave rather than start fresh.
triage keeps the inbox sane with a consistent label vocabulary.
spec-self-critique red-teams your own spec before you commit to building it.
verify-spike / decision-gate — gate-before-build. When to-issues cuts a slice that hinges on an unknown it tags the slice instead of guessing: a single yes/no fact against the real lib/runtime/DB runs as a verify-spike (throwaway read-only harness, verdict + proof sunk to the issue); a bounded "which option" trade-off or a research gap runs as a decision-gate (read-only weigh-up, options × criteria table, reasoned pick sunk to an ADR/issue). The gate is its own slice, sequenced before the build slice it blocks — clarify the one open point cheaply instead of re-grilling the whole feature; genuinely hard-to-reverse calls still escalate up to +codex.
domain-modeling / codebase-design — shared design vocabulary. When a slice is about shaping rather than shipping — pinning down the ubiquitous language and ADRs (domain-modeling) or designing a deep module behind a clean seam (codebase-design) — these give the grill and the design work a precise, consistent vocabulary instead of ad-hoc terms.
wayfinder — when the idea is too big for one session. Charts a foggy, multi-session effort as a shared map issue with investigation tickets on your tracker (native blocking renders the frontier visually), resolved one per session until the way to the destination is clear — planning, not doing.
research delegates primary-source reading legwork to a background agent; the findings land as a cited Markdown note in the repo.

You approve the slice breakdown before anything is published — the funnel never publishes behind your back.

2. Execute — build it right, not just fast

"Make the tests pass" drifts into untested, sprawling, hard-to-review change. The execute phase keeps the diff disciplined.

tdd — a strict red → green → refactor loop; the test is written first and must fail for the right reason.
prototype — spike a throwaway when the path is genuinely unclear, so the real implementation is informed.
implement — drive a PRD or a set of issues to done: tdd at the agreed seams, typecheck + single-file tests throughout, the full suite once at the end, then a code-review pass before it lands.

Two more skills are doors of their own, not funnel steps. You reach for them when the work starts broken or tangled rather than from a fresh idea, so they enter outside the plan funnel and feed straight into Execute:

diagnose — a disciplined root-cause hunt for bugs (reproduce → isolate → fix → prove), not a guess-and-patch. Entered from a bug or anomaly, never the PRD funnel; the fix it lands flows on into Execute.
improve-codebase-architecture — step back from the diff to the structure when a change is fighting the codebase. A recon stream that either becomes a planned slice (back through to-issues) or guides a refactor in place.

3. Land — ship without surprises

The risky part is the merge: half-checked PRs, broken hooks, context lost at handoff. The land phase puts mechanical gates in front of the commit.

make-landable — the post-implement half: run the local CI gate, judge the secret scan, commit the finished slice, and author the PR body with its close/part-of marker and the build's assumption-drift markers. It stops at a landable branch — nothing is pushed, opened, or merged. A planning session with no worktree lands its durable content the same way, through one confirmed file claim that leaves every bystanding change untouched.
land — the post-acceptance half: push, open or reuse the PR, enforce the PR body contract, merge the PR, reconcile the board, tear the finished worktree down, retire the branch, sweep merged branches, and surface anything still open. It does not replace live verification; verify the user outcome before landing. Interrupted halfway? Re-run it — every step re-reads present state (does the PR exist, is it merged, is the worktree still there?) and skips what is already done, so there is no separate resume mode and no journal to repair.
Teardown asks your repository, not a config file. Finishing a worktree classifies it with git's own file taxonomy at the moment it acts: a tracked change or an unmerged path blocks, an untracked file your repo does not ignore blocks with a bounded report, and an ignored entry is scratch that dies with the worktree. Making something disposable therefore means ignoring it — the full rules, the .env* exception, and the breaking change from the pattern keys are in the worktree lifecycle.
The pre-commit / pre-push gate fires automatically — TypeScript, lint, and contract guards block a broken commit or push. You don't run a skill here; the gate was installed once at setup (git-guardrails / setup-pre-commit, both Claude only, see Configuration) and now guards every Land.
resolving-merge-conflicts — a disciplined loop for an in-progress merge/rebase conflict: understand each side's intent from history/PRs, preserve both where possible, always resolve (never --abort), then re-run the checks.
Helper scripts — pr-body-check.py, execute-ready-check.py, and board-sync.py keep the PR and the issue tracker honest (see Configuration).

4. Learn — compound the lessons instead of repeating them

The same mistake recurs because nothing captured it. The learn phase turns friction into config.

retro — an in-session post-mortem that proposes concrete changes to your rules, skills, or hooks, each with per-patch approval.
write-a-skill (Claude only) — turn a move you keep repeating into a reusable skill.

Optional: cross-model review (via Codex)

An independent second model is a cheap way to catch what one model rationalizes. grill-me-codex / grill-with-docs-codex run the grill through Codex, codex-review gets a second-opinion plan review, and codex-build flips the roles for an optional Act 3 (Codex implements the frozen spec in a bounded workspace-write sandbox, Claude verifies the diff and proof). All four are Claude only (invoked from Claude Code, which shells out to the Codex CLI) and need the Codex CLI installed.

The altitude model

The four phases above are what you do. Underneath them sits a shape for what you're doing it to — a plan travels through four altitudes, and each hands a well-defined object to the level below:

| Altitude | What it is | Artefact | |---|---|---| | Program | The whole undertaking, described once with a wave plan attached. | one PRD issue | | Phase | An acceptance bracket around a handful of waves. Optional. | a board field | | Wave | The working unit: one outcome, a few slices, one gate — exactly the wave you already build with the flow above. | one anchor issue | | Slice | One build session, one pull request, one visible result. | one sub-issue |

Two roads lead to the same wave. Top-down: scale-check names the size in a few plain questions; a big undertaking gets grilled once into a Program PRD with a wave plan, and to-issues selects its internal Program graph path from that explicit identity. It unfolds the plan into named waves after you approve a full preview in chat — zero board writes until you say yes. Bottom-up: board-to-waves clusters loose issues into a wave candidate, which earns a real number only when you promote it. Either road lands in the identical wave anchor plus slice sub-issues, built through the same implement → make-landable → land → retro spine as every other wave.

When the slices are file-disjoint and their specs are locked, orchestrate-wave lands the whole anchor end-to-end — often AFK: it dispatches an implementer per slice into its own worktree, integrates serially, verifies centrally, and lands the wave. It's the execute-and-land node of the wave ladder (scale-check → to-issues / board-to-waves → orchestrate-wave); a single slice still just goes to implement.

The Program-to-Phase-to-Wave-to-Slice altitude ladder, and the two routes — a planned top-down Program route and a grown bottom-up board route — that both fund the same Wave-and-Slices build spine.

The full walkthrough — every entry point, the build-layer skills, and the six mechanics that keep a multi-wave plan honest (gates, drift propagation, the revision loop, program-sync, and counted completeness) — lives on one page: read the methodology → (also shipped as docs/methodology.html in your install, so it works offline too).

Configuration

The skills ship the how; your repo supplies the what. init only lays down empty stubs — /setup-workflow fills them. It's a guided, idempotent skill (not a script): it explores your repo, confirms with you section by section, and writes:

| It writes | So that | |---|---| | docs/agents/issue-tracker.md | to-issues / triage know whether to call gh, glab, or follow your flow | | docs/agents/triage-labels.md | triage uses your label vocabulary | | docs/agents/domain.md | the domain skills find your CONTEXT.md / ADR layout | | docs/agents/board-sync.md | the board scripts get your GitHub Projects field IDs (the board profile) | | ## Agent skills + ## Prod in CLAUDE.md / AGENTS.md | the agent knows your skills and deploy target |

Each generated file carries a setup-workflow sentinel on its first line, so a re-run only fills what's missing and never overwrites content you've filled in.

Two more one-time skills harden the repo when you adopt the kit — both Claude only: git-guardrails installs the secret / branch / broken-build guardrails, and setup-pre-commit wires the pre-commit gate. Run them once — afterwards the gate fires automatically on every commit and push (see the Land phase above).

The board profile

The board helper scripts carry no hard-coded IDs. They read everything board-specific from a single fenced json block in docs/agents/board-sync.md, marked :

{
  "repo": "<owner>/<repo>",
  "project": { "number": 1, "owner": "<owner>", "nodeId": "<project-node-id>" },
  "fields": {
    "status": {
      "id": "<status-field-id>",
      "options": { "Spec": "<option-id>", "In Progress": "<option-id>", "Done": "<option-id>" },
      "roles": { "spec": "Spec", "inProgress": "In Progress", "done": "Done" }
    },
    "wave": "<wave-field-id>",
    "cluster": "<cluster-field-id>",
    "specPath": "<field-id>",
    "planPath": "<field-id>"
  },
  "labels": {
    "readyForAgent": "ready-for-agent",
    "typePrefix": "type:",
    "clusterType": "type:cluster",
    "waveStub": "wave-stub"
  },
  "branchPrefixes": ["feat", "fix", "chore", "docs"],
  "prMarkers": { "partOf": "Part of", "retroMarker": "**Retro:**", "retroValues": ["ran", "skipped"] },
  "headings": { "vorBau": "Clarify Before Build" }
}

/setup-workflow discovers these values for you from gh project field-list; you rarely touch this by hand. Point a script at an alternate profile with the BOARD_SYNC_PROFILE environment variable. Labels, branch prefixes, and headings are yours to rename — the scripts read whatever the profile says.

Status stage names are yours too: scripts and skills address stages by semantic role (fields.status.roles: idea/triaged/spec/inProgress/review/done → your option names, e.g. board-sync.py add --status-role spec), so a board in any language works — map each role once, rename an option with one profile edit.

The worktree lifecycle

An optional capability, offered once by /setup-workflow and recorded in your own docs/agents/workflow-capabilities.json. Enabled, it gives each build its own linked worktree: python3 scripts/worktree-lifecycle/setup.py cuts the branch, creates the worktree from your naming templates, and runs your project's setup steps; on Claude Code a set of hook adapters keeps edits, verification commands, and Git mutations in the checkout they belong to; and land tears the worktree down after the merge. A worktree belongs to a build — a session that only plans or grills stays in the main checkout, keeps its scratch on disk, and lands its durable output as ordinary content.

The profile carries structural facts only: where worktrees live (worktreeRoot), how branches and paths are named (branchTemplate, contentBranchTemplate, pathTemplate, branchRegex), which branches are protected (mainBranches, protectedBranches), the setup command and its ordered steps, and the command patterns that must run inside the active worktree. Keys the loader does not know are ignored in silence, so a profile written for an older kit keeps working without warning noise.

Teardown authority is the repository's current state, read at the moment of action, and nothing else. It classifies the worktree with git's own file taxonomy over your standard exclude sources — the repository's .gitignore files, .git/info/exclude, and your global excludes file:

| What git reports | What teardown does | |---|---| | a tracked modification, or an unmerged path | blocks, and names it | | an untracked file you do not ignore | blocks with a bounded report — a count plus the top directories, never a page-long path dump | | an ignored entry | scratch: deleted together with the worktree |

Two rules sit on top of that taxonomy. An .env* file (basename glob) is the single exception — ignored, yet potentially irreplaceable — and it has two arms. A path your own seed.paths declares is removed because you declared it: you said this file is what a fresh worktree carries, which is the same kind of statement your .gitignore makes, and every such deletion is named in the teardown report. An .env* file you did not declare is removed only when it is byte-identical to the file at the same relative path in your main checkout; divergent, missing there, or not a plain file stops teardown and names the exact file. That is why a worktree carrying its own port needs one line of profile: undeclared, it is byte-different from your main checkout by construction and blocks. An ignored symlink is unlinked, never followed, and only while its target stays inside the worktree: an absolute, escaping, dangling, or since-changed target keeps the worktree and names the link.

Branch retirement is authorized, never assumed. A branch that is an ancestor of the freshly fetched protected branch is deleted normally. A branch that is not is force-deleted only when exactly one merged pull request matches it completely — your repository as base, no fork head, the same head and base ref — and that PR's head commit still equals the branch tip when the tip is re-read immediately before deletion. Anything else keeps the branch and reports why. Without platform access this degrades to ancestry only, and says so.

For a read-only inventory of every linked worktree and local branch — issue, PR, merge, age, and removal facts, nothing removed — run python3 scripts/worktree-lifecycle/cleanup.py sweep.

Breaking — the deletion pattern keys are gone, with no migration. Earlier releases configured what teardown could delete with worktreeLifecycle.scratchPatterns and wrapup.landingGeneratedArtifactPatterns. Both keys are removed. Deletion policy now has exactly one configuration surface: the ignore mechanism. There is nothing to migrate — a profile that still carries either key simply keeps it as consumer data; nothing reads it, nothing warns, nothing rewrites it — but the behaviour did change. If you used a pattern to make a file deletable, ignore the file instead; /setup-workflow offers (never installs) the ignore rules for the planning artefacts the shipped skills write. And note the risk this deliberately accepts: a file you keep gitignored inside a worktree is deletable at teardown unless it matches .env*. The decision record is docs/adr/0009-teardown-authority-is-stateless-repository-classification.md.

What's yours vs. the kit's

init records a sha256 of every file it installs. That's the line between the two: edit any skill or script freely — update detects your edits, keeps your bytes in a backup it names, and activates the new version on top. Say a path is yours (own <path> --as=explicit-fork) and update leaves it alone entirely. Your project layer (docs/agents/*, the board profile, CLAUDE.md, AGENTS.md) remains consumer-owned. update may only apply a previewed, schema-driven, idempotent compatibility migration that fills missing evidence without rewriting an existing value; it verifies and rolls that migration back with the rest of the candidate.

The kit collects nothing — no telemetry, no usage reporting, no phone-home — so how it behaves in your repo is visible to us only through the feedback you send.

Updating & removing

npx github:iKon85/agent-workflow-kit diff        # preview an update (dry run, writes nothing)
npx github:iKon85/agent-workflow-kit update      # apply it
npx github:iKon85/agent-workflow-kit update --yes --keep-deleted  # headless/CI
npx github:iKon85/agent-workflow-kit uninstall   # remove kit-installed files

update is a three-way reconcile against the hashes init recorded:

update always activates the full new version — there is no half-updated installation and no edit that blocks the release:

a file you didn't touch fast-forwards to the new version;
a file you did edit, without saying it is yours, is replaced by the new version — but never silently: your bytes are copied to <path>.<timestamp>.bak first (an existing backup is never clobbered), the diff is printed, and the end-of-update summary lists every backed-up path and offers you the three supported routes — move Project-specific instructions to docs/agents/skills/<skill>.md, own the path as an explicit fork, or send the improvement upstream with contribute start. It offers; it never picks one for you;
a file you intentionally fork can be detached with npx github:iKon85/agent-workflow-kit own <path> --as=explicit-fork and returned to kit ownership with npx github:iKon85/agent-workflow-kit disown <path>; owned files are skipped by updates even after the package stops shipping them, and are never overwritten or backed up — a declared fork is a decision, not a drift;
a modified declared Core path enters the temporary Contribution Bridge with contribute start <path>. contribute prepare <path> --output=.agent-workflow-kit/contributions/<name>.json writes one local, schema-versioned diff/provenance artifact and performs no remote action. A release whose Core bytes match the bridged bytes retires the bridge automatically on reimport;
contribute status <path> --surface=retro|pre-update|guard reads the same repository-scoped route decision on every workflow surface. Without a valid contributionRouting section in docs/agents/workflow-capabilities.json, only preserve/Explicit-fork guidance is available. A configured upstream must match its local Git remote; even then, the remote pull-request route requires a separate explicit approval;
a file removed upstream is offered for deletion (a hook still referenced by your settings.json is kept regardless);
a new Kit path that already exists locally is an ambiguous-collision until an interactive or automated caller explicitly classifies it as a Project extension, Contribution Bridge, Explicit fork, or clean Core; --yes never chooses that interpretation and never overwrites the path;
new skills without a local collision are added.

Ownership survives repeated init, including init --force: consumer-owned files are never overwritten. uninstall preserves consumer-owned files on disk but detaches them from the manifest, ending ownership tracking; it also retains anything edited or still referenced. The manifest remains only when other retained entries still require it.

Use diff --owned to inspect owned paths without changing them. Each path is reported as changed-upstream, removed-upstream, missing-locally, identical, or unsafe-path; binary files report only size and hashes. Containment and file type are revalidated when read.

Ownership commands are designed for a single-user CLI workflow and are not concurrency-safe. Do not run manifest-mutating commands concurrently. Flags: --force (overwrite pre-existing untracked files on init), --yes / -y (run update non-interactively and confirm only already-classified safe actions), --keep-deleted (follow upstream deletions and remove those files locally), --restore-deleted (retain files that were deleted upstream), and --as=explicit-fork for own.

A headless update requires --yes; otherwise it exits before reading release state or touching consumer files. The mutually exclusive deletion flags only override the blanket answer for files removed upstream. They never resolve an ownership collision, so a headless update that hits one still prints its report, exits non-zero, and leaves the consumer byte-identical. An undeclared local edit is not such a case: it is backed up, replaced, and reported, headless or not.

The optional Contribution Routing capability is consumer-owned:

{
  "contributionRouting": {
    "schemaVersion": 1,
    "enabled": true,
    "upstream": {
      "repository": "owner/repository",
      "remote": "kit-upstream"
    },
    "workflows": {
      "prepareLocal": true,
      "upstreamPullRequest": {
        "enabled": true,
        "requiresExplicitApproval": true
      }
    }
  }
}

The resolver verifies the configured remote URL and never infers capability from a username, machine, checkout path, consumer repository name, credentials, or current GitHub login.

Project extensions versus forks

Every shipped skill probes the optional consumer-owned docs/agents/skills/<skill>.md after loading its canonical Core. New extensions declare ; existing non-empty unmarked files remain supported as legacy v0. Claude and Codex use the same extension path and fail closed on an unknown schema or mismatched identity.

Use an extension for Project-specific language, commands, policy, or capability data. It augments Core and survives setup and updates byte-for-byte; it cannot weaken Core gates or replace executable semantics. If you need to change parsing, migration, evaluation, or other executable behavior, create an Explicit fork with its own identity and update line instead.

Upgrade notes

0.44.0 — teardown classifies, and the package ships less

Action required only if your profile configured teardown patterns.

worktreeLifecycle.scratchPatterns and wrapup.landingGeneratedArtifactPatterns are gone, with no migration. Teardown now classifies what it may delete from the repository's own ignore rules at the moment it acts, so the ignore mechanism is the single place deletion policy is configured. A profile still carrying either key simply keeps it, unread — nothing breaks, but the key no longer does anything. Move whatever those patterns protected into .gitignore (to make it deletable scratch) or out of the ignore rules (to make it a blocker).

Two consequences worth knowing before your next /wrapup:

A gitignored file that is not .env* is deletable at teardown. That is the deliberate trade for having no pattern list to maintain.
The session-teardown CLI scripts/worktree-lifecycle/session.py is removed, along with both of its recovery flags. Re-running the command is the recovery route; there is no attempt journal to repair. Worktree creation now goes through scripts/worktree-lifecycle/setup.py.

The long "removed:" list in the release notes below is mostly narrower packaging, not deleted features. Tests, this repository's own ADRs and research notes, and its build tooling stopped being published into node_modules; none of them was ever installed into a consumer repo by init, and every one of the 338 installed files is unchanged in scope. The only entry that removes something consumers could have used is session.py.

0.38.0 — explicit landing-artifact policy

Superseded — no action required. A later release removed the pattern keys without a migration: teardown now classifies from the repository's own ignore rules, so wrapup.landingGeneratedArtifactPatterns is no longer read, the requirement is no longer registered, and a profile still carrying the key simply keeps it. The original note is kept below as history.

Existing consumers must run setup-workflow once after kit-update, review the generated wrapup.landingGeneratedArtifactPatterns decision in docs/agents/workflow-capabilities.json, and commit that profile change. Until the explicit policy is committed, wrapup-land fails closed before landing instead of assuming that no generated artifact is eligible for session-owned cleanup.

You do not have to remember this note. kit-update carries a versioned registry of required consumer migrations and names any outstanding one in its preview and in its terminal report — interactively, under --yes, as JSON via update --json, and in the automated update pull request. It reports the decision you still owe; it never writes a cleanup policy for you.

0.33.0 — capability-gated orchestration

kit-update reconciles this release for you. These notes matter only if you maintain a local fork of orchestrate-wave: the blocks below changed behaviour, so a forked copy must re-apply them by hand or it keeps orchestrating the old way. Decision record: docs/adr/0002-capability-gated-orchestration.md.

Capability matrix, fail-closed. The dispatch mechanic is selected from host-supplied capability evidence, degrading A → B → C. Missing or unknown evidence never proves a capability, and Path C (direct, serial) is always available.
No emulation of a missing primitive. A host without a scripted workflow runtime gets the simpler recipe, never a hand-rolled imitation of one.
Codex Path B is native subagents. Explicit per-slice spawns joined by an explicit wait — dormant until a host supplies the complete normalized inventory.
JSON-schema reports plus independent verification. Every path returns schema-valid recon and builder reports and crosses the same main-thread boundary; a builder's own PASS is a hypothesis until semanticVerify confirms it against independently collected Git facts.
Per-batch, post-hub worktree provisioning. Worktrees are created serially in the main thread from the integrated base after the hub lands, under an atomic compare-and-set wave claim; reuse on a stale base now STOPs.
Heartbeat during long gates. Long-running gates report status rather than waiting silently.

Release notes

1.0.3

changed: .agents/skills/retro/SKILL.md
changed: .claude/skills/retro/SKILL.md
changed: README.md
changed: agent-workflow-kit.package.json
changed: package.json
changed: scripts/kit-release.mjs
changed: scripts/wrapup-land.py

1.0.2

changed: src/lib/updateReconcile.mjs

1.0.1

changed: README.md
changed: docs/methodology.html
changed: docs/methodology.svg
changed: docs/workflow.html
changed: docs/workflow.png

1.0.0

removed: .agents/skills/setup-workflow/workflow-advisories.md
removed: .claude/hooks/baseline-capture-hint.py
removed: .claude/hooks/block-bg-double-background.py
removed: .claude/hooks/block-npm-install-in-pnpm.py
removed: .claude/hooks/block-secrets.py
removed: .claude/hooks/branch-context.py
removed: .claude/hooks/branch-watch.py
removed: .claude/hooks/convention-drift-hint.py
removed: .claude/hooks/enforce-worktree-discipline.py
removed: .claude/hooks/enforce-worktree.py
removed: .claude/hooks/kit-origin-edit-hint.py
removed: .claude/hooks/loc-offender-forewarn.py
removed: .claude/hooks/migration-snapshot-reminder.py
removed: .claude/hooks/pre-refactor-sweep.py
removed: .claude/hooks/recon-size-hint.py
removed: .claude/hooks/skill-drift-hint.py
removed: .claude/hooks/slice-handoff-hint.py
removed: .claude/hooks/sync-board-status.py
removed: .claude/hooks/typecheck-on-stop.py
removed: .claude/hooks/typecheck-on-stop.sh
removed: .claude/skills/setup-workflow/workflow-advisories.md
removed: scripts/workflow-advisories/capabilities.json
removed: scripts/workflow-advisories/core.py
changed: .agents/skills/audit-skills/SKILL.md
changed: .agents/skills/setup-workflow/SKILL.md
changed: .agents/skills/setup-workflow/safety-guardrails.md
changed: .agents/skills/setup-workflow/worktree-lifecycle.md
changed: .agents/skills/tdd/SKILL.md
changed: .claude/hooks/_hook_utils.py
changed: .claude/hooks/drift-guard.py
changed: .claude/hooks/enforce-worktree-cwd.py
changed: .claude/hooks/grep-shim-guard.py
changed: .claude/skills/audit-skills/SKILL.md
changed: .claude/skills/setup-workflow/SKILL.md
changed: .claude/skills/setup-workflow/safety-guardrails.md
changed: .claude/skills/setup-workflow/worktree-lifecycle.md
changed: .claude/skills/tdd/SKILL.md
changed: PROVENANCE.md
changed: README.md
changed: agent-workflow-kit.package.json
changed: scripts/worktree-lifecycle/README.md
changed: scripts/worktree-lifecycle/capabilities.json
changed: scripts/worktree-lifecycle/core.py
changed: src/lib/bundle.mjs

0.47.0

added: .agents/skills/land/SKILL.md
added: .agents/skills/land/SOURCES.txt
added: .agents/skills/make-landable/SKILL.md
added: .agents/skills/make-landable/SOURCES.txt
added: .claude/skills/land/SKILL.md
added: .claude/skills/land/SOURCES.txt
added: .claude/skills/make-landable/SKILL.md
added: .claude/skills/make-landable/SOURCES.txt
removed: .agents/skills/wrapup/SKILL.md
removed: .agents/skills/wrapup/SOURCES.txt
removed: .claude/skills/wrapup/SKILL.md
removed: .claude/skills/wrapup/SOURCES.txt
changed: .agents/skills/ask-matt/SKILL.md
changed: .agents/skills/grill-me/SKILL.md
changed: .agents/skills/grill-with-docs/SKILL.md
changed: .agents/skills/kit-release/SKILL.md
changed: .agents/skills/kit-update/SKILL.md
changed: .agents/skills/orchestrate-wave/SKILL.md
changed: .agents/skills/setup-workflow/SKILL.md
changed: .agents/skills/setup-workflow/board-sync.md
changed: .agents/skills/setup-workflow/workflow-overview.md
changed: .agents/skills/tdd/SKILL.md
changed: .agents/skills/to-issues/SKILL.md
changed: .agents/skills/to-prd/PROGRAM-PRD-FORMAT.md
changed: .agents/skills/to-waves/SKILL.md
changed: .claude/hooks/kit-origin-edit-hint.py
changed: .claude/skills/ask-matt/SKILL.md
changed: .claude/skills/grill-me-codex/SKILL.md
changed: .claude/skills/grill-me/SKILL.md
changed: .claude/skills/grill-with-docs-codex/SKILL.md
changed: .claude/skills/grill-with-docs/SKILL.md
changed: .claude/skills/kit-release/SKILL.md
changed: .claude/skills/kit-update/SKILL.md
changed: .claude/skills/orchestrate-wave/SKILL.md
changed: .claude/skills/setup-workflow/SKILL.md
changed: .claude/skills/setup-workflow/board-sync.md
changed: .claude/skills/setup-workflow/workflow-overview.md
changed: .claude/skills/skill-manifest.json
changed: .claude/skills/tdd/SKILL.md
changed: .claude/skills/to-issues/SKILL.md
changed: .claude/skills/to-prd/PROGRAM-PRD-FORMAT.md
changed: .claude/skills/to-waves/SKILL.md
changed: README.md
changed: agent-workflow-kit.package.json
changed: docs/agents/wave-anchor-template.md
changed: scripts/board-sync.py
changed: scripts/execute-ready-check.py
changed: scripts/kit-release.mjs
changed: scripts/pr-body-check.py
changed: scripts/render-anchor.py
changed: scripts/worktree-lifecycle/README.md
changed: scripts/worktree-lifecycle/plan-artifacts.json
changed: scripts/worktree-lifecycle/profile.py
changed: scripts/wrapup-land.py
changed: src/cli.mjs
changed: src/commands/init.mjs
changed: src/commands/update.mjs
changed: src/lib/atomicWrite.mjs
changed: src/lib/bundle.mjs
changed: src/lib/updateCandidate.mjs
changed: src/lib/updateReconcile.mjs
changed: src/lib/verifyUpdateCandidate.mjs
changed: src/lib/verifyUpdateCandidateTransaction.mjs

0.46.4

changed: .agents/skills/setup-workflow/SKILL.md
changed: .agents/skills/setup-workflow/worktree-lifecycle.md
changed: .agents/skills/wrapup/SKILL.md
changed: .claude/hooks/enforce-worktree-cwd.py
changed: .claude/skills/setup-workflow/SKILL.md
changed: .claude/skills/setup-workflow/worktree-lifecycle.md
changed: .claude/skills/wrapup/SKILL.md
changed: README.md
changed: agent-workflow-kit.package.json
changed: scripts/worktree-lifecycle/README.md
changed: scripts/worktree-lifecycle/classify.py
changed: scripts/worktree-lifecycle/cleanup.py
changed: scripts/worktree-lifecycle/core.py
changed: scripts/worktree-lifecycle/ignore_seed.py
changed: scripts/worktree-lifecycle/profile.py
changed: scripts/worktree-lifecycle/setup.py
changed: scripts/wrapup-land.py

0.46.3

changed: .agents/skills/kit-update/SKILL.md
changed: .agents/skills/setup-workflow/workflow-overview.md
changed: .agents/skills/wrapup/SKILL.md
changed: .claude/skills/kit-update/SKILL.md
changed: .claude/skills/setup-workflow/workflow-overview.md
changed: .claude/skills/wrapup/SKILL.md
changed: agent-workflow-kit.package.json
changed: scripts/pr-body-check.py
changed: scripts/readiness.mjs
changed: scripts/wrapup-land.py
changed: src/cli.mjs
changed: src/commands/init.mjs
changed: src/commands/update.mjs

0.46.2

changed: scripts/codex-exec.sh

0.46.1

changed: .agents/skills/orchestrate-wave/SKILL.md
changed: .claude/skills/orchestrate-wave/SKILL.md
changed: agent-workflow-kit.package.json
changed: scripts/kit-release.mjs

0.46.0

added: src/commands/routing-refresh.mjs
added: src/lib/routingFetch.mjs
added: src/lib/routingHostCapabilities.mjs
added: src/lib/routingModelIdentity.mjs
added: src/lib/routingSources/endpoints.mjs
changed: agent-workflow-kit.package.json
changed: src/cli.mjs
changed: src/lib/bundle.mjs
changed: src/lib/routingInventory/snapshots/claude.json

0.45.2

changed: .agents/skills/wrapup/SKILL.md
changed: .claude/skills/wrapup/SKILL.md
changed: README.md
changed: agent-workflow-kit.package.json
changed: package.json
changed: scripts/wrapup-land.py

0.45.1

changed: README.md
changed: agent-workflow-kit.package.json
changed: package.json
changed: scripts/codex-exec.sh

0.45.0

added: scripts/doctrine-migration/index.mjs
added: src/commands/routing-status.mjs
added: src/lib/dispatchJournal.mjs
added: src/lib/dispatchPlan.mjs
added: src/lib/routingAccessGraphStore.mjs
added: src/lib/routingAdapters/hostBridge.mjs
added: src/lib/routingDispatchLease.mjs
added: src/lib/routingIntentClassifier.mjs
added: src/lib/routingInventory.mjs
added: src/lib/routingInventory/snapshots/claude.json
added: src/lib/routingInventory/snapshots/codex.json
added: src/lib/routingProfilePolicy.mjs
added: src/lib/routingProfileStorage.mjs
changed: .agents/skills/audit-skills/SKILL.md
changed: .agents/skills/code-review/SKILL.md
changed: .agents/skills/codebase-design/DESIGN-IT-TWICE.md
changed: .agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md
changed: .agents/skills/improve-codebase-architecture/SKILL.md
changed: .agents/skills/orchestrate-wave/SKILL.md
changed: .agents/skills/orchestrate-wave/references/dispatch-subagents.md
changed: .agents/skills/orchestrate-wave/references/dispatch-workflow.md
changed: .agents/skills/research/SKILL.md
changed: .agents/skills/to-issues/SKILL.md
changed: .claude/skills/audit-skills/SKILL.md
changed: .claude/skills/code-review/SKILL.md
changed: .claude/skills/codebase-design/DESIGN-IT-TWICE.md
changed: .claude/skills/codex-build/SKILL.md
changed: .claude/skills/codex-review/SKILL.md
changed: .claude/skills/grill-me-codex/SKILL.md
changed: .claude/skills/grill-with-docs-codex/SKILL.md
changed: .claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md
changed: .claude/skills/improve-codebase-architecture/SKILL.md
changed: .claude/skills/orchestrate-wave/SKILL.md
changed: .claude/skills/orchestrate-wave/references/dispatch-subagents.md
changed: .claude/skills/orchestrate-wave/references/dispatch-workflow.md
changed: .claude/skills/research/SKILL.md
changed: .claude/skills/skill-manifest.json
changed: .claude/skills/to-issues/SKILL.md
changed: agent-workflow-kit.package.json
changed: scripts/kit-release.mjs
changed: src/cli.mjs
changed: src/lib/bundle.mjs
changed: src/lib/dispatchReceipt.mjs
changed: src/lib/frontendWorkloads.mjs
changed: src/lib/routeDispatcher.mjs
changed: src/lib/routingAccessGraph.mjs
changed: src/lib/routingAdapters/claude.mjs
changed: src/lib/routingAdapters/codex.mjs
changed: src/lib/routingCatalog.mjs
changed: src/lib/routingEvidenceCache.mjs
changed: src/lib/routingIntent.mjs
changed: src/lib/routingPolicy.mjs
changed: src/lib/routingProfile.mjs
changed: src/lib/routingResolver.mjs
changed: src/lib/routingSources/artificialAnalysis.mjs
changed: src/lib/routingSources/benchlm.mjs
changed: src/lib/routingSources/codeArena.mjs
changed: src/lib/routingSources/deepswe.mjs
changed: src/lib/routingSources/openhands.mjs
changed: src/lib/routingSources/openhandsFrontend.mjs
changed: src/lib/updateCandidate.mjs

0.44.2

changed: src/cli.mjs
changed: src/commands/update.mjs
changed: src/consumer-migrations.json
changed: src/lib/consumerMigrations.mjs

0.44.1

changed: .claude/skills/skill-manifest.json
changed: agent-workflow-kit.package.json

0.44.0

added: scripts/worktree-lifecycle/classify.py
removed: docs/adr/0001-consumer-divergence-policy.md
removed: docs/adr/0002-capability-gated-orchestration.md
removed: docs/adr/0003-kit-core-and-project-extension-lifecycle.md
removed: docs/adr/0004-release-intent-is-a-version-tag.md
removed: docs/adr/0005-to-issues-is-the-planning-facade.md
removed: docs/adr/0006-routing-knowledge-access-and-policy-are-separate.md
removed: docs/adr/0007-session-teardown-requires-provenance-bound-ownership.md
removed: docs/adr/0008-planning-ignore-rules-are-offered-never-installed.md
removed: docs/adr/0009-teardown-authority-is-stateless-repository-classification.md
removed: docs/adr/0010-model-roster-replaces-the-optimization-dial.md
removed: docs/agents/board-sync.md
removed: docs/agents/code-review.md
removed: docs/agents/workflow-capabilities.json
removed: docs/research/agent-task-taxonomy-benchmark-coverage.md
removed: docs/research/benchlm-routing-source.md
removed: docs/research/consumer-owned-protocol-files.md
removed: docs/research/frontend-agent-benchmarks.md
removed: docs/research/model-effort-routing-benchmarks.md
removed: docs/research/provider-neutral-agent-routing.md
removed: docs/research/wave-152-consumer-acceptance.md
removed: docs/research/wave-43-script-hook-census.md
removed: scripts/build-kit.mjs
removed: scripts/build-kit.test.mjs
removed: scripts/census-contract.test.mjs
removed: scripts/census/census.test.mjs
removed: scripts/census/state.test.mjs
removed: scripts/census/transaction.test.mjs
removed: scripts/check-kit-staleness.mjs
removed: scripts/check-kit-staleness.test.mjs
removed: scripts/codex-exec-scenarios/fake-codex.mjs
removed: scripts/codex-exec.test.mjs
removed: scripts/grill-census-wiring-guard.mjs
removed: scripts/grill-census-wiring-guard.test.mjs
removed: scripts/kit-release.test.mjs
removed: scripts/kit-update-pr.test.mjs
removed: scripts/lib/audit-refs.mjs
removed: scripts/lib/scrub.mjs
removed: scripts/lib/scrub.test.mjs
removed: scripts/memory-lifecycle/memory-lifecycle.test.mjs
removed: scripts/portability_profile_scan.py
removed: scripts/release-delta-guard.test.mjs
removed: scripts/release-parity.test.mjs
removed: scripts/release-state.test.mjs
removed: scripts/test_anchor_table.py
removed: scripts/test_board_bootstrap.py
removed: scripts/test_board_sync.py
removed: scripts/test_board_sync_create_idempotency.py
removed: scripts/test_board_sync_wave_title.py
removed: scripts/test_census_backstop.py
removed: scripts/test_census_forward_contract.py
removed: scripts/test_census_update_contract.test.mjs
removed: scripts/test_codex_adapter_sync_contract.py
removed: scripts/test_dist_kit_smoke.py
removed: scripts/test_drift_guard_diagnostics.py
removed: scripts/test_issue_claim_contract.py
removed: scripts/test_kit_docs_language_census.py
removed: scripts/test_marker_lib.py
removed: scripts/test_orchestrate_wave_contract.py
removed: scripts/test_pr_body_check.py
removed: scripts/test_profile_globs.py
removed: scripts/test_program_planning_contract.py
removed: scripts/test_release_authorization_contract.py
removed: scripts/test_render_anchor.py
removed: scripts/test_retro_wrapup_contract.py
removed: scripts/test_skill_code_review_seed.py
removed: scripts/test_skill_codex_exec_lifecycle.py
removed: scripts/test_skill_frontmatter_lint.py
removed: scripts/test_skill_gh_lint.py
removed: scripts/test_skill_language_census.py
removed: scripts/test_skill_optional_readiness.py
removed: scripts/test_skill_portability_lint.py
removed: scripts/test_skill_precommit_template.py
removed: scripts/test_skill_publish_audit.py
removed: scripts/test_skill_readiness_contract.py
removed: scripts/test_skill_readiness_preflight.py
removed: scripts/test_skill_required_readiness.py
removed: scripts/test_skill_selfcontainment_lint.py
removed: scripts/test_skill_setup_workflow_seeds.py
removed: scripts/test_skill_stale_name_lint.py
removed: scripts/test_skill_surface_refs.py
removed: scripts/test_skill_trailing_artifact_lint.py
removed: scripts/test_tdd_contract.py
removed: scripts/test_worktree_ignore_seed.py
removed: scripts/test_worktree_setup_base_guard.py
removed: scripts/test_worktree_wrapup_contract.py
removed: scripts/test_wrapup_land.py
removed: scripts/worktree-lifecycle/session.py
changed: .agents/skills/grill-me/SKILL.md
changed: .agents/skills/grill-with-docs/SKILL.md
changed: .agents/skills/kit-update/SKILL.md
changed: .agents/skills/orchestrate-wave/SKILL.md
changed: .agents/skills/setup-workflow/SKILL.md
changed: .agents/skills/setup-workflow/board-sync.md
changed: .agents/skills/setup-workflow/workflow-advisories.md
changed: .agents/skills/setup-workflow/worktree-lifecycle.md
changed: .agents/skills/to-issues/SKILL.md
changed: .agents/skills/wrapup/SKILL.md
changed: .claude/skills/grill-me-codex/SKILL.md
changed: .claude/skills/grill-me/SKILL.md
changed: .claude/skills/grill-with-docs-codex/SKILL.md
changed: .claude/skills/grill-with-docs/SKILL.md
changed: .claude/skills/kit-update/SKILL.md
changed: .claude/skills/orchestrate-wave/SKILL.md
changed: .claude/skills/setup-workflow/SKILL.md
changed: .claude/skills/setup-workflow/board-sync.md
changed: .claude/skills/setup-workflow/workflow-advisories.md
changed: .claude/skills/setup-workflow/worktree-lifecycle.md
changed: .claude/skills/to-issues/SKILL.md
changed: .claude/skills/wrapup/SKILL.md
changed: README.md
changed: agent-workflow-kit.package.json
changed: package.json
changed: scripts/marker_lib.py
changed: scripts/profile_globs.py
changed: scripts/release-delta-guard.mjs
changed: scripts/worktree-lifecycle/README.md
changed: scripts/worktree-lifecycle/capabilities.json
changed: scripts/worktree-lifecycle/cleanup.py
changed: scripts/worktree-lifecycle/core.py
changed: scripts/worktree-lifecycle/ignore_seed.py
changed: scripts/worktree-lifecycle/profile.py
changed: scripts/worktree-lifecycle/setup.py
changed: scripts/wrapup-land.py
changed: src/consumer-migrations.json
changed: src/lib/bundle.mjs

0.43.0

removed: docs/agents/domain.md
removed: docs/agents/issue-tracker.md
removed: docs/agents/skills/local-ci.md
removed: docs/agents/skills/orchestrate-wave.md
removed: docs/agents/skills/spec-self-critique.md
removed: docs/agents/triage-labels.md
removed: docs/conventions/spec-completeness.md
changed: package.json
changed: scripts/build-kit.test.mjs
changed: scripts/codex-exec-scenarios/fake-codex.mjs
changed: scripts/codex-exec.test.mjs
changed: scripts/release-delta-guard.mjs
changed: scripts/release-delta-guard.test.mjs
changed: scripts/test_worktree_wrapup_contract.py
changed: scripts/worktree-lifecycle/README.md
changed: scripts/worktree-lifecycle/core.py

0.42.1

changed: docs/agents/skills/orchestrate-wave.md

0.42.0

added: docs/adr/0010-model-roster-replaces-the-optimization-dial.md
added: docs/research/agent-task-taxonomy-benchmark-coverage.md
changed: docs/adr/0006-routing-knowledge-access-and-policy-are-separate.md

0.41.1

changed: README.md
changed: agent-workflow-kit.package.json
changed: package.json
changed: scripts/pr-body-check.py
changed: scripts/test_pr_body_check.py
changed: scripts/test_worktree_wrapup_contract.py
changed: scripts/wrapup-land.py

0.41.0

added: docs/adr/0009-teardown-authority-is-stateless-repository-classification.md
changed: agent-workflow-kit.package.json
changed: docs/adr/0007-session-teardown-requires-provenance-bound-ownership.md
changed: scripts/pr-body-check.py
changed: scripts/test_pr_body_check.py

0.40.0 — planning ignore rules are offered, never installed

Nothing in this release requires a consumer action. kit-update reconciles it.

Several skills used to state as fact that PLAN.md, PLAN-REVIEW-LOG.md and ANNAHMEN.md are gitignored and live on disk only. In your repository that was simply untrue: neither init nor update has ever touched your .gitignore, and no installed file added those rules — so planning worktrees looked permanently dirty, cleanup refused to remove them, and a plan document could be committed by accident.

The prose is honest now. The affected skills say the artifacts are expected to be ignored and name who can add the rule, instead of asserting an installed guarantee.
/setup-workflow offers the rules. It previews the exact lines, asks first, and appends one idempotent marker block. Declining changes nothing; a re-run is a byte-identical no-op; a block you edited yourself is reported, not repaired; an artifact already tracked by git is reported separately, because an ignore rule cannot untrack it.
.gitignore stays yours. It has no manifest entry, no baseline hash and no three-way reconcile — a file the kit cannot reconcile is one it must not write uninvited. Ordinary update reconciliation never reaches the seeder. Decision record: docs/adr/0008-planning-ignore-rules-are-offered-never-installed.md.

0.39.0 — self-explaining guards, one glob dialect, a board you can create