agent-workbench: Skills for Operating AI Code Agents in Projects

Introduction

Have you ever run into situations like these when using an AI code agent?

• Work starts smoothly, but another problem appears along the way, and you lose track of progress on the original task.
• You have explained the design policy many times, but when the agent restarts in another session, it goes back to old assumptions.
• Tests appear to run, but they are not the verification commands the project actually needs.
• Whether a review comment was fixed, left open, or rejected is buried in the chat.
• A point you already made is repeated again in the next session.
• The agent says the work is done, but you cannot easily see which requirements were met, which commands were verified, which files were modified, and which review issues were closed.

These problems appear when you start using code agents in large projects. In large and complex projects, the working conditions themselves become complex. Design, requirements, tasks, reviews, verification, commands, Git status, user correction instructions, and interruptions all become intertwined.

Even in human development, this information is distributed across issues, pull requests, design documents, CI, review comments, commit history, and similar systems.

When you entrust a large task to a code agent, you also need a place to manage the work state.

Some people manage this state in Markdown.

In practice, many people create files like TASKS.md, AGENT.md, and WORKLOG.md and write the current work status there.

This is useful for starting small. It’s easy for humans to read, and you can track differences using Git.

However, if a code agent works continuously on a large project, Markdown alone becomes hard to manage. If the file gets too large, the agent will not reliably read and interpret everything correctly every time.

• Which description is the latest?
• Which tasks are completed?
• Which review issues are unresolved?
• Which design decisions are still valid?
• Which verification commands were actually executed?
• Which precautions have already been turned into rules?

When all of this is mixed into one long Markdown file, it becomes a giant memo rather than state management. In the worst case, the agent finds a similar string with grep and mixes old state with new state.

The timeline will also be broken.

• “Was this issue resolved later?”
• “Has this design decision been reversed?”
• “Which commit is this test result for?”
• “Does this memo describe the state before the interruption or after work resumed?”
• “Is this warning a one-time comment or a rule that should be followed in the future?”

Things like this become ambiguous.

If you want to use a code agent for a large and complex project, you need a ledger that can structure the work state, track it chronologically, and retrieve it from the necessary perspectives.

That is why I created agent-workbench: a tool for storing a code agent’s work state in a structured way inside the project.

Here is the repository. https://github.com/MuNeNiCK/agent-workbench

Docs are here. https://munenick.github.io/agent-workbench/

What is agent-workbench?

agent-workbench is a work ledger for code agents. I am building it as an operational layer that helps code agents carry out long-running tasks in large, complex projects.

It is not a task management tool for humans. It is also not a replacement for Trello or GitHub Issues.

The goal is to give code agents a structured reference for the current state of work, designs, reviews, validations, evidence, and user correction instructions while they work inside a project.

The following directories will be created in the project.

.agent-workbench/
  ledger.sqlite
  designs/
  exports/
  logs/

The central file is .agent-workbench/ledger.sqlite.

This is a project-local SQLite ledger.

This is where you record work units, design packages, tasks, checklists, reviews, issues, verification results, command executions, Git commits, changed files, user correction instructions, KPTs, and related information.

In other words, agents can see and act on “structured work state that remains in the project” rather than only “the current conversation” or “a huge Markdown file”.

Why is it necessary?

Large tasks cannot be managed through chat alone

The work you want to entrust to code agents is not just file editing.

For example, tasks include:

- Understanding existing designs
- Organizing specifications and constraints
- Deciding on an implementation policy
- Breaking work down into tasks
- Implementing changes
- Performing testing and validation
- Receiving review feedback
- Fixing issues
- Re-examining the result
- Deciding whether the work is complete

In these tasks, decisions made during the process affect later work.

• Which design decisions are valid?
• Which requirements correspond to which tasks?
• Which tests should be performed?
• Which review points still remain?
• What changes should be included in this work?

If you manage these things only through chat history, the state becomes less reliable as the work continues.

Sometimes the agent misses context. For humans, it also becomes difficult to track what was written and where.

agent-workbench leaves this state in the project, not in the chat.

Markdown management tends to break down as it grows

Many people are familiar with managing work status in Markdown.

- Write TODO in Markdown
- Leave work log in Markdown
- Add design decisions to Markdown
- Paste review points in Markdown
- Write verification results in Markdown

If only humans read it, that may be enough. However, there are limits to using it as continuous state management for code agents.

First, the file keeps growing.

Agents may not read large Markdown correctly every time. Sometimes it does not fit into the available context. When the agent tries to read only the necessary parts, it may pick up old information.

