Michael Boutin

Open source · imick-io/skills

How the skills, labels and agent loop fit together

A big idea becomes an initiative of epics. Each epic is briefed, planned into decisions, cut into tickets, built by agents in sandboxes, verified in the running app and merged. Labels on GitHub issues say what each issue is and who acts next. Skills are the commands that move issues along.

You decide

Scope, the brief, specs and the final merge. Fast and supersonic modes hand some of that to agents.

Agents do the legwork

Planning on autopilot, building, debugging, reviewing and verifying, in Docker sandboxes.

Workflows keep it tidy

Triage on every new issue, the epic merge gate, and closing what's done.

Use it

  1. 1.Install the skills into your project

    npx skills@latest add imick-io/skills
  2. 2.Set the project up

    /setup-imick-skills
  3. 3.Start from an idea

    /scope-decomposer "<your idea>"

Overview

The flow, by who acts

Follow the arrows from the top. Each column is who acts: you in a Claude session, the agent loop running unattended, or a GitHub workflow. Dashed arrows are feedback.
Youin a Claude sessionAgent loopunattended, npm run agentsGitHubworkflows on the repoYour ideaa product or a big featureIssue filedby you or a teammateAuto-triagelabels what it is + who acts, in Actions or the loopbug · enhancement/scope-decomposeran initiative of epicsepic/briefyour intent; pick the modeneeds-briefing/wayfinderdecisions, with youPlans the epicwayfinder + research → a specautopilot/to-spec → /to-ticketstickets with their blockersApprove the specor comment what to changespec-approvedBuilds ready ticketsimplement · debug · reviewready-for-agentAnswer what's stuckcomment, relabel for agentsready-for-humanEpic PR + verify-epictested in the running appepic-gate turns greenclosed · no mocks · verifiedReview & mergethe epic PR to mainClosing chainepic → milestone → initiativetoo big: needs-scopingbug or small enhancementmanualautopilotspectickets cutcan't finishansweredmilestone emptyfailures → bugs

Agent loop mode

The fast track

The same flow with fast mode on (AGENTS_MODE=fast, or the fast label on an epic). The loop takes the steps that waited on you: it approves its own spec, answers what's stuck, resolves conflicts and merges the verified epic. You come in only through the dashed arrows, when it asks.
Youonly when askedAgent loopAGENTS_MODE=fast, or a fast epicGitHubworkflows on the repoYour ideaa product or a big featureIssue filedby you or a teammateAuto-triagelabels what + who/scope-decomposerlocal-first v1, Go live lastepic/briefpick autopilot + fastfastResolves conflictsmain ↔ epic branch, any timePlans the epicwayfinder + research → a specautopilotYour callonly on decisions < 70%agent:askedApproves its specevery decision ≥ 70%spec-approvedBuilds ready ticketsimplement · debug · reviewready-for-agentAnswer one questionSlack ping → commentagent:askedAnswers what's stuck≥ 70%, or a local stand-inready-for-humanEpic PR + verify-epictested in the running appepic-gate greenclosed · verifiedMerges the epicinto main, by itselfClosing chainepic → milestone → initiativetoo bigbug or small enhancementautopilot + fastbelow 70%your commenttickets cutcan't finishansweredmilestone emptyfailures

Below AGENTS_THRESHOLD (70 by default), it asks you instead of deciding. It always asks before spending money, handling real credentials or personal data, deleting or publishing anything.

Agent loop mode

Supersonic

Fast mode without the waiting, for throwaway MVPs (AGENTS_MODE=supersonic, or the supersonic label). /scope-decomposer writes every epic's brief in its one interview. Below the threshold, a call that can be undone is assumed instead of asked, and the spec is always approved. The assumptions reach you in one Slack digest a day; comment on an issue to change a call.
Youone interview, then a digestAgent loopAGENTS_MODE=supersonicGitHubworkflows on the repoYour ideaa throwaway MVPIssue filedby you or a teammateAuto-triagelabels what + who/scope-decomposerone interview: epics + briefsautopilotPlans the epicwayfinder + research → a specResolves conflictsmain ↔ epic branch, any timeApproves its specalways; low calls assumedspec-approvedBuilds ready ticketsimplement · debug · reviewready-for-agentBlocking questionmoney · secrets · data · deletesagent:askedAssumes or answersbest guess if it can be undoneagent:assumedEpic PR + verify-epictested in the running appepic-gate greenclosed · verifiedDaily digestcomment to change a callagent:assumedFollows upedits it, or a follow-up ticketMerges the epicinto main, by itselfClosing chainepic → milestone → initiativetoo bigbug or small enhancementbriefed epicstickets cutcan't finishback to buildmilestone emptyfailuresassumed calls

