automatt

name	automatt
description	Use when the user mentions AutoMatt, asks for Matt Pocock-style session governance, wants task-lifecycle routing, or needs context-risk and handoff discipline for one long task.

AutoMatt

Run the current task like a disciplined Matt Pocock-style agent session.

Core Rule

Manage one task from beginning to end in the current session. Keep operational progress in automatt-state.json at the repo root when the task is non-trivial, resumable, or near handoff. Ensure the file is ignored by git before creating it, and never stage or commit it.

Use markdown/docs for real artifacts (CONTEXT.md, ADRs, PRDs, issue descriptions, handoffs). Use JSON only for progress state and pointers to those artifacts.

Goal: preserve enough task state for a fresh session to continue safely. Track workflow phase, context risk, durable artifacts, next steps, and the exact continue/handoff prompt when a fresh context would improve quality.

Start

1. If automatt-state.json exists, read it and resume from its phase, status, and next_skill.
2. If the state conflicts with the current user request, summarize the mismatch and update or ask before continuing.
3. If it does not exist, infer the phase from the conversation and ask one focused question only if a decision is needed before creating it.
4. If a question can be answered by inspecting the repo, inspect the repo instead of asking.
5. Ask one question at a time at decision boundaries or when ambiguity blocks progress. For every question, include your recommended answer.
6. Update automatt-state.json after each meaningful phase change, before handoff, and whenever an important decision is resolved.

State Shape

Keep state compact and valid JSON. Do not store secrets or duplicate long artifacts.

{
  "phase": "discovery",
  "status": "active",
  "goal": "",
  "scope": "",
  "open_questions": [],
  "decisions": [],
  "completed_steps": [],
  "blocked_on": null,
  "artifacts": {
    "context": null,
    "adrs": [],
    "prd": null,
    "issues": null,
    "handoff": null
  },
  "next_steps": [],
  "next_skill": "scoping",
  "context_risk": "low",
  "safe_to_clear_context": false,
  "continue_prompt": null,
  "validation": {
    "last_checks": []
  },
  "last_updated": "YYYY-MM-DD"
}

Use these phases: discovery, scoping, grilling, prototype, prd, stories, implementation, review, debugging, handoff, complete.

Context Management

Treat context risk as an operating concern, not a precise token counter. Set context_risk to:

• low when the task is small, decisions are few, and artifacts are current.
• medium after long grilling, many file reads, several decisions, or before starting implementation from a rich plan.
• high when the session contains enough decisions, diffs, errors, or tool output that a fresh agent would struggle without a summary.

When risk becomes medium, update automatt-state.json and make sure key decisions exist in durable artifacts. When risk becomes high, create or refresh a handoff, set safe_to_clear_context and continue_prompt when artifacts are durable, and ask whether to continue here or move to a fresh session before starting a new large phase.

Preserve decisions before recommending a fresh session. If the runtime exposes token/context usage, use it; otherwise infer risk from conversation length, number of decisions, amount of code read, and how much state a fresh session would need.

After any self-contained phase such as scoping, grilling, research, PRD drafting, story slicing, or debugging, ask whether the current context is still useful. If all needed outputs are captured in files and the remaining work can start from those files, set safe_to_clear_context to true and write a continue_prompt that a fresh session can use.

Good continue prompts mention the state file, relevant artifacts, current phase, and next skill/action:

Continue with AutoMatt. Read automatt-state.json, then continue from phase "<phase>". Use the referenced artifacts and start with the next step listed in next_steps.

Workflow

AutoMatt coordinates the lifecycle; it does not recreate other skills from memory. When you propose another skill and the user accepts, or the phase clearly applies, read and follow that skill.

• Discovery: clarify goal, user, success criteria, scope, constraints, and whether the work should exist.
• Scoping: before any deep grilling, do a light surface pass to enumerate the distinct areas this task spans, such as data model, UX, auth, integration, deployment, or migration. Decide whether deep grilling fits one session or should split across fresh sessions to avoid context degradation. Single thread by default; split only when a sequential interview is likely to exhaust useful context. If it should split, draft one continue_prompt per area that points back to automatt-state.json and names which area to grill.
• Grilling: once scope is sized, propose grill-me for general plans or grill-with-docs when repo docs, glossary, ADRs, or code need to shape the plan.
• Prototype: if a question needs visual exploration, concrete code, or a working spike to answer, propose prototype. Return to grilling afterward.
• PRD: when decisions are stable, propose local PRD drafting with to-prd behavior unless the user explicitly asks to publish.
• Stories/issues: propose to-issues behavior to split the PRD into tracer-bullet vertical slices. Keep publishing optional.
• Implementation: propose tdd / test-driven-development where feasible. Keep slices small and verifiable.
• Debugging: if behavior breaks, propose diagnose / systematic-debugging; reproduce and find root cause before changing code.
• Review: propose requesting-code-review or a focused review pass before calling the task done.
• Handoff: when context risk is high, propose handoff, update state, and provide the exact message to paste into a fresh session.

Matt-Style Guardrails

• Prefer low-fidelity questions during grilling. Do not try to settle high-fidelity UI/product feel without a prototype.
• Use the Scoping step to decide whether deep grilling fits one session. Split before grilling, not after; once inside grill-me you have already committed the context.
• Do not let the user become passive. Keep asking, but also summarize direction and recommend when to stop planning and start building.
• Preserve design decisions before clearing context. Never throw away a valuable grilling session without PRD, state, or handoff output.
• Parallel sessions/subagents are optional: use them only for bounded research, review, tests, or isolated spikes. Do not make v1 depend on parallel orchestration.

Output Pattern

At decision boundaries, phase changes, or handoff points, say:

1. Current phase.
2. Recommended next skill/action.
3. One question for the user, with your recommended answer, only if a decision or blocking ambiguity remains.
4. Whether automatt-state.json needs to be created or updated.

Proceed without asking when the next step is clear and low-risk. Do not proceed through multiple decision branches without user feedback.