| name | agent-workbench |
| description | Use when managing long-running coding-agent work with structured project memory, task tracking, design decisions, review loops, work records, and classified Markdown exports across Agent Skills-compatible coding-agent workflows. |
| license | MIT |
Agent Workbench
Use this skill when a project needs durable agent operating state: checklists,
design decisions, review findings, work records, or compatibility notes that
should survive across sessions without forcing the agent to grep old Markdown
logs.
CLI Entry
This skill uses the Agent Workbench CLI through the Linux x86_64 wrapper bundled
with the installed skill.
Resolve the wrapper path relative to this SKILL.md file. Do not assume the
current repository has a top-level scripts/ directory. If this skill is
installed at <installed-skill-dir>/SKILL.md, run:
sh <installed-skill-dir>/scripts/agent-workbench.sh <agent-workbench-args>
The wrapper uses the bundled CLI_VERSION file by default, downloads the
matching Linux x86_64 release asset, verifies its SHA256 checksum, caches it
under the user's cache directory, and then executes it.
When the skill lives inside an Agent Workbench source checkout, the wrapper
first uses the checkout's already-built target/debug/agent-workbench or
target/release/agent-workbench binary when present. This keeps project-scope
development installs aligned with the source tree under review. A normal
installed skill without a source checkout continues to use CLI_VERSION.
When references show commands as agent-workbench ..., run the same arguments
through the wrapper. For example, agent-workbench status means:
sh <installed-skill-dir>/scripts/agent-workbench.sh status
Command Scope
The wrapped CLI is the command authority. Use agent-workbench help and
agent-workbench <command> --help through the wrapper when exact syntax matters.
Common command groups include:
agent-workbench initagent-workbench update inspectagent-workbench update apply --expected-current <identity>agent-workbench update restore --backup <handle> --expected-current <identity>agent-workbench statusagent-workbench nextagent-workbench doctor validation-linksagent-workbench doctor validation-links --repairagent-workbench doctor validation-links --auditagent-workbench migration task-history planagent-workbench migration task-history ambiguity-listagent-workbench migration task-history authority-recordagent-workbench migration task-history ambiguity-decideagent-workbench migration task-history applyagent-workbench migration task-history auditagent-workbench rules applicable --scope currentagent-workbench authority listagent-workbench review run addagent-workbench review adjudicateagent-workbench finding decideagent-workbench verification adjudicateagent-workbench design initagent-workbench design importagent-workbench design refreshagent-workbench design approveagent-workbench requirement listagent-workbench design-decision listagent-workbench gate-template listagent-workbench acceptance addagent-workbench authority event addagent-workbench correction addagent-workbench correction listagent-workbench decision addagent-workbench decision searchagent-workbench command fixed addagent-workbench command preferagent-workbench command listagent-workbench command usage addagent-workbench command usage listagent-workbench command usage promoteagent-workbench command deviation addagent-workbench command deprecateagent-workbench task addagent-workbench task listagent-workbench task closeagent-workbench task accept-out-of-scopeagent-workbench phase createagent-workbench phase listagent-workbench phase showagent-workbench phase assignagent-workbench phase dependency addagent-workbench phase dependency listagent-workbench phase dependency satisfyagent-workbench phase dependency acceptagent-workbench phase trace listagent-workbench phase trace decideagent-workbench phase inventoryagent-workbench phase rescopeagent-workbench phase splitagent-workbench phase close-readyagent-workbench phase closeagent-workbench phase accept-out-of-scopeagent-workbench decompose designagent-workbench trace derive-taskagent-workbench checklist listagent-workbench checklist item listagent-workbench checklist item closeagent-workbench checklist closeagent-workbench stale listagent-workbench stale acceptagent-workbench stale closeagent-workbench gate design-ready --dry-runagent-workbench gate implementation-ready --dry-runagent-workbench gate close-ready --dry-runagent-workbench gate resume-ready --maturity basic|trace-aware|repo-aware --dry-runagent-workbench gate selectagent-workbench gate recordagent-workbench gate run listagent-workbench review scope startagent-workbench review policy addagent-workbench review plan addagent-workbench review plan listagent-workbench review plan waiveagent-workbench review plan target addagent-workbench review run addagent-workbench review run listagent-workbench review adjudicateagent-workbench finding addagent-workbench finding classifyagent-workbench finding decideagent-workbench finding listagent-workbench finding verifyagent-workbench verification adjudicateagent-workbench finding accept-out-of-scopeagent-workbench closure addagent-workbench closure correction-beginagent-workbench closure transition applyagent-workbench closure readyagent-workbench closure supersedeagent-workbench review-contextagent-workbench evidence addagent-workbench coverage addagent-workbench export designagent-workbench export planagent-workbench repository addagent-workbench repository listagent-workbench repository snapshot addagent-workbench repository snapshot listagent-workbench repository dirty addagent-workbench repository classify addagent-workbench repository compare addagent-workbench repository commit addagent-workbench repository file addagent-workbench git commit addagent-workbench git files addagent-workbench work startagent-workbench work activateagent-workbench work remediate --finding <finding-id>agent-workbench work suspendagent-workbench work interruptagent-workbench work resumeagent-workbench work reopenagent-workbench work follow-upagent-workbench work closeagent-workbench work blockagent-workbench work unblockagent-workbench work abandonagent-workbench work forkagent-workbench resume-check --maturity basic|trace-aware|repo-awareagent-workbench record createagent-workbench record command addagent-workbench record commit addagent-workbench record file addagent-workbench record link commandagent-workbench record link commitagent-workbench record link fileagent-workbench record export <record-id> --output <path>agent-workbench kpt start --from correctionsagent-workbench kpt item addagent-workbench kpt item listagent-workbench kpt item convert
Load only the reference needed for the current operation:
references/quickstart.md for first project setup and the normal
design-to-implementation path.references/cli-workflow.md for the compact command sequence during normal
coding-agent work.references/review-recipes.md for review role selection, fresh/resume review
rules, finding lifecycle, and completion review prompt requirements.references/interruption-recovery.md for suspend, interrupt, resume, reopen,
follow-up, and fork flows.references/repository-validation.md for validation, repository, Git, and
work-record evidence commands.references/close-ready-troubleshooting.md when close-ready is blocked.references/state-recovery.md when normal commands report invalid
validation-run project links or when historical phase-bearing task data needs
the explicit task-history migration.
References
Use the local design references in this repository when changing the skill or
CLI. Do not treat old Markdown exports as standing policy unless they are linked
from current managed project state.
Rules
- Prefer structured project memory over broad Markdown history searches.
- Use
agent-workbench status and agent-workbench next before long-running
work, executed through the wrapper path resolved relative to this skill.
- If
status or next reports finding_remediation: true or
finding remediation, inspect finding_remediation_count, then run
agent-workbench finding list --status open to explicitly retrieve the
project-internal closure contracts. Implementation is allowed only in the
printed owning work unit and only to satisfy those contracts. Keep the findings open. After implementing and
testing each fix, run its exact printed closure ready command; do not launch
resume review before that boundary. Stale design-derived state always takes
precedence over this exception.
- If
status or next reports phase_blocked: true or blocked phase, do
not start implementation, edit code, record implementation evidence, or run
implementation validation as the next action. Follow the printed blocker
command for finding classification, closure, verification, gate repair, or
work unblock first.
- A printed
work remediate --finding <id> is the sole activation path for an
eligible registered implementation finding, including an inactive owner.
Run that exact command before editing. It creates or reuses only the audited
scoped activation selected by the resolver; do not substitute work activate,
work reopen, or changes outside the supported CLI.
- In
finding_remediation, edit only the listed closure contracts. work suspend, work block, and work abandon are the only work lifecycle
alternates; they apply only to the active bound owner. Finish a selected
finding with closure ready, then run the exact finding-fix resume review and
matching finding verify before relying on a later fresh review.
- In
source_correction, edit only the printed typed Markdown surfaces after
closure correction-begin. Apply declared transition: tokens in ordinal
order with closure transition apply; do not run the underlying task,
decomposition, phase, dependency, or stale mutation directly. Run closure ready only after every file postcondition and transition token is complete.
- For legacy partial or duplicate current decomposition, use only a declared
design-reconcile:<design>/<work>/<canonical-checklist> transition. Apply
stale tokens first, reconcile before using generated aliases, replace phase
memberships before predecessor or rejected numeric task disposition, and
keep normal design-decompose strict. Reconciliation may replace a uniquely
matched completed predecessor membership inside a closed phase with the
canonical task while preserving the phase's closed state; never create an
open replacement phase for completed work. If the registered closure lacks these
tokens, use authority-backed closure supersede; do not improvise commands.
- After
closure ready, generate review-context finding-fix, record the
independent verification claim with review run add, and record the owner's
separate decision with verification adjudicate. A resume review never replaces
the later fresh unbiased completion review.
- Use
agent-workbench rules applicable --scope current before acting on a
resumed or interrupted work unit.
- Before planning, editing, or reviewing, run
agent-workbench correction list
and apply active user corrections for the current scope.
- Treat Design Package authority as Markdown-only. Every manifest path under
arc42, requirements, and validation must name a regular .md file.
Keep JSON, test vectors, fixtures, generated output, binaries, and other data
outside the Design Package; specify their required behavior in Markdown and
validate them through repository evidence.
- Before choosing validation or test commands, run
agent-workbench command list
and prefer applicable fixed or preferred command profiles.
- Treat managed project state as a private implementation detail. Do not use
unsupported tools, internal queries, or implementation names during
normal agent workflow. Use Agent Workbench CLI commands and
review-context.
If a required state question has no CLI or review-context answer, report the
missing product surface as a blocker instead of bypassing the CLI.
- If normal commands report invalid validation project links, use
agent-workbench doctor validation-links for read-only diagnosis.
Run agent-workbench doctor validation-links --repair only when the complete
plan is repairable. It preserves a recovery point, repairs known
parent/dependent links atomically, records an immutable audit, and
commits only after migration and integrity validation pass. Use --audit to
list prior repairs. An unrepairable result is a blocker, not permission to
inspect or alter private managed state outside the CLI.
- Historical task migration is an explicit operator action. Normal task, phase,
refresh, reconciliation, status, and resume commands must never apply it.
Follow
references/state-recovery.md, bind every mutating step to the opaque
handles printed by the read-only plan, and stop on a stale handle or unresolved
ambiguity.
- When repeated corrections, command drift, recurring findings, or recurring
close/resume failures appear, propose or run
agent-workbench kpt start and
inspect items with agent-workbench kpt item list.
- Use read-only gates before state-changing steps:
design-ready,
implementation-ready, close-ready, and resume-ready.
- For design-derived implementation work, create the required review plans and
clean runs before relying on gates:
design_review for design-ready,
design_task_decomposition for implementation-ready, and both
design_implementation_diff plus implementation_review for close-ready.
- Design-derived implementation work must use explicit implementation
activation for the work unit produced by
decompose design:
work activate --implementation --design-version <design-version-id> <work-unit-id>. work start --implementation --design-version ... and
plain reserved aliases such as work start implementation are not valid
implementation paths.
- Use
decompose design for normal design-to-plan conversion. Use
trace derive-task for explicit manual links or corrections.
- When an aggregate work unit needs internal scheduling or smaller reviewable
chunks, use work phases instead of inventing task order from intuition. Create
ordered phases with
phase create, assign tasks with phase assign, inspect
trace bundles with phase inventory, and run phase rescope --dry-run or
phase split --dry-run before any cross-work-unit move. Cross-phase
dependencies outrank simple phase order and must be satisfied or
authority-accepted with phase dependency commands.
- For grouped phase reviews that remain inside the aggregate work unit, add a
phase review target with
review plan target add --plan <id> --type phase --phase <phase-id> and use
review-context <kind> --design-version <id> --work-unit <id> --phase <phase-id>.
Split phase work units use normal work-unit-scoped review contexts.
- Run
phase close-ready <phase-id> --dry-run before phase close. Closing a
phase does not close the aggregate work unit; aggregate close still requires
gate close-ready --dry-run.
- Use
stale list to inspect stale design-derived records. Use
stale accept <record-type> <id> --reason "<reason>" when a stale record
should remain auditable without changing its lifecycle status. Use
stale close <record-type> <id> --reason "<reason>" for stale
task_derivation, checklist, or validation_gate records that should be
closed. Do not use task accept-out-of-scope for stale validation gates;
that command is only for task scope exceptions.
- Record implementation evidence and coverage items for design-derived tasks,
then close completed checklist items with
checklist item close <item-id>
and close their parent checklist with checklist close <checklist-id>.
Use checklist item list --checklist <checklist-id> to inspect items. Do
not use stale disposition commands for non-stale checklist completion.
- Use
review-context when launching a review agent so the prompt is focused
on the relevant design version, work unit, or review kind. Pass the printed
target value to review run add --target. The command
records a completed review; it does not launch or perform the review.
Design-derived gates require clean fresh runs tied to that context with
trusted provenance such as --provenance external_agent --external-agent-id <agent-id> --provenance-ref <review-output-ref> or
--provenance human_review --provenance-ref <review-output-ref>.
Self-recorded clean runs must not be used to satisfy readiness gates.
- If a required review plan was created for the wrong scope, is no longer
required, or is intentionally superseded, do not inspect or alter private
managed state. Run
agent-workbench review plan waive <review-plan-id> --reason "<reason>". The reasoned user action is the audit record.
- For final completion checks, use a fresh unbiased review unless the user
explicitly asks only for resume verification of known findings. Do not use a
resume review as the final completion signal by default.
- When asking a review agent whether the project is complete, include the skill
package itself in the review scope. A project is not complete if the CLI and
tests match the design but the installed skill cannot guide a fresh coding
agent through setup, reviews, implementation, interruption recovery,
close-ready troubleshooting, and evidence recording.
- Use
resume-check only when a durable result should be recorded for an actual
resume operation.
- Record reusable validation commands with
command fixed add and command runs
with command usage add so work records can link to stable evidence.
- Record selected validation gate results with
gate record; list prior runs
with gate run list.
- Register every Git boundary that can affect the task. For repo-aware resume,
every registered repository needs suspend and current snapshots plus classified
comparisons.
- Record repository snapshots, dirty entries, classifications, resume
comparisons, close comparisons, commits, and file changes when repository
state matters to close or resume decisions.
- Create work records with
record create and link commands, commits, and files
when they are available. Manual commit/path links can be recorded first; later
repository commit add and repository file add entries backfill structured
Git identities when the match is unambiguous.
- Use
work suspend, work interrupt, work reopen, and work follow-up to
preserve the activation stack before switching tasks.
- Treat accepted design decisions as durable constraints until the user changes them.