It still stops and waits for money, credentials, personal data, deleting or publishing: those can't be undone. A wrong guess elsewhere costs rework, since your comment becomes a follow-up ticket. Fine for an MVP; not for production work.

Agent loop mode

A ticket, by hand

The agent loop's steps for one ticket, run yourself in Claude Code. /claim does the top part: it assigns you, picks the branch by whether the ticket sits under an epic, and switches you to it. Both paths share the build, then split again to land. Dashed arrows are the way back.
Youin Claude Code, in the repoGitHubthe issue and the repoTicket readyopen, unassigned, unblockedready-for-agent/claimassigns you: the loop skips itUnder an epic?its Branch: line names epic/NN-slugUpdate the epic branchmerge origin/main in, pushBranch off mainfeat/N, or fix/N for a bugBranch off the epicagent/issue-NStart the serviceswhat sandbox-setup.sh starts/implement #N/debug-and-fix for a bug/code-reviewsince the base branch, against #NChecks greentypecheck, tests, the prompt's extrasMerge into the epiconto origin/epic, then pushOpen the PRbody: Fixes #Nready-for-reviewTicket closedlanded on the epic, or PR mergedyesnoepicno epicclose ityou merge the PRconflict: merge the epic instop halfway: unassign
the main pathfeedback, and questions to you

Step by step

The stages

  1. 1

    Intake

    Workflow

    Anyone files an issue. Automatic triage labels what it is and who acts next, and comments its reasoning: a small enhancement goes to agents with a brief, a bug to debugging, anything big to scoping, anything unclear back to the reporter.

    /triageneeds-triageneeds-info
  2. 2

    Scope

    You + agent

    A big idea, yours or a needs-scoping issue, becomes an initiative with epics. Each epic has one destination, one owner area, its own milestone (NN: Initiative / Epic) and branch (epic/NN-slug), and blocking links to the epics it waits on. New products default to a local-first v1. Every epic carries the initiative's version (version:v1, v1.1, v2…), which the tracker's roadmap shows one at a time.

    /scope-decomposerinitiativeepicversion:*
  3. 3

    Brief

    You + agent

    A short, high-level interview per epic captures your must-haves, no-gos and calls already made, saved in the epic's Brief. It ends with your choice: manual or autopilot (and fast, if you want it).

    /briefneeds-briefingautopilot
  4. 4

    Plan

    You, or the loop

    Wayfinder charts the decisions an epic needs as tickets and resolves them: with you, one at a time, or alone on autopilot, ending in a spec for your approval. /product-design builds the real UI on mock data until you agree.

    /wayfinder/dig/product-designwayfinder:map
  5. 5

    Tickets

    Agent

    The spec is cut into tracer-bullet tickets, each in the epic's milestone with its blockers, labelled for agents.

    /to-spec/to-ticketsspecready-for-agent
  6. 6

    Build & fix

    Agent loop

    The loop picks every ready, unblocked ticket, plans which can run in parallel, and works each in a Docker sandbox: tests first, then a code review. Epic tickets land on the epic branch and close; others arrive as PRs. A ticket it can't finish goes to a person.

    ready-for-agentready-for-agent-debuggingready-for-human
  7. 7

    Verify

    Agent loop

    When a milestone has no open tickets, the loop opens the epic's PR and runs verify-epic in the running app: acceptance criteria, stories, API contracts, agreed screens. Failures become bug tickets, the loop fixes them, and verification runs again. A slow suite in test-suites/ that the epic's diff touches gets a Run ticket, run last on the epic branch, before the PR opens or, for a suite added later, before it merges.

    ready-for-agent-debuggingsuite-run
  8. 8

    Ship

    You (or fast mode)

    epic-gate turns green when nothing is open, no mocks/ folder is left and verification passed. You merge (fast mode merges for you). The epic closes, then its milestone, then the initiative when it was the last epic.

    ready-for-review

Reference

Labels

