The New SDLC, Run by Agents: the MetaSkills workflow

1The agents

Four agents do the work

Every step of the workflow is carried out by one of four agents, dispatched from your own session. Meet the agents first: the skills that follow are the playbooks they load, and each agent's limits decide who may do what.

Fig. 1The relay. Each arrow is what one agent hands the next. The architect plans the work, diagnosing a bug's root cause first when the bug calls for it, and later reviews the developer's pull request; findings go back to the developer for at most two rounds of fixes, and the architect merges once the review is clean. The last line in each box lists the skills that agent runs. Your session dispatches every agent in a fresh context and never does their work itself.

Plans and judges

architect

The judgment agent. In dev-cycle phase 1 it designs the How and claims the issue; when a bug calls for it, it first finds the Why in one root-cause comment. In phase 3 the same architect, dispatched in a fresh context with none of the build's history, reviews the pull request and merges it.

Runs: issue-plan, issue-diagnose, code-review
Writes: The claim, the plan ledger, the RCA comment, the review comment, and the squash merge. Locally, only .tmp-* staging files and the diagnosis or review worktree, all removed afterward.
Never: Writes production code, designs a fix inside the RCA, or reviews a change it implemented or substantially edited.
Returns: The ledger link, approach, task count, and blockers; the RCA link and conclusion; or the review URL, assessment, and merge result.

Builds

developer

The implementation agent, dev-cycle phase 2. It turns the architect's plan ledger into one pull request, then fixes the reviewer's enumerated findings in at most two revision rounds.

Runs: issue-implement
Writes: A branch and commits in its own .worktrees/ checkout, the pull request, ledger check-offs, and the move to In review.
Never: Creates a plan ledger, claims an issue, or guesses. Ambiguity and design trade-offs go under the ledger's Blockers, and it stops.
Returns: The PR URL, changed paths, validation results, ledger state, and residual risks.

Defines and reports

project-manager

Owns the What. It files issues, refines them until they say what done means, and reports on the work. As a subagent it cannot hold a question gate, so it returns its questions for the caller to ask.

Runs: issue-raise, issue-refine, backlog-refine, weekly-review, project-status
Writes: New issues, and body, label, or status changes once approved. Locally, only Docs/ and .tmp-* bodies; its shell is read-only.
Never: Writes production code, or changes an issue body, labels, or board status without approval.
Returns: The issue URL, or a proposal with open questions; for reports, the file path.

Tests

quality-assurance

Tests a running app, staging by default, through Playwright MCP browser tools, and files only the bugs it can reproduce. burndown dispatches a fresh one to sweep a batch's merged work.

Runs: qa
Writes: One bug issue per root cause, filed through issue-raise. Edits and shell are unrestricted for testing.
Never: Drives the browser with scripts, npx playwright, or browser_run_code_unsafe; builds features; or captures secrets or personal data.
Returns: Workflows tested, issues filed, unfiled bugs with reasons, non-reproducible observations, and limits.

Not an agent

You, the coordinator

The orchestrators dev-cycle and burndown are not agents. They run in your own session (burndown runs dev-cycle once per issue), dispatch each agent with only the issue reference and the facts it needs, check what comes back, and dispatch the next. They never write code, post plans, move the board, or merge.

Without subagents, run each phase in a fresh session that loads only that phase's skill, and never review in the session that implemented. Two skills belong to no agent: any session can run setup and paper-doc.

How each harness enforces the agents' permissions

Each agent's instructions are identical in its Claude Code, opencode, and Codex definition, and lint checks that they match. The permission envelopes differ, because each harness expresses permissions its own way.

Agent	opencode	Claude Code	Codex
architect	Edits denied except `.tmp-*`	Read, Grep, Glob, Bash, Write, Edit, Skill	`workspace-write`
developer	Edit and bash allowed	No tool list, so every tool	`workspace-write`
project-manager	Edits only `Docs/*` and `.tmp-`; bash asks, except `gh`, `git log/status/diff`, `rg`, `grep`	Same tools as architect	`workspace-write`
quality-assurance	Edit and bash allowed	Architect's tools plus `mcp__playwright__*`	`danger-full-access`, approval `never`

