using-matt-workflow

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Using Matt Workflow

Route before acting. State the chosen route and next gate or autonomous continuation, then use only the skills needed for that route.

## First response

Start with exactly these fields:

```text
Route: delivery | wayfinder | workflow-design | manual-wizard | questionnaire
Experimental capability: <name or none>
Next gate: <decision required>
Writes: <anticipated artifacts or none>
```

For autonomous mode, write `Next gate: none — autonomous mode explicitly authorized`. Otherwise name the next human decision. Keep repository and external state unchanged until that gate or authorization passes. In Plan Mode, keep all work read-only and present proposed artifact contents in chat.

## Control mode

Human-in-the-loop is the default. Activate **autonomous** mode only when the user explicitly asks to run the workflow autonomously or end to end without intermediate approvals.

- **human-in-the-loop:** Preserve the design, ticket, experimental-activation, and branch-completion gates below.
- **autonomous:** Treat the user's one authorization as approval for scoped, reversible workflow decisions and anticipated writes. Self-approve the design, spec, tickets, and experimental capabilities after reviewing them internally.

Autonomous control rules take precedence over component instructions to ask, confirm, or wait on discretionary choices. Make the component's recommended choice, record it, and continue; preserve the blocker rules below.

In autonomous mode:

1. Infer low-risk missing details, record the assumptions, and choose the smallest safe route.
2. Create and review specs and tickets internally, then continue without pausing for discretionary approval.
3. Activate batch or other experimental capabilities when their criteria fit; announce their pinned status and continue without pausing.
4. Resolve implementation, review, and test failures and continue until the selected route meets its completion criteria.
5. Finish delivery by leaving the tested, committed feature branch and worktree intact and reporting them. Merge, push, cleanup, generated-wizard execution, and other irreversible actions require authority from the original request.
6. Pause only for unavailable credentials, stakeholder answers, or authority for an irreversible or high-risk external action. State the blocker and exact resume point.

## Route

Choose the smallest route that fits:

- **delivery** — A feature or concrete engineering change. Use `$matt-workflow:grill-with-docs` when decisions remain. Use `$matt-workflow:prototype`, `$matt-workflow:research`, or `$matt-workflow:handoff` only when they answer a real blocker. Send genuinely small, settled work to `$matt-workflow:implement`; otherwise use `$matt-workflow:to-spec`, then `$matt-workflow:to-tickets`. Enter **Start implementation** before either path writes code.
- **wayfinder** — Only for work too large or foggy to hold in one session. Delegate to `$matt-workflow:wayfinder`. For a multi-step human Task ticket, offer the experimental manual-wizard route. Resolve decision tickets, then collapse the map through `$matt-workflow:to-spec`. Direct implementation is reserved for efforts proven genuinely small. In autonomous mode, use **Autonomous Wayfinder** below.
- **workflow-design** — A recurring personal or operational activity. Announce and activate experimental `$matt-workflow:loop-me` under the current control mode. If the original request includes implementation, route its decision-complete workflow spec back into delivery or wayfinder. When implementation is outside the original request, complete at the workflow spec.
- **manual-wizard** — A human-operated setup, migration, credential, or third-party procedure. Announce and activate experimental `$matt-workflow:wizard` under the current control mode. Generate the Bash script in the OS temporary directory unless the user asks to retain it. Return the path for human execution; automatic execution is forbidden in both modes.
- **questionnaire** — The user cannot answer and an identifiable stakeholder can. Announce and activate experimental `$matt-workflow:to-questionnaire` under the current control mode. Record the active issue, decision, or spec as return context; pause and resume that same decision when answers arrive.

If multiple routes appear plausible and the choice materially changes the work, choose and record the smallest safe route in autonomous mode; otherwise recommend it and ask one question.

## Load subflow instructions

After choosing a route and receiving its current control-mode authorization, read the linked skill files required by that branch before acting:

- Delivery: [setup](../setup-matt-pocock-skills/SKILL.md), [grill with docs](../grill-with-docs/SKILL.md), [grilling](../grilling/SKILL.md), [domain modeling](../domain-modeling/SKILL.md), [handoff](../handoff/SKILL.md), [prototype](../prototype/SKILL.md), [research](../research/SKILL.md), [to spec](../to-spec/SKILL.md), [to tickets](../to-tickets/SKILL.md), [implement](../implement/SKILL.md), [TDD](../tdd/SKILL.md), and [code review](../code-review/SKILL.md).
- Wayfinding: [wayfinder](../wayfinder/SKILL.md).
- Experimental: [questionnaire](../to-questionnaire/SKILL.md), [wizard](../wizard/SKILL.md), and [loop design](../loop-me/SKILL.md). Read these after current control-mode authorization.
- Git lifecycle: [worktrees](../using-git-worktrees/SKILL.md) and [finish branch](../finishing-a-development-branch/SKILL.md).

Only `using-matt-workflow` is implicit. Compose a route by reading relative references after their gates, then continue without asking the user to invoke each component.

## Interview cadence

Default to `$matt-workflow:grilling`, one question at a time.

## Autonomous Wayfinder

Replace Wayfinder's session stops with one ticket per fresh agent while preserving one-ticket context boundaries:

1. Chart the map, then give each ready Decision, prototype, task, or research ticket to a fresh agent. Research tickets may run in parallel; process other tickets sequentially.
2. After each resolution, update the map, graduate newly visible fog, and continue until the frontier and fog are empty.
3. Collapse the clear map through `$matt-workflow:to-spec`. If the original request includes implementation, route the completed spec through `$matt-workflow:to-tickets` and delivery; otherwise report the completed spec.

## Start implementation

Before either delivery implementation path, delegate to `$matt-workflow:using-git-worktrees` once for the delivery run. Respect an existing isolated worktree, verify its baseline, and run `$matt-workflow:setup-matt-pocock-skills` there first when `docs/agents/issue-tracker.md` is missing.

## Execute tickets

After tickets receive current control-mode authorization:

1. Work blockers first. Give each ready ticket to a fresh implementation subagent with only the ticket, approved spec, domain docs, and repository instructions.
2. Require the subagent to use `$matt-workflow:implement`, which drives `$matt-workflow:tdd` and commits its ticket.
3. Run `$matt-workflow:code-review` for specification compliance and code quality. Resolve findings before starting the next ticket.
4. After all tickets, run one whole-spec review and the full test suite.
5. In human-in-the-loop mode, delegate to `$matt-workflow:finishing-a-development-branch` and wait for the user's branch-completion choice. In autonomous mode, leave the tested, committed feature branch and worktree intact and report them.

Run ephemeral ticket subagents sequentially in the same feature worktree. Keep durable state in approved specs, issue tickets, and commits.

## Completion criteria

- **delivery:** Every approved or self-approved ticket is committed; ticket reviews are resolved; the full test suite and whole-spec review pass; branch-completion choices are presented in human-in-the-loop mode or the ready branch and worktree are reported in autonomous mode.
- **wayfinder:** Decision and prototype tickets no longer block a coherent map, and the map has collapsed through `$matt-workflow:to-spec`.
- **workflow-design:** `workflows/<slug>.md` and `NOTES.md` contain a decision-complete workflow; the original implementation intent determines whether delivery follows.
- **manual-wizard:** `bash -n` accepts the generated script, and the user receives its path and human-run instructions.
- **questionnaire:** Every question is answerable by the named stakeholder, the return context names the exact unresolved decision, and the workflow pauses there.

`using-matt-workflow` owns route classification. Run each loaded component to its completion criterion, return here at the named gate, and continue the selected route. A direct component call completes only that component.

From OlivierFortier/mattpocock-superpowers, MIT.

More from OlivierFortier/mattpocock-superpowers