Workbench Capstone

In plain words

Every semester your project group rebuilds the same folders, rules and scripts from scratch. A workbench pack stops that. It is one versioned folder holding the agent's rules, schemas and scripts, plus a single installer that drops it into any repo the same way each time. Copy it, run it, and the agent is set up correctly on day one.

How it flows

A tiny example

pack = load_pack("agent-workbench-pack")
install(pack, repo="my-project")

for task in board:
    if not in_scope(task.path):
        block(task)
        continue
    result = run_step(task)
    if verify(result):
        mark_done(task)

Notice the scope check comes before any work, and nothing is marked done until the verify gate agrees.

What you will learn

• How to pack everything an agent needs into one folder you can copy into any project.
• What belongs inside that pack, and what must stay out.
• Why the pack needs a version number and a safe uninstall.
• How to write a tiny harness that runs a task, checks its scope, and gates the result.

The problem, simply

Think about your final-year project group. Every semester somebody sets up the same things again: the folder structure, the rules document, the checklist for who reviews what, the small script that runs the tests. Karthik has it in his laptop, Sneha has a slightly different copy, and the shared Google Doc is two months old.

By the time you finish, nobody knows which version is the real one. So next semester, you build it all again from zero.

The same thing happens with AI agents at work. Over this module you built separate pieces: rules for the agent, a policy for retries, a handoff note format, a reviewer checklist, a state file, a task board, a scope contract. Seven surfaces. If they live in seven different chat histories, they are gone in a month.

See, the fix is boring and it works. Put all of it in one versioned folder with one install command. Copy the folder into any repo, run the installer, and the agent is working reliably the next morning.

The idea

The pack is a recipe, each install is a serving

A workbench pack is just a directory with a fixed shape. Nothing magical inside.

Inside the pack there are four kinds of things:

• Docs — the agent rules, the reliability policy, the handoff protocol, the reviewer rubric. These are the rules of the house.
• Schemas — the shape of the agent state file, the task board, and the scope contract. These are the contract.
• Scripts — init the workbench, run with feedback, verify the result, generate a handoff. These are the runtime.
• An installer — one script that lays all of it down.

Plus a README and a VERSION file at the top.

What stays out

This is the part people get wrong. Three things must not go inside the pack.

Project-specific tasks. Those belong on the target repo's own board, not in a reusable pack. Vendor SDK calls, meaning code tied to one particular agent framework — the moment you put that in, the pack only works for one tool. And team onboarding prose; the pack sits next to your onboarding docs, it does not swallow them.

IMP

Note: A pack that is framework-agnostic survives your company switching tools next year. A pack full of one vendor's imports does not.

VERSION is a contract, not marketing

The pack carries a VERSION file, exactly like package.json or pyproject.toml in your normal projects.

Change a schema or a script in a way that needs migration, bump the major number. Add something new, bump the minor. Fix a typo in a doc, bump the patch. The installer writes that version into the target repo, so later you can see which pack version this repo was set up with.

One source, many tools

Suppose Priya's team uses three different coding assistants. Nobody wants to maintain three rule files that slowly drift apart.

So the installer keeps one real file, AGENTS.md, and makes links to it at whatever path each tool expects. One source of truth, fanned out. If you ever find yourself forking the pack to support one tool, something has gone wrong.

Uninstall must refuse sometimes

The uninstaller removes what the pack owns: docs, schemas, scripts, the rules file. It never touches agent_state.json, the task board, or the outputs folder.

IMPRemember: state belongs to the user, not to the pack. If those files have uncommitted changes, the uninstaller should stop and say so rather than cleaning up.

The three pieces that make it a harness

A pack is not just files sitting there. When it runs, three things work together in a loop.

The scope check asks: is this file allowed to be touched? The gate asks: did the work actually pass? The loop asks: should we try again, or stop?

Build it

Here is that whole harness in one small file. The "model" is fake so nothing goes to the internet.

"""A tiny workbench harness: loop + scope check + verification gate."""

# The scope contract: only these path prefixes may be touched.
SCOPE = {"allow": ["src/", "tests/"], "max_attempts": 3}

# The task board. Each task says what to change and how to check it.
BOARD = [
    {"id": "T1", "path": "src/billing.py", "want": "fix rounding"},
    {"id": "T2", "path": "deploy/prod.tf", "want": "raise memory"},
    {"id": "T3", "path": "tests/test_cart.py", "want": "add case"},
]

STATE = {"pack_version": "1.2.0", "done": [], "blocked": []}

def fake_model(task, attempt):
    """Pretend agent. First try on T3 is sloppy; second try is clean."""
    ok = not (task["id"] == "T3" and attempt == 1)
    return {"path": task["path"], "note": task["want"], "tests_pass": ok}

def in_scope(path):
    """Scope check: reject anything outside the allowed folders."""
    return any(path.startswith(prefix) for prefix in SCOPE["allow"])

def gate(result):
    """Verification gate: work counts only if the checks pass."""
    if not in_scope(result["path"]):
        return False, "out of scope"
    if not result["tests_pass"]:
        return False, "tests failed"
    return True, "ok"

def run(task):
    """Loop: retry a task until the gate passes or attempts run out."""
    for attempt in range(1, SCOPE["max_attempts"] + 1):
        result = fake_model(task, attempt)
        passed, why = gate(result)
        print(f"  attempt {attempt}: {why}")
        if passed:
            return True, why
        if why == "out of scope":
            return False, why  # retrying will not help
    return False, "gave up"

for task in BOARD:
    print(f"{task['id']} -> {task['path']}")
    passed, why = run(task)
    bucket = "done" if passed else "blocked"
    STATE[bucket].append({"id": task["id"], "why": why})

print("\nstate:", STATE)

Look at three things in the output. T1 passes on the first attempt. T2 is refused immediately because deploy/ is outside the scope contract, and the loop does not waste retries on it. T3 fails once, retries, and passes.

That is the whole workbench in miniature: a loop that stops, a gate that judges, and a scope that says no.

Where you will see this

• Coding agents like Claude Code and Cursor read a rules file from your repo root, which is exactly the docs part of a pack.
• Company internal platform teams ship a "starter kit" repo so every new service gets the same CI, lint, and agent setup on day one.
• GitHub template repositories, where "Use this template" gives every team the same known-good baseline.
• Support bots at Swiggy or a bank, where the same policy documents and escalation rules get deployed to many bot instances at once.
• Any team that has a create-app style command that scaffolds a project in one line.

Common mistakes

• Keeping the workbench in chat history or a shared doc. It gets stale, then everyone quietly builds their own copy, and now there is no standard at all.
• Putting project tasks inside the pack. The pack then only fits the one project it was born in, and nobody else can use it.
• Importing one framework's SDK in the pack scripts. You have locked yourself in. When the team moves tools, the whole pack is thrown away.
• An uninstaller that deletes state files. Somebody loses a half-finished task board and stops trusting the pack forever.
• No version file. Six months later you cannot tell why the same pack behaves differently in two repos.

Warning

Warning: An installer that is not idempotent is worse than no installer. Running it twice must not duplicate files or overwrite a repo's live state.

If they ask in an interview

Q: How would you make an agent setup reusable across many repositories?

A: I would package the rules, schemas, and scripts into one versioned directory with a single idempotent installer. Each repo records the pack version it was installed against, so drift is visible. Project-specific tasks and vendor SDK calls stay out so the pack works anywhere.

Q: What do you keep out of a reusable pack, and why?

A: Project tasks, vendor-specific SDK code, and team onboarding prose. Tasks belong on the target repo's own board, vendor code locks the pack to one tool, and onboarding prose is company-specific. Keeping them out is what makes the pack drop-in.

Q: How should the uninstaller behave?

A: It removes only what the pack owns: docs, schemas, scripts, and the rules file, ideally with an option to keep the rules file. It must never delete the agent state, the task board, or outputs, and it should refuse to run when those files have uncommitted changes.

Try these

1. Take the code above and add a --dry-run mode: print what each task would do without updating the state. Notice how much easier the loop is to debug.
2. Add a fourth task that touches docs/readme.md and decide whether docs/ should be in scope. Write one line defending your choice.
3. Write a tiny check_version function that compares a pack version string to a version recorded in the state and prints migration needed when the major numbers differ.
4. Sketch, in plain text, the folder layout you would ship for your own final-year project, and mark each file as in-pack or out-of-pack.

Words, simply

Quick recap

• Put every workbench piece in one versioned folder with one idempotent installer, so nobody rebuilds it from scratch.
• Tasks, vendor SDK code, and onboarding prose stay out; docs, schemas, and scripts stay in.
• At runtime the pack is just a loop, a scope check, and a gate — and state always belongs to the user, not the pack.