Matching instructions do not prove matching capability: check the effective permissions in each harness before relying on an agent's limits. No agent definition pins a model; choose models per harness.

2The lifecycle

Five statuses, one owner per move

The board Status field is both the progress tracker and the lock. Each forward move belongs to one agent, made through exactly one skill; the coordinator never moves it.

Fig. 2Status transitions, the agent that makes each one, and the skill it uses. The names follow the README; each project maps them to its own Status options in AGENTS.md § Project Board.

The What, the Why, and the How

The issue body is the durable spec and never holds a design or a task list; a bug's body never holds a fix. The design lives in exactly one comment whose first line is . Only issue-plan creates it; everyone else edits it in place by its numeric REST id.

<!-- plan-ledger -->
## Plan
## Approach
## Touch Points
## Validation
## Risks
## Tasks
- [ ] Task: unit, code area, validation signal
## Sequence
## Blockers
_None._

Approach, Tasks, and Blockers are required. issue-implement starts only when Blockers reads _None._ and checks a task off only once it is implemented, validated, and in the branch.

A bug that meets issue-diagnose's criteria gets its Why first, in one comment whose first line is : the observed failure, an evidence-marked why chain, the component that should already handle it, and a reproduction. It moves no status and designs no fix; it reaches the developer only through the body and the ledger.

The board moves in the figure are the only status writes in the whole workflow. dev-cycle, burndown, and backlog-refine dispatch the skills that make them, then verify the result.

Status	Entered through	Run by	What is written
Backlog	`issue-raise`	project-manager or the user	The issue, from the repository template or Summary, Context, Expected outcome, Notes. One Type when Types are enabled, existing labels only, an assignee, the board item.
Ready	`issue-refine`	project-manager	The rewritten body, after the user approves it. No comments. A split keeps the parent and adds native sub-issues.
In progress	`issue-plan`	architect	The claim, then the single plan-ledger comment: approach, touch points, validation, risks, tasks, sequence, blockers.
In review	`issue-implement`	developer	A branch `issue-<n>-<slug>` from a `.worktrees/` checkout, the PR, and ledger check-offs.
Done	`code-review`	architect, in a fresh context	The review comment and the squash merge. Done is set only for issues the PR actually closed, and only when GitHub automation is off.

Boardless projects

`board: none` is a declaration, not a default

A project that declares board: none in § Project Board skips every board read, claim, and move, and each skill reports that it did. Missing or incomplete board facts are different: they stop the skill, and are never reinterpreted as board: none.

Without a board, ownership still comes from the ledger and its tie-break, an existing ledger still needs an explicit resume, and the batch skills need an explicit list, label, or milestone because there is no Ready column to read.

3The skills

Fourteen skills in five groups

The skills are the agents' playbooks. Two define the work, one diagnoses bugs, and three deliver it; three orchestrators sequence them for one issue or a batch; five more verify, report, or support.

Fig. 3Who hands work to whom. The middle row is the lifecycle from Fig. 2. Solid arrows hand work on; dashed arrows dispatch, and the numbers on dev-cycle's arrows are its phases. The last line in each box names the agent or session that runs the skill. issue-diagnose runs only for a bug that needs a root cause: issue-refine, issue-plan, or code-review can call for it, dev-cycle or backlog-refine dispatches it, and its RCA comment feeds the plan. Not drawn: dev-cycle and burndown also send unrefined or oversized issues back to issue-refine.

Define the What

Say what done means

issue-raise files a classified, assigned issue at the board's new-issue status. issue-refine settles scope and acceptance criteria in the body, then moves it to Ready. Neither designs anything; design questions become constraints for the plan, and a bug report carries no fix.

