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.Install the skills into your project
npx skills@latest add imick-io/skills2.Set the project up
/setup-imick-skills3.Start from an idea
/scope-decomposer "<your idea>"
Overview
The flow, by who acts
Agent loop mode
The fast track
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.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
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.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
Step by step
The stages
- 1
Intake
WorkflowAnyone 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
Scope
You + agentA 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
Brief
You + agentA 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
Plan
You, or the loopWayfinder 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
Tickets
AgentThe 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
Build & fix
Agent loopThe 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
Verify
Agent loopWhen 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
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
| Label | Kind | Means | Set by | What happens next |
|---|---|---|---|---|
| needs-triage | Transient | Triage hasn't finished | New issue | Triage runs, or /triage #n |
| bug | What | Something is broken | Triage | Goes with a who label |
| enhancement | What | A small improvement, one brief's worth | Triage | Goes with a who label |
| needs-scoping | What | Too big for one brief | Triage | /scope-decomposer turns it into an initiative |
| needs-info | What | Waiting on the reporter | Triage | The reporter replies; triage re-runs |
| wontfix | What | Built already, duplicate or rejected | Triage | A person closes it |
| split | What | Bundled several asks, like a pasted client email | Triage | Each ask is its own issue; a person closes this one |
| suite-run | What | Run 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 PR | The loop runs it last in the epic (or against main), and the epic's PR waits for it |
| ready-for-agent | Who | An agent builds it | Triage, /to-tickets, fast mode | The loop runs implement |
| ready-for-agent-debugging | Who | An agent reproduces and fixes the bug | Triage, verify-epic, fast mode | The loop runs debug-and-fix |
| ready-for-human | Who | A person acts next | Any skill or the loop | The assignee acts; in fast mode the loop tries first |
| ready-for-review | Who | A fix PR waits for review | The loop | Review the linked PR |
| initiative | Planning | A big idea, the parent of epics | /scope-decomposer | Closes when its last epic ships |
| epic | Planning | One bounded scope: one map, one PR | /scope-decomposer | /brief, then planning |
| needs-briefing | Planning | An epic waiting for its brief | /scope-decomposer | /brief |
| autopilot | Planning | An epic the loop plans by itself | /brief | The loop runs wayfinder on autopilot |
| wayfinder:map | Planning | An epic's map of decisions (also wayfinder:* tickets) | /wayfinder | Resolve its decision tickets |
| spec | Planning | A spec, never built directly | /to-spec, autopilot | Approve it, then /to-tickets |
| spec-approved | Planning | You (or fast mode) approved an autopilot spec | You, or fast mode | The loop cuts its tickets |
| area:* | Ownership | Which part of the product, so who owns it | /scope-decomposer, triage | See docs/agents/team.md |
| version:* | Planning | The 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 you | Move the label when an epic slips; an epic without one is flagged on the roadmap |
| agent:planning | Loop | The loop is planning this epic right now | The loop | Removed when the run ends |
| fast | Loop | Fast mode for this one epic | You | The loop unblocks it by itself |
| agent:unblocking | Loop | Fast mode is working on this issue now | The loop | Removed when the run ends |
| agent:asked | Loop | Fast mode asked you a question here | The loop | Comment your answer on the issue |
| supersonic | Loop | Supersonic mode for this one epic | You, or /scope-decomposer | The loop assumes what can be undone |
| agent:assumed | Loop | Supersonic assumed a call here | The loop | Comment to change it; a follow-up fixes what's built |
| backlog | Parked | Parked for later: no triage, no agent, no planning | You, or /triage | Remove 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
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
A ticket you build yourself
/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
Fast mode, when the loop is stuck
Parking something
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
.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).| Moment | Manual | Autopilot | Fast | Supersonic |
|---|---|---|---|---|
| The brief | You, with an agent | You, with an agent | You, with an agent | Written by /scope-decomposer in its one interview |
| Each planning decision | You, one at a time in /wayfinder | Agent decides, digs when unsure, marks guesses assumed | Same as autopilot | Same as autopilot |
| The spec | You write it with /to-spec | You approve it (spec-approved) | Approved if every decision is at or above the threshold; you're asked only about the ones below | Always approved; the low ones stand as assumed |
| An account, secret or access only you have | You | Parked as ready-for-human (a local stand-in first on a local-first v1) | Local stand-in if one serves; otherwise asked in Slack | Local stand-in if one serves; otherwise asked and waited for |
| A ticket the agent can't finish | You | You | Answered when confident enough, sent back to the agents; otherwise asked | Answered, or assumed when it can be undone; asked only otherwise |
| main conflicts with the epic branch | You (a manual epic is yours) | An agent resolves the merge on the epic branch; asks you if it can't | Same as autopilot | Same as autopilot |
| Merging the verified epic PR | You | You | Merged once verify-epic passes | Merged once verify-epic passes |
| How you hear from it | You run it yourself | A ping when a spec is ready | A Slack ping per question | One 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
/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.mdPlans 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
| Branch | Holds | Merges into |
|---|---|---|
| epic/NN-slug | Everything for one epic | main, through the epic PR |
| agent/issue-n | One agent's ticket, briefly | The epic branch |
| feat/n, fix/n | A ticket outside any epic | main, through its PR |
| design/NN-slug | Agreed screenshots from /product-design | Never |
| File | Says |
|---|---|
| docs/agents/issue-tracker.md | Where issues live |
| docs/agents/triage-labels.md | The label strings |
| docs/agents/team.md | Areas, owners, people |
| docs/agents/domain.md | Where the glossary and ADRs live |
| docs/agents/preview.md | Where 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.