Second, the timeline is fragile.

Markdown is basically a document. If you repeatedly add, edit, move, and delete content, it becomes unclear when the state changed and what caused the change.

Also, different types of state are mixed together.

When task lists, design decisions, validation logs, review issues, user corrections, and work notes are mixed into a single file, the agent searches for them as text instead of treating them as states.

In the worst case, grep picks up a line and the agent makes a decision while ignoring the timeline and state transitions.

This is dangerous for large projects.

agent-workbench puts the source of truth for work state into the SQLite ledger.

Work units, review findings, verification results, command executions, completion judgments, user corrections, KPTs, and related items are treated as structured records.

Agents switch tasks on their own

In large projects, other problems are often discovered during work.

• While updating the documentation, I noticed that the CLI was behaving strangely.
• During implementation, you realize that the assumptions in the existing tests are broken.
• During review, a design omission is found in another module.

These interruptions are not a bad thing in and of themselves.

The problem is that it becomes unclear where the original work stopped, why it stopped, and what must be checked before returning to it.

The code agent may move on to the problem at hand. When context compression or a session boundary gets in the way, the original problem is often forgotten. As a result, the original work is left behind.

agent-workbench treats units of work as work units.

Work units have states such as active, suspended, blocked, closed, reopened, and follow-up.

In addition, the activation stack records current work, interruptions, and returns.

For example, the flow is as follows.

docs work is active
  ↓
Find issues with release wrapper
  ↓
suspend docs work
  ↓
wrapper work active
  ↓
close wrapper work
  ↓
Check resume-ready and return to docs work

Rather than simply writing “I’ll come back later” in chat or Markdown, interruptions and returns are managed as work states.

Misalignment between design and implementation

In large projects, the correspondence between design and implementation is important.

You can pass design documents to code agents to implement. However, free-form design notes alone make it unclear which items are requirements, which are constraints, and which are established design decisions.

As a result, the agent “implements something that seems right.” For large projects, it is dangerous when you cannot track which requirements the implementation satisfies, which design decisions it follows, and which validations were used to verify it.

agent-workbench structures design materials in the form of Design Packages.

The Design Package includes human-readable design descriptions as well as machine-readable information such as requirements, decisions, and validation gate templates.

Requirements have stable keys like REQ-001. Design decisions have keys like DEC-001. Validation conditions are defined as validation gates.

This allows us to connect designs, tasks, checklists, implementation evidence, validation results, and review results.

Verification commands are guessed

In large projects, the correct validation command is often not simple.

cargo test alone is not enough, a feature flag is required. You may need to target only specific workspace members.

You need to use pnpm test instead of npm test. In some cases, verifying Docs generation and release wrappers is more important than regular testing.

Code agents tend to guess and execute common commands. And sometimes it reports “I tested” even though I ran the wrong command.

This can be quite dangerous for large projects.

agent-workbench allows you to record command profiles.

Fixed verification commands, recommended commands, non-recommended commands, execution results, deviation reasons, etc. can be recorded in the ledger. Before starting work, the agent checks the command profile and selects the validation commands to use for the project.

Validation results are recorded as command usage and validation gate runs.

This makes it possible to track what commands were executed, what the results were, and what requirements were verified.

Review points keep coming

For large projects, review is rarely completed in one pass.

• Design review
• Task breakdown review
• Implementation review
• Review of differences between design and implementation
• Check if known issues have been fixed

If you handle all of these in chat or Markdown, it becomes difficult to understand which points still remain.

• Has the issue been corrected?
• Has it been fixed but not verified yet?
• Was it rejected?
• Was it derived from another point?

agent-workbench handles review plans, review runs, findings, closures, and verification separately.

Points raised in a review are recorded as findings, closures are recorded after corrections, and verification is recorded when necessary.

This is a mechanism for treating reviews as work state rather than just “comments”.

Repeating the same points

When using code agents, you may come across similar precautions many times.

• This project uses this test command.
• Do not edit this directory directly.
• Be sure to check this review perspective.
• Leave logs in this format.
• This implementation policy will not be adopted.

If these points remain only in chat, the same problem may be repeated in the next session.

The same goes for reviews. A problem that was fixed once may reappear in another task.

agent-workbench allows you to record user corrections and KPTs.

Instead of leaving them as one-off comments, you can make them available for reference in the next piece of work.

For example, organizing them as Keep, Problem, and Try clarifies what to keep doing, what went wrong, and what to try next. Additionally, recurring issues can be promoted to rules, command profiles, and checklists rather than just review comments.