Find the Why, deliver the How

Diagnose, plan, build, review

For a bug that calls for it, issue-diagnose finds the root cause in one RCA comment without designing the fix. issue-plan claims the issue and writes its plan ledger, fixing that cause in the component that should already handle it. issue-implement turns that ledger into one fully resolving PR. The architect who planned it then runs code-review in a fresh context, reviews the PR, and squash-merges when every criterion holds.

Orchestrate

Sequence, never do

dev-cycle runs the three delivery phases for one issue, diagnosing a bug first when it needs it. burndown runs dev-cycle across dependency-ordered waves and closes with a QA sweep. backlog-refine fans issue-refine out across a backlog, diagnosing approved bugs before refining them. None of them writes code, moves the board, or merges.

Verify and report

Feed findings back in

qa tests a running app through Playwright MCP and files each reproduced bug through issue-raise, so regressions re-enter the lifecycle at Backlog. weekly-review and project-status are read-only on GitHub and write only under Docs/status/.

Support

Outside the lifecycle

setup provisions local, Docker Compose, or CI environments from the documented commands. paper-doc writes portable HTML documents such as this one. Deployment is deliberately absent: it differs in every project, so it lives in the consuming repository.

Where to start

You have	Start with	It hands off to
An idea, bug, or follow-up with no issue yet	`issue-raise`	Nothing; the issue waits in Backlog for refinement
An issue that is vague or bigger than one PR	`issue-refine`	issue-raise for native sub-issues when it splits
A backlog to groom	`backlog-refine`	issue-refine, one worker per item
One issue to ship	`dev-cycle`	issue-plan, issue-implement, code-review
A list, label, milestone, or board column to ship	`burndown`	dev-cycle per issue, then qa
A bug whose cause is unclear	`issue-diagnose`	issue-refine or issue-plan, which work from its RCA comment
An issue that needs only a design	`issue-plan`	dev-cycle later, resumed explicitly
A PR, a branch, or uncommitted changes	`code-review`	Nothing; it reports, and merges in PR mode
A running app to test	`qa`	issue-raise for each reproduced bug
An environment to set up or repair	`setup`	Nothing
A weekly status report	`weekly-review`	Nothing; it writes to `Docs/status/`
A "what is left" question	`project-status`	Suggested batches for backlog-refine or burndown

Every skill has a same-named wrapper in commands/ for opencode and Codex. Claude Code invokes the skill directly as /<name>.

4Ground rules

The rules every skill shares

These invariants let narrow skills compose without stepping on each other. Each is stated once, in the skill that owns it, and referenced everywhere else.

Rule	In practice	Owner
Facts come from `AGENTS.md`	Every skill names the sections it needs. A missing or insufficient section stops it; a project fact is never guessed. A `MetaSkills version` line says which template version the file satisfies: a newer minor version means the project must update its `AGENTS.md` or issue templates.	`AGENTS.template.md`
Why before How for bugs	A bug that meets the criteria gets one RCA comment before any plan, and the plan fixes its cause instead of adding machinery around the symptom. Bug reports never carry a fix.	`issue-diagnose`
Status is the lock	Only Ready can be claimed. An existing ledger or any later status means claimed. Resuming needs explicit user authorization; a batch dispatch is not authorization.	`issue-plan`
Implementer is not reviewer	A reviewer that authored or substantially edited the change stops and spawns a fresh one. The reviewer alone merges; callers only record the result.	`code-review`
Delivery fully resolves	The PR's final line is `Closes #n`, and exactly that issue's canonical URL is registered as the closing reference. Partial scope stops for repair or an approved split, never a partial `Refs`.	`issue-implement`
Loops are bounded	At most two fix and re-review rounds, then the PR is parked. A re-review classifies each prior finding and adds only fix-induced regressions or release-threatening Critical or High issues it could not have raised earlier. A refinement an RCA asks for runs once; a re-diagnosis spends the cycle's single plan repair and a revision round, and a repair that changes nothing parks the PR.	`dev-cycle`, `code-review`
One severity ladder	Critical, High, Medium, Low, everywhere. Critical or High blocks commits and merges.	`code-review`
Work is isolated	Implementation and review each run in their own `.worktrees/` checkout. Review is pinned to the captured head SHA; only clean worktrees inside `.worktrees/` are removed.	`issue-implement`, `code-review`
No hidden state	The board and issue comments are the only workflow state. Batch tracking lives in the conversation; multi-line bodies are staged in `.tmp-*` files and deleted.	Every skill
Findings compound	A recurring review finding or guardrail gap becomes a proposed amendment to `AGENTS.md` or the review checklist.	`code-review`, `burndown`