A triaged issue carries one what label (what it is) and one who label (who acts next). Planning labels mark the issues the planning skills create; loop labels are state the agent loop sets while it works. An assignee means claimed: someone, or some agent, is on it now.
LabelKindMeansSet byWhat happens next
needs-triageTransientTriage hasn't finishedNew issueTriage runs, or /triage #n
bugWhatSomething is brokenTriageGoes with a who label
enhancementWhatA small improvement, one brief's worthTriageGoes with a who label
needs-scopingWhatToo big for one briefTriage/scope-decomposer turns it into an initiative
needs-infoWhatWaiting on the reporterTriageThe reporter replies; triage re-runs
wontfixWhatBuilt already, duplicate or rejectedTriageA person closes it
splitWhatBundled several asks, like a pasted client emailTriageEach ask is its own issue; a person closes this one
suite-runWhatRun a slow suite from test-suites/ on a finished branch; green closes it, red files bugs it waits on/to-tickets, or the loop before an epic's PRThe loop runs it last in the epic (or against main), and the epic's PR waits for it
ready-for-agentWhoAn agent builds itTriage, /to-tickets, fast modeThe loop runs implement
ready-for-agent-debuggingWhoAn agent reproduces and fixes the bugTriage, verify-epic, fast modeThe loop runs debug-and-fix
ready-for-humanWhoA person acts nextAny skill or the loopThe assignee acts; in fast mode the loop tries first
ready-for-reviewWhoA fix PR waits for reviewThe loopReview the linked PR
initiativePlanningA big idea, the parent of epics/scope-decomposerCloses when its last epic ships
epicPlanningOne bounded scope: one map, one PR/scope-decomposer/brief, then planning
needs-briefingPlanningAn epic waiting for its brief/scope-decomposer/brief
autopilotPlanningAn epic the loop plans by itself/briefThe loop runs wayfinder on autopilot
wayfinder:mapPlanningAn epic's map of decisions (also wayfinder:* tickets)/wayfinderResolve its decision tickets
specPlanningA spec, never built directly/to-spec, autopilotApprove it, then /to-tickets
spec-approvedPlanningYou (or fast mode) approved an autopilot specYou, or fast modeThe loop cuts its tickets
area:*OwnershipWhich part of the product, so who owns it/scope-decomposer, triageSee docs/agents/team.md
version:*PlanningThe version an epic ships in (version:v1, version:v1.1, version:v2); the tracker's roadmap shows one version at a time/scope-decomposer, or youMove the label when an epic slips; an epic without one is flagged on the roadmap
agent:planningLoopThe loop is planning this epic right nowThe loopRemoved when the run ends
fastLoopFast mode for this one epicYouThe loop unblocks it by itself
agent:unblockingLoopFast mode is working on this issue nowThe loopRemoved when the run ends
agent:askedLoopFast mode asked you a question hereThe loopComment your answer on the issue
supersonicLoopSupersonic mode for this one epicYou, or /scope-decomposerThe loop assumes what can be undone
agent:assumedLoopSupersonic assumed a call hereThe loopComment to change it; a follow-up fixes what's built
backlogParkedParked for later: no triage, no agent, no planningYou, or /triageRemove it and set a who label to bring it back

Label journeys

The same labels, in the order an issue meets them. The tags on the arrows name what moves it.

A bug someone files

needs-triage→ auto-triage →bug→ready-for-agent-debugging→ debug-and-fix →ready-for-review→ you merge →closed

If the diagnosis needs a person, debug-and-fix hands it to ready-for-human instead. Under an epic, the fix lands on the epic branch and the issue closes.

A small enhancement

needs-triage→ auto-triage →enhancement→ready-for-agent→ implement →ready-for-review→ you merge →closed

A ticket you build yourself

ready-for-agent→ claim →→ implement →→ code-review →→ you land it →closed

/claim assigns you (the loop then leaves it alone) and sets up the branch. Under an epic you merge into the epic branch; otherwise you open the PR with Fixes #n. Step by step: docs/build-a-ticket-yourself.md.

A big idea, on autopilot

needs-scoping→ /scope-decomposer →epic→needs-briefing→ /brief →autopilot→ loop plans →spec→ you approve →spec-approved→ /to-tickets →ready-for-agent→ verify-epic →→ you merge →closed

Fast mode, when the loop is stuck

ready-for-human→ loop answers →ready-for-agent
ready-for-human→ not confident →agent:asked→ you comment →ready-for-agent