This makes it harder for agents to repeat the same mistakes.

The goal is to record these points in the project ledger and check them before starting work, rather than searching chat history for “something I said before.”

There is no evidence in the completion report

Code agents tend to say “done” when it looks like the work is done. However, for large projects, a natural language completion report is not enough.

- Is the task closed?
- Are there any review points left?
- Was the verification command executed?
- Are the execution results recorded?
- Are the changed files within the intended range?
- Were Git commits created?
- Is the work compatible with the design requirements?
- Is the working directory state classified?
- Were learnings that should become user corrections or KPTs recorded?

If the agent says “complete” without evidence for these points, humans still have to confirm everything.

agent-workbench provides a close-ready gate.

close-ready is a readiness gate that confirms whether the work can be closed.

It checks tasks, checklists, reviews, issues, validation commands, repository state, work records, and related items, then blocks closure if anything is missing.

In other words, it structurally checks completion conditions before the agent says “Complete.”

What agent-workbench solves

agent-workbench moves code agent work from “on-the-fly chat” or “giant Markdown” to “project work state.”

• Check the current state before the agent begins work.
• Record design decisions and verification results during work.
• When an interruption occurs, record the reason for the interruption and the return conditions.
• When a review issue is raised, track the issue, correction, and verification.
• Record user corrections and KPTs to avoid repeating the same points.
• Check that the evidence is in place before completion.

Rather than doing this only with natural language notes, agent-workbench structures it with a CLI and a SQLite ledger. Broadly speaking, it covers the following:

- work unit
- suspension and return
- design package
- requirements
- design decisions
- task
- checklist
- verification gate
- command profile
- command execution history
- review plan
- review results
- confirmation and correction
- Git commit
- changed file
- repository state
- user correction instructions
- KPT
- work record

This allows agents to decide “what to do next” from the ledger rather than from the tone of the chat or grep results.

How to use

agent-workbench is primarily intended to be used by a code agent rather than by a human typing CLI commands directly. Humans tell the agent “what they want it to do” and “how they want it to manage its state using agent-workbench.”

Here, I will distinguish between using it from the start of a project and introducing it into an existing project.

Install

agent-workbench is installed as an Agent Skill.

To install it for a user, run:

gh skill install MuNeNiCK/agent-workbench agent-workbench \
  --scope user \
  --agent <target-agent>

To install it for a project, run:

gh skill install MuNeNiCK/agent-workbench agent-workbench \
  --scope project \
  --agent <target-agent>

For <target-agent>, specify the value that corresponds to the code agent you are using.

Using it from the start of a project

If you are using it for a new project, or when the design has not yet been finalized, do not start implementation immediately.

The flow is as follows.

1. Initialize agent-workbench
2. Create design notes or documents
3. Import design memo as Design Package
4. Conduct a design review
5. Close the design
6. Break down into tasks and checklists
7. Perform a task breakdown review
8. Check implementation-ready
9. Implement
10. Complete through verification, review, and close-ready

First, instruct the agent as follows:

Please initialize $agent-workbench for use in this project.
After initialization, report your current state, what you need to do next, and what workflows are available.

Next, pass the design to the agent. If you have already written a design, provide it.

Please use the design notes below to organize the design of this project.

Don't go into implementation yet.
Please separate and organize requirements, constraints, design decisions, verification policies, and unclear points.

<Paste design memo here>

Alternatively, if you want to create the design while consulting with an agent, use a request like this:

Use $agent-workbench to organize the design of this project together.

First, identify your objectives, requirements, constraints, design decisions, and verification methods.
If you have any questions, please do not make any decisions.
Don't go into implementation yet.

Once you have a design memo or design document, import it into agent-workbench.

Please import the design organized so far as a Design Package that $agent-workbench can understand.

Structure your requirements, design decisions, and validation gates.
After importing, please report any missing information, ambiguity, or points that require confirmation as part of the Design Package.

After importing, run a design review.

Run a design review using $agent-workbench.

Check for missing requirements, inconsistent design decisions, missing validation policies, and blockers that need to be resolved before implementation.
Please record the review results in your ledger.

If there are no problems in the design review, close the design.

Check the results of the design review and decide if the design can be closed.

If you are unable to close, please report any outstanding issues and the next necessary fix.
If possible, close the design on $agent-workbench.

Once the design is closed, proceed to task decomposition.

Based on the closed design, break it down into implementation tasks and checklists in $agent-workbench.

Please link which requirements each task corresponds to and which validation gate should be used to check.
Don't go into implementation yet.