One owner per shared mechanic

Mechanic	Owner
Board transitions, complete board reads, ledger creation and tie-break	`issue-plan`
RCA criteria and the root-cause comment	`issue-diagnose`
Native sub-issue linking	`issue-raise`
Implementation worktree and PR delivery	`issue-implement`
Review worktree, squash merge, after-merge steps	`code-review`
The two-round revision bound	`dev-cycle`
Login order and capture rules for a running app	`qa`

Where the workflow stops on purpose

A required AGENTS.md section is missing

Any skill names the section and stops. Adding the section is the fix; the skill never infers it.

The issue is already claimed

issue-plan, dev-cycle, and burndown report claimed and leave it alone, even when the ledger looks abandoned. Only an explicit user resume continues it.

The plan needs a decision

issue-plan's approval gate triggers on materially different approaches with no clear winner, widened scope or a broken Notes constraint, a split, a data migration or backfill, a public contract change, a security or permission decision, a What that is still ambiguous, or a bug's RCA that needs evidence. It asks with a recommendation and stops before claiming.

A bug needs a diagnosis first

issue-refine or issue-plan reports needs diagnosis and stops before Ready or the claim. dev-cycle or backlog-refine runs issue-diagnose, then resumes. An RCA asking for refinement gets one round under the user's approval; a second request stops.

Implementation hits a design question

issue-implement records it under Blockers and stops. dev-cycle may send the ledger back to the architect once, for a same-cycle repair, re-diagnosing first if the blocker contradicts the RCA; a second blocker ends the cycle.

Review cannot converge or merge

After two revision rounds, or as soon as the developer contests a finding, dev-cycle parks the PR with both positions. A review that finds the plan treats a symptom triggers one re-diagnosis and repair; a second, or a repair that changes nothing, parks the PR. An unmet merge criterion short of Critical or High is reported and the PR stays open for the user.

The data is incomplete

A board read whose item count does not match totalCount, an issue URL with zero or several board matches, or a partial page set stops the operation. Samples are never reported as totals.

5One issue

dev-cycle, phase by phase

The coordinator writes no code, posts no plans, moves no status, and merges nothing. It dispatches each phase to a fresh context carrying only the issue reference and the facts that phase needs, then checks the result before the next dispatch.

Fig. 4One issue from load to report, including the diagnosis a bug may need, the approval gate, the single blocked-plan repair, and the bounded revision loop. Every phase runs in a fresh context; the review never runs where the code was written.

Phase	Agent	Skill	Skipped when	Returns
Diagnose, as needed	architect	`issue-diagnose`	No phase reports needs diagnosis	RCA link and REST id, conclusion, criteria, refinement or evidence needed
Refine, as needed	project-manager	`issue-refine`	The issue is Ready and no RCA asks for refinement	A proposal and questions, or the applied refinement and its status
1 · Plan	architect	`issue-plan`	The user explicitly asked to resume an already-planned issue	Ledger link, approach, task count, blockers or decisions
2 · Implement	developer	`issue-implement`	An explicit resume finds an existing delivery PR, which goes straight to review	PR URL, changed paths, ledger state, validation output, risks
3 · Review	architect, in a fresh context	`code-review`	Never	Assessment, comment URL, merge or blocker, board transition, cleanup
4 · Revise	developer, then the architect again	`issue-implement`, `code-review`	The review was clean	Commits, fixed and contested findings, validation output