Parking something

ready-for-agent→ you park it →backlog→ you un-park →ready-for-agent

Parking drops the who label, so a backlog issue is in nobody's inbox and no agent touches it.

How much waits on you

Manual, autopilot, fast, supersonic

Set the mode in .sandcastle/.env: AGENTS_MODE=fast or AGENTS_MODE=supersonic for a whole project, or label one epic fast or supersonic. AGENTS_THRESHOLD (70 by default) is the confidence below which the loop asks (fast) or assumes (supersonic).
MomentManualAutopilotFastSupersonic
The briefYou, with an agentYou, with an agentYou, with an agentWritten by /scope-decomposer in its one interview
Each planning decisionYou, one at a time in /wayfinderAgent decides, digs when unsure, marks guesses assumedSame as autopilotSame as autopilot
The specYou write it with /to-specYou approve it (spec-approved)Approved if every decision is at or above the threshold; you're asked only about the ones belowAlways approved; the low ones stand as assumed
An account, secret or access only you haveYouParked as ready-for-human (a local stand-in first on a local-first v1)Local stand-in if one serves; otherwise asked in SlackLocal stand-in if one serves; otherwise asked and waited for
A ticket the agent can't finishYouYouAnswered when confident enough, sent back to the agents; otherwise askedAnswered, or assumed when it can be undone; asked only otherwise
main conflicts with the epic branchYou (a manual epic is yours)An agent resolves the merge on the epic branch; asks you if it can'tSame as autopilotSame as autopilot
Merging the verified epic PRYouYouMerged once verify-epic passesMerged once verify-epic passes
How you hear from itYou run it yourselfA ping when a spec is readyA Slack ping per questionOne digest a day; pings only for what blocks

Highlighted cells wait on you; the rest are done for you.

The loop always asks

Fast and supersonic modes always stop for you before spending money, handling real credentials or personal data, deleting or publishing anything, or contradicting the brief. They never touch anything labelled backlog.

Local-first v1

For a new product, /scope-decomposer recommends building the whole first version on your machine (SQLite or Docker Postgres, local storage, a dev login, console email, test-mode payments). Cloud accounts, domains, secrets and deploys wait in one Go live epic, last and blocking nothing, so the loop never stalls on setup only you can do.

Catalog

Skills

You type it skills run only when you call them with /name. Claude picks it skills also load on their own when the task fits. Select a skill to see what it uses.

Planning

From an issue or idea to tickets agents can build.

Building & fixing

Turning tickets into tested, reviewed code, and checking the result.

Design & code quality

Shared vocabulary and reviews for the code's shape.

Thinking tools

Interviews and research the other skills lean on, also useful alone.

Setup & upkeep

Project setup, the tracker page, repo hygiene.

In progress

Not finished; not installed in projects yet.

What calls what

Dependencies

A skill uses another when it loads it mid-run. It hands off to the one that normally comes next. A project needs every skill its skills use, committed in .claude/skills/: agents in the loop's sandboxes only see the repo.

Planning

Building & fixing

Design & code quality

Thinking tools

Setup & upkeep

In progress

wayfinder

SKILL.md
you type itagent loop

Plans an epic as a map of decision tickets and resolves them until the way is clear. On autopilot the loop decides alone and writes a spec for approval.

From Matt Pocock

Uses

Used by

No other skill loads it

Comes before / after

To install wayfinder, also install grilling, domain-modeling, research, prototype, dig, to-spec.

Where things live

Branches and settings

BranchHoldsMerges into
epic/NN-slugEverything for one epicmain, through the epic PR
agent/issue-nOne agent's ticket, brieflyThe epic branch
feat/n, fix/nA ticket outside any epicmain, through its PR
design/NN-slugAgreed screenshots from /product-designNever
FileSays
docs/agents/issue-tracker.mdWhere issues live
docs/agents/triage-labels.mdThe label strings
docs/agents/team.mdAreas, owners, people
docs/agents/domain.mdWhere the glossary and ADRs live
docs/agents/preview.mdWhere verify-epic finds the running app
.github/workflows/Triage; the epic gate and closing chain
.sandcastle/The agent loop; secrets and the mode in .env

All of these are written by /setup-imick-skills, run once per project, and stay editable by hand.

This page is drawn from docs/handbook.json in imick-io/skills, regenerated with the skills and refreshed here daily.