Then run a task breakdown review.

Use $agent-workbench to perform a task decomposition review.

Are all design requirements included in the tasks and checklists?
Do they correspond to the verification gates?
Please check if any work is missing before implementation.

Confirm whether to proceed with implementation.

Check implementation-ready in $agent-workbench.

If you cannot proceed with implementation, please report the blocker and any necessary actions.
If you decide to proceed with implementation, be sure to summarize the tasks to be implemented, verification methods, and design decisions to be aware of before starting the implementation.

During implementation, record validation commands and changes.

Implement it according to the current tasks in $agent-workbench.

Please record the executed commands, verification results, modified files, and correspondence with design requirements in the ledger.
Don't guess at test commands; check the registered command profile before executing them.

If something needs to be noted during implementation, or if something should not be repeated, record it as a user correction or KPT.

Please record the current issue in $agent-workbench as a user correction.

To avoid repeating the same points in the future, please organize the scope of application, actions to avoid, and details to check next time.
Please reflect it in KPT if necessary.

Confirm close-ready before completing.

Even if you think your implementation is complete, don't close your work yet.

Check close-ready in $agent-workbench.
Please report any unfinished tasks, unresolved review points, missing validation, changed files, Git status, blockers, user corrections, or KPTs that should be recorded.
Close your work only if close-ready passes.

Introducing it into an existing project

When introducing it into an existing project, first take inventory of the current state.

Because code, design memos, issues, READMEs, tests, CI, and other project assets already exist, do not create a new design all at once. Start by importing the current project state into the ledger.

The flow is as follows.

1. Initialize agent-workbench
2. Investigate existing designs, READMEs, issues, tests, and CI
3. Organize the current state as a Design Package or work unit
4. Register existing verification commands in the command profile
5. Register existing notes and points that you do not want to repeat as user corrections or KPTs
6. Register unfinished work or known issues as a work unit
7. Check design reviews and implementation-ready as needed
8. Proceed to implementation, modification, review, and close-ready

First, instruct the agent as follows:

Please introduce $agent-workbench to this existing project.

First, initialize the ledger and explore the current repository state, existing documentation, testing methods, CI, and any outstanding work.
Don't go into implementation or modification yet.

Ask the agent to investigate the existing state.

Use $agent-workbench to take stock of the current state of this project.

Review READMEs, docs, issue notes, test commands, CI configurations, existing design decisions, and any work that appears unfinished.
Please organize the items that should be registered in the ledger.

Register verification commands.

Please research the validation commands that should be used for this project and register them in the $agent-workbench command profile.

Please separate recommended commands, commands to avoid, and verification commands for each purpose.
Don't register by guessing; check the README, CI settings, package settings, and existing scripts.

Register existing precautions and points that you do not want to repeat.

Organize points that should not be repeated in the future, along with precautions that should be observed in this project.
Please register them as user corrections or KPTs in $agent-workbench.

Please separate the target scope, actions to avoid, and details to check in the future.

Convert existing designs into Design Packages.

Organize the existing design information and import it as a $agent-workbench Design Package if necessary.

Separate and organize requirements, constraints, design decisions, and verification gates.
If there are any points that are unclear or the design is ambiguous, please report them as confirmation items rather than filling in the details.

Turn existing unfinished work into a work unit.

Identify unfinished or ongoing work in your current project.
Please register it as a work unit in $agent-workbench.

For each work unit, record its purpose, current state, blockers, and what needs to be done next.

If you want to resume work on an existing project, first have the agent report the current status.

Check the current status using $agent-workbench.

Please report the active work unit, suspended work units, unresolved review points, registered command profile,
user corrections, KPTs, current Git state, and next steps to take.
Then make an implementation plan.

Before proceeding with implementation, check implementation-ready.

Check implementation-ready in $agent-workbench to see if you are ready to proceed with this work.

Please report any missing designs, unresolved issues, unregistered validation commands, or repository state issues.
If there are no problems, please specify the target task and verification method before proceeding with implementation.

Always pass close-ready before completing.

Check $agent-workbench for close-ready before marking the work as complete.

Please report unfinished tasks, unresolved review points, insufficient validation, changed files, Git status, blockers,
and any remaining user corrections or KPTs that should be recorded.
If close-ready does not pass, do not close the work and suggest the next necessary action.

Main concepts

Ledger

A ledger is a project-local SQLite database.

.agent-workbench/ledger.sqlite

This is where you record work status, designs, reviews, validations, evidence, and related information.

The key is to use a structured ledger as the source of truth, rather than Markdown or chat.