What must hold before a merge

The assessment is Approve, with no Critical, High, or important pre-merge Medium finding.
Required checks pass on the reviewed head, and the PR is mergeable.
No validation result indicates production breakage.
Nobody asked for review only, and no auto-deploy needs manual timing.

The merge passes --match-head-commit with the reviewed SHA. If the head or base moved, the reviewer re-reviews a fresh pinned checkout instead of retrying with the new SHA.

Handoffs carry evidence, not context

Each dispatch prompt names the issue URL plus exactly what the next agent needs: claim or resume evidence and the ledger's REST id for the developer, the PR number and round for the reviewer, the review comment URL and enumerated findings for a revision, and the RCA's REST id and trigger for a re-diagnosis.

Without subagents, run one fresh session per phase, loading only that phase's skill. Never review in the session that implemented.

6Batches

Waves for delivery and grooming

burndown and backlog-refine both order their work into dependency waves. Neither restates or controls the skill it fans out to; each records results in the conversation and leaves state on the board.

Fig. 5burndown. Issues in one wave share no dependency edge and no write set, so their cycles may interleave.

Fig. 6backlog-refine. One question gate up front; approval covers only the items it cleared.

burndown

Two bounds on concurrency

Scope, in precedence: an explicit issue list, a label query, a milestone, a board status the user names, else the Ready column.
Concurrency has exactly two bounds: dependency edges, and write-set overlap in files, migrations, contracts, routes, state models, or fixtures. Doubt serializes.
Decision points are recorded as needs-decision and asked together at the end of the wave; parked PRs block only their dependents.
Claimed elsewhere drops the issue and its dependents. Two or more in one wave stops the batch for a question.
The QA sweep is discovery, not a gate. Merged PRs are never reverted; confirmed bugs become new Backlog issues that reference the originating PR.

The coordinator's only GitHub writes are triage comments. Under GraphQL secondary rate limits it staggers board reads and prefers gh api graphql or REST verification over blocking the wave, then re-verifies unconfirmed moves once the limit resets.

backlog-refine

One gate, then waves

Nothing fans out before the gate, and no item is refined with an unanswered question or invented scope.
Only issue-refine edits a body, splits an issue, or moves it to Ready. backlog-refine writes nothing but .tmp-* bodies.
Each item is tracked as needs-answers, needs-diagnosis, clarified, refined to Ready, skipped, or deferred, in the conversation.
Bugs that need a root cause are listed at the gate. With a go-ahead, one architect worker diagnoses each before it is refined.
Split parents are refined before their children, which land in later waves.
Obsolete or duplicate items are flagged for the user, never silently dropped.

Workers that cannot hold a question gate return their questions and the items already clear; the caller asks and re-dispatches with the answers.

7Ownership

How two agents avoid one issue

Claims are optimistic. The status is set first and re-read; then the plan ledger's numeric REST comment id settles any tie that the status could not.

Fig. 7A simultaneous claim. With board: none the board steps disappear and the ledger tie-break alone decides.

Reading the board

Before any status edit, read the board's totalCount, fetch exactly that many items, and require the counts to match. Match the issue by its canonical URL, never its number. Zero matches asks; several matches stop as ambiguous.

Resume and repair

A ledger is never silently resumed, however stale it looks. The one coordinator exception is a same-cycle blocked-plan repair: dev-cycle passes the ledger's REST id, its ownership evidence, and the blockers, and the architect edits that ledger under the same approval gate. A review finding that the plan treats a symptom can trigger the same single repair, after a re-diagnosis.

8Reference

Every skill at a glance

What each skill is for, which agent runs it, what it writes, and which AGENTS.md sections it reads before acting.

Skill	Run by	Use it to	Writes
`issue-raise`	project-manager	File a classified, assigned issue or a native sub-issue	The issue with its Type, labels, and assignee; sub-issue links; the board item at the new-issue status
`issue-refine`	project-manager	Settle scope and acceptance criteria	The issue body after approval; Ready status. No comments
`backlog-refine`	project-manager	Refine a batch in waves after one question gate	Only `.tmp-*` bodies; issue-refine does the writing
`issue-diagnose`	architect	Find a bug's root cause before planning	The single RCA comment; nothing else
`issue-plan`	architect	Design the How and claim the issue	In progress status; the single plan ledger
`issue-implement`	developer	Turn a ledger into one PR, or run a revision round	Branch and commits in `.worktrees/`; the PR; ledger check-offs; In review status
`code-review`	architect, never the implementer	Review a PR for merge, or local changes for commit	The review comment, the squash merge, Done when automation is off. Local mode only reports
`dev-cycle`	coordinator: the user session or burndown	Ship one issue	Nothing itself
`burndown`	coordinator	Ship a batch, then sweep it with QA	Triage comments only
`qa`	quality-assurance	Test a running app through Playwright MCP	Bug issues, through issue-raise
`setup`	any session	Set up or repair local, Docker Compose, or CI environments	Local configuration; never secrets
`weekly-review`	project-manager	Report a week of GitHub and git activity	`Docs/status/YYYY-MM-DD-weekly-review.md`
`project-status`	project-manager	Group every not-done issue by how the items relate	Nothing, or `Docs/status/YYYY-MM-DD-project-status.md` on request
`paper-doc`	any session	Write a portable HTML document	The document

What each skill reads from `AGENTS.md`

required required in one mode only, noted below
Skill	Overview	Layout & Stack	Build & Validation	Project Board	Repositories	Environments	Branch Map	Agent Login	Review Notes
`issue-raise`				required	required
`issue-refine`		required		required	required				required
`backlog-refine`		required		required	required
`issue-diagnose`		required	required		required		required		required
`issue-plan`		required	required	required	required				required
`issue-implement`		required	required	required	required		required
`code-review`		required	required	PR mode only	PR mode only		PR mode only		required
`dev-cycle`			required	required	required		required
`burndown`		required	required	required	required	QA sweep only	required	QA sweep only
`qa`				required	required	required		required
`setup`		required	required					required
`weekly-review`	required			required	required
`project-status`	required	required		required	required
`paper-doc`	Reads whatever project facts the document needs, and asks when they are missing

code-review needs Project Board, Repositories, and Branch Map only in PR mode; local mode never touches the board. burndown needs Environments and Agent Login only for its QA sweep, which it skips with a note when there is no running app.

9Evidence

Sources and limits

The project lives at github.com/odytrice/metaskills. Every statement here was read from that repository at commit 22cc809, and the links below point at that commit.

skills/: the fourteen SKILL.md files, plus code-review/checklist.md and output-format.md.
agents/: the four agents in three dialects.
commands/: the same-named wrappers.
README.md: the workflow summary and core mechanics.
AGENTS.template.md: the sections and conventions every consuming project provides.
tests/workflow-scenarios.md: the manual scenarios that pin these behaviors.

Limits of this guide

It describes the instructions, not observed runs. tests/workflow-scenarios.md evaluates them by walkthrough; nothing here was executed against GitHub.
Status names follow the README. A consuming project's real Status options, board number, and done automation come from its own AGENTS.md.
This repository's own AGENTS.md documents no board, environments, or agent login, so board-dependent skills stop and ask when pointed at MetaSkills itself.
Figs. 1 and 3 were drawn in draw.io; the other diagrams were rendered with PlantUML 1.2024.3. Each figure's source is embedded beside it in this file, and the draw.io sources open directly in draw.io.

Google Fonts enhance the typography when online. The prose and diagrams are local to this file and work offline with fallback fonts.