dev-team (for claude)

A Claude Code plugin for projects you need to come back to.

Here is the problem it solves. You close the session halfway through a feature. A week passes, the session compacts, or you open a new terminal on another machine, and the thread that held everything is gone or blurred. Claude Code can resume a past session, but a saved conversation is a transcript, not project memory: compaction summarizes the specifics away, it does not follow a fresh clone or reach a teammate, and it was never a structured set of tasks with acceptance criteria that a future agent could just pick up and act on. So you end up re-explaining. Every time.

dev-team makes that moment boring: the project's memory lives in files on disk, structured so a session that starts with zero context can read them and carry on from exactly where the last one stopped.

This is the Claude Code plugin. There is a sibling native pi build that does the same job; this one runs as a Claude Code plugin and wires its three tiers straight to Anthropic's opus/sonnet/haiku ladder, which is why a few details below differ from the pi version.

What it's actually trying to do

Treat cold starts as the normal case. Not as recovery, not as a special mode. Every task document, decision, and report is written so a future agent with no memory of the conversation can act on it. If acting on a document requires a fact that only exists in some earlier chat, that document is considered defective and gets the fact written into it.

Get things right without you having to babysit. Work is verified by an agent that never saw the implementation, judged against the acceptance criteria rather than against the implementer's own account of what they did. Higher-stakes work additionally gets an adversarial pass. When a task fails verification three times, the loop stops and the director re-specs it instead of trying a fourth time on the same broken premise.

Stay small. There is no daemon, no database, no server, no MCP endpoint. It is markdown files, some agent definitions, a few shell scripts for the parts that should be deterministic rather than inferred, and three hooks. If you deleted the plugin tomorrow, the state folder in your project would still be readable.

Leave you holding the wheel. Nothing kicks off on its own. Setup only happens when you ask for it by name, cleanup only runs when you ask, and every plan the director produces is something you can argue with. When an agent disagrees with your call it says so once, in writing, in the record, and then does what you decided.

How a session goes

Starting fresh in a new project:

/start

It asks you what you are building, what the stack is, how to run and test it, what the constraints are. It figures out your VCS instead of assuming git (that answer is recorded in one place, PROJECT.md, and every later command that touches version control reads it from there). Then the director cuts the first tasks.

Already have a codebase?

/infer-start

Same outcome, except the charter gets written from evidence in the repo instead of from an interview, and you review it.

From then on the loop is short:

/standup        where things stand, read-only, safe to run any time
/implement      run the focus task (or several at once), then verify automatically
/spec           hand the director a new goal to break down
/checkpoint     write down everything a cold session would need

Next session, in a new terminal with nothing in context:

/pickup

which rehydrates from the manifest and the latest checkpoint, checks that the workspace actually matches what the state files claim, and tells you what is next. The SessionStart hook has usually already injected the manifest before you type anything, so even a session where you forget to run /pickup starts out knowing the project exists.

Who is on the team

One director (Opus) plans, decides, and rules on disputes. A planner (Sonnet) does the mechanical decomposition labor underneath it. Five tracks do the work: dev, research, docs, redteam, and qa, each available at three tiers (hi = Opus, med = Sonnet, low = Haiku). The agents below has the full roster and what each one is for.

Every task carries two independent stamps, and keeping them separate is deliberate:

• tier answers "who should implement this", and the answer is the cheapest agent that will succeed.
• rigor answers "how hard do we check it", and the answer comes from blast radius.

A one-line config change in the payment path is tier: low, rigor: hi. Trivial to write, expensive to get wrong. Collapsing these into a single "importance" number is what makes teams either overpay for simple work or underverify dangerous work.

Two more agents sit outside the grid entirely: a completeness advocate and a simplicity advocate, who exist only to argue. /debate puts them against each other on a contested design question and has the director rule, with the losing argument preserved in the record rather than smoothed over.

Where everything gets written

In your project, at .claude/state/:

MANIFEST.md      the index, the counters, the current focus. The cold-start entrypoint.
PROJECT.md       the charter: goal, stack, commands, constraints, VCS.
ROSTER.md        who is on the team, including local hires.
tasks/           units of work, one agent one session each
steps/           execution plans
adrs/            decisions, including the alternatives that lost
research/        questions answered with evidence
reports/         what was done and how it was checked
feedback/        defects, escalations, redteam findings, your own notes
debates/         positions plus the director's ruling
handson/         test sessions waiting on you
checkpoints/     session snapshots

Fair warning: this tree is written for machines, not for you. It is terse on purpose, because every token in it gets re-read by every future agent. There is a README.md inside it whose entire job is to tell a human who wandered in to go run /standup instead. Your project's real documentation (the README, the guides) lives at the project root where it belongs, owned by the docs track, and /document exists to keep it honest.

Install

The repo doubles as its own marketplace, so GitHub is the whole distribution. Nothing to host, nothing to clone:

claude plugin marketplace add aashishvasu/dev-team-claude
claude plugin install dev-team@aashishvasu

Restart Claude Code so the agents, skills, and hooks load. Then /start in a new project, or /infer-start in an existing one.

Later, to pick up a new version:

claude plugin update dev-team

That one also needs a restart to take effect. Projects already using dev-team will notice the change on their own: their SessionStart hook flags the roster as stale until /audit regenerates it, which is the intended upgrade path rather than an error.

The agents

Nineteen of them ship with the plugin. Four have named jobs:

Agent	Model	What it is for
director	Opus	Planning and judgment, never implementation. Decomposes goals into tasks, assigns track and tier, writes ADRs, rules debates, triages feedback, re-specs after a failed verify.
planner	Sonnet	Mechanical planning labor one rung down. Writes steps docs for already-specced tasks, drafts task docs from an approved outline. Never decides.
advocate-completeness	Sonnet	Argues the fuller option in a debate: edge cases, failure modes, security, migration paths. Writes nothing to state.
advocate-simplicity	Sonnet	Argues the leaner option: YAGNI, fewer dependencies, deletion over addition, maintenance cost. Writes nothing to state.

The other fifteen are the five tracks at three tiers each. Same track means same kind of work; the tier is how much judgment the work needs.

Track	hi (Opus)	med (Sonnet)	low (Haiku)
dev	Ambiguity to resolve, cross-cutting changes, performance-critical or novel code, root-cause hunts across subsystems	Standard features and bugfixes where the codebase already shows the pattern to follow	Mechanical, fully specified edits: renames, config, boilerplate
research	Feasibility studies, architecture comparisons, deep codebase archaeology, evaluations needing a throwaway prototype	How a library or subsystem works, evaluating one dependency against a need	Lookups with exactly one right answer
docs	Information architecture: designing a docs set, structuring an API reference	Guides, README sections, changelogs where the structure already exists	Docstring sweeps, applying a rename across docs, dead links
redteam	Threat modeling, injection and authz hunting, proof-of-concept exploits against this codebase	Focused adversarial pass on one surface: hostile inputs, error paths, races	Rerunning existing checklists, retesting old findings to confirm fixes hold
qa	Test strategy where designing the check is itself hard: concurrency, property-based testing, harness design	The default /verify agent. Also writes tests and reproduces reported defects	Running existing suites, bisecting a failing test

Low tier refuses to start without a steps doc. That is the deal that makes Haiku safe to use: it does not get handed a task and left to interpret it, it gets handed an ordered list someone else already thought through. If no steps doc exists, the task is not a low-tier task yet.

Agents also never allocate their own document IDs. The skill that spawns them claims the IDs up front and passes them in, giving each concurrent agent a disjoint block so two of them cannot collide on T-0007. A concurrent run keeps every number it handed out rather than recycling the ones nobody used, so the numbering can have gaps in it. A gap is not a lost document.

Hiring your own

When the five tracks genuinely do not fit your project, /hire forges a project-local specialist. The director evaluates whether the need is real, designs the agent around your specifics, and it lands in .claude/agents/local-*.md (the only directory Claude Code will actually spawn from) with an ADR recording why it had to exist.

Local agents read the same law as everyone else, from .claude/dev-team/, which holds byte-for-byte copies of the protocol, guidelines, and templates. They are copies rather than summaries for a reason: plugin paths do not resolve inside your project's files, and a verbatim copy means checking for drift is a cmp, not a judgment call. scripts/gen-roster.sh syncs them and regenerates ROSTER.md; /audit byte-checks them.

The skills

Skill	What it does
/start	Set up a new project: charter from you, state tree, first tasks. Only on request.
/infer-start	Same, for an existing codebase, with the charter inferred from the repo. Only on request.
/pickup	Resume from disk with zero prior context. The counterpart of /checkpoint.
/checkpoint	Save what a cold session would need. Run before ending, before anything risky.
/standup	Human-readable status. Read-only.
/spec	Hand the director a mid-project goal and get it decomposed into tasks.
/implement	Run a task end to end, then verify it automatically. Give it several independent tasks to run them concurrently.
/verify	Context-free QA check against acceptance criteria. Runs inside /implement, or standalone.
/redteam	Adversarial pass: hostile inputs, error paths, security. Files a doc per finding.
/debate	Completeness vs simplicity on a contested question, director rules.
/research	Answer a question with evidence, recorded as a research doc.
/document	Close the gaps between your project's human-facing docs and reality.
/handson	Walk you through testing a milestone build, capture what you hit.
/feedback	Capture your feedback and route it into tasks, research, or debate.
/hire	Forge a project-local specialist agent, with an ADR justifying it.
/audit	Integrity check on the state tree. Fixes mechanical drift, files real problems.
/cleanup	Archive finished docs to keep the tree lean. Moves, never deletes. Only on request.
/team-doctor	Checks this plugin itself for internal drift. Report-only unless you confirm fixes.

Hooks

Three, all quiet by default and all no-ops in a project that is not a dev-team project:

• SessionStart injects the manifest, so a new session knows the project exists before you say anything.
• PreCompact tells the compaction summary which facts must survive: active task IDs, in-flight paths, next actions.
• PostToolUse (on Write and Edit) checks state documents as they are written and makes the agent fix a malformed one in the same turn.

Handlers ship in behavior-identical bash and PowerShell sets. See hooks-handlers/README.md for which one runs and how to switch.

Development

Working on the plugin itself starts with a clone:

git clone https://github.com/<github-user>/dev-team-claude
cd dev-team-claude

The dev loop is claude --plugin-dir <clone-path> run from a scratch project somewhere else, never from inside the clone, so a test session's state cannot end up committed. After editing, run /team-doctor (or bash scripts/drift-check.sh) to catch drift, and claude plugin validate . before committing. Hook handlers come in behavior-identical twin pairs, so a change to one has to land in both.