Work unit

A work unit is a unit of work performed by an agent.

For example:

- Implement release workflow
- Reorganize public docs
- Create a design package
- Correct review issues

Work units have states such as active, suspended, blocked, closed, reopened, and follow-up.

This allows you to track the current state of your work.

Activation stack

The activation stack is a mechanism for handling suspension and resumption.

For example, record the following flow.

docs work is active
  ↓
release wrapper issue found
  ↓
suspend docs work
  ↓
wrapper work active
  ↓
close wrapper work
  ↓
Check resume-ready and return to docs work

The resume-ready gate checks whether the design state, review state, repository state, or prerequisites have changed.

Design Package

A Design Package structures design materials in a format that is easy for agent-workbench to handle.

There is no need to write in a special format from the beginning.

The source material can be a regular design memo, a Markdown design document, a text file, or notes organized during a conversation.

The important thing is to capture the design materials in a form that can be tracked by agent-workbench, rather than just treating them as a giant memo.

When imported as a Design Package, the information contained in the design can be divided and handled as follows.

- requirements
- constraints
- design decisions
- verification policy
- verification gate
- unresolved confirmations

Requirements have keys like REQ-001. Design decisions have keys like DEC-001.

This allows you to link implementation tasks, checklists, validation gates, reviews, and implementation evidence to design requirements.

This lets you say, “I implemented this requirement with this task and satisfied it with this verification,” rather than simply “I read the design and implemented it.”

Readiness gate

A readiness gate confirms whether work can proceed to the next stage.

Typical gates are listed below.

Gates are basically read-only.

Instead of automatically progressing through states, it shows you what evidence is missing and what you need to do next.

Instead of letting the agent decide that something is probably okay, assumptions are reduced by passing gates at each milestone.

Review

agent-workbench incorporates reviews into the workflow.

Review plans, review targets, review results, findings, finding classifications, corrections, and verification are handled separately.

Reviews are also divided by type.

We also separate fresh reviews and resume reviews.

A fresh review is a new, independent review. A resume review is a review to confirm whether known issues have been corrected.

In general, fresh reviews are used to determine completion.

Evidence

Evidence records that the work was actually done.

For example:

- command usage
- validation run
- repository snapshot
- Git commit
- changed file
- implementation evidence
- review finding and closure
- work record

The close-ready gate looks at this evidence and confirms whether the work can be closed.

Command profile

A command profile is a mechanism for recording project-specific verification commands.

Code agents tend to guess test commands.

However, the correct command varies depending on the project.

Record fixed commands, recommended commands, deprecated commands, deviation reasons, and related details in a command profile so agents do not have to guess every time.

User corrections and KPT

User corrections and KPTs are mechanisms for avoiding repeated problems.

They leave notes for the code agent about things noticed during work and things to avoid next time.

For example:

- This project uses this test command
- Do not edit this directory directly
- Do not repeat this type of review issue
- Always run this validation before completing
- This design policy will not be adopted

If you only mention these points in chat, you may need to make the same point again in the next session.

With agent-workbench, these points can be stored in the ledger as user corrections or KPTs.

By organizing things as Keep, Problem, and Try, you can clarify what to continue, what went wrong, and what to try next.

Additionally, recurring issues can be reflected in command profiles, checklists, review perspectives, and work rules.

When to use it

When using code agents in large and complex projects

agent-workbench is for large projects.

It works well for tasks that include design, implementation, review, verification, fixes, and completion checks.

When spanning multiple sessions

Use it when you need to resume work the next day or hand it off to another agent.

Instead of relying on chat history or giant Markdown files, you can inspect the ledger in the project and resume from there.

When you want design-driven implementation

Use it when you want to treat requirements, decisions, and validation gates as a Design Package and connect them to tasks, reviews, and implementation evidence.

When you want stricter review and completion checks

Use it when you want the agent to check the close-ready gate, review results, validation evidence, and repository state before saying “I’m done.”

When you do not want to repeat the same corrections

Use it when you want to record user corrections or KPTs and carry the same assumptions into the next agent session.

Conclusion

Code agents have become quite useful for large projects.

However, the larger the work, the more difficult it becomes to manage state using chat or Markdown alone.

Is the design valid? Which tasks have been completed? Which review points remain? Which verification command should I use? Is there enough evidence to close the work? Are you repeating something you warned about before?

If agents judge this information from chat tone or grep results every time, their work becomes unreliable.

If you want to use code agents for large projects and handle design, review, verification, completion decisions, and recurrence prevention properly, give it a try.