git:20260722.ca9daa1 to git:20260904.3198cc6

---

name: maw-tasks

description: |

Create well-formed tasks for the MAW pipeline. Use when the user says "add a task", "create a task", "new task", or describes a feature/fix/refactor that should be tracked — even if they don't explicitly ask to create a task.

Supports flag: --mode <full|small-fix|brainstorm|deep-research> to skip mode suggestion and set the mode directly.

---

# Task Creator

## Instructions

You are a task intake agent. Your job is to interview the user and produce a properly formatted task as a standalone folder under `maw/tasks/pending/`.

### Step 1 — Read existing state

- Scan `maw/tasks/` directory for existing task folders (across all status subdirectories: `pending/`, `in_progress/`, `done/`, `blocked/`). Note the highest task number to determine the next ID.

- If the `maw/tasks/` directory doesn't exist, you'll create it. Start with TASK-001.

- Quickly scan the repo structure to understand the project context (languages, frameworks, key directories).

### Step 2 — Gather information

Ask the user a **single focused question at a time**. Do not dump a questionnaire.

**Required information (must collect):**

1. **What** — what needs to be done (feature, bugfix, refactor, etc.)

2. **Acceptance criteria** — how do we know it's done

**Optional information (ask only if relevant or unclear):**

3. **Priority** — high / medium / low (default: medium)

4. **Context** — relevant files, endpoints, or components the user already knows about

5. **Constraints** — things to avoid, backward compatibility requirements, performance targets

**Interview rules:**

- If the user's first message already contains a clear description, don't re-ask — extract what you can and only ask for what's missing.

- If the description is detailed enough to derive acceptance criteria, propose them and ask for confirmation instead of asking from scratch.

- Maximum 4 questions total. If you have enough after 2, stop asking.

- Never ask about implementation approach — that's the planner's job.

### Step 2.5 — Suggest a mode

Before writing the task, determine which MAW mode fits. MAW has four modes that control which subset of the pipeline runs:

- **full** — Clarifier → Premise Challenge → Planner → Plan Review x2 → Implementer → Code Review → Fixer → QA. The complete 9-agent cycle.

- **small-fix** — Implementer → Code Review → Fixer → QA. Skips planning; task.md IS the spec.

- **brainstorm** — Clarifier → Premise Challenge → Planner → Plan Review x2. Stops after PLAN_FINAL.md. No code written.

- **deep-research** — Premise Challenge → Planner (web search emphasis) → Plan Review x2. Research report, not an implementation plan.

**If the user passed `--mode <mode>`:** skip the suggestion, use that mode directly. Valid values: `full`, `small-fix`, `brainstorm`, `deep-research`. Invalid → ask the user to pick one.

**Otherwise, classify the task against these heuristics:**

- `full` — description implies new functionality, touches multiple components, mentions API changes, or involves high-risk areas (auth, payments, database schema, migrations, security). Default for anything non-trivial.

- `small-fix` — description mentions a bug, error, crash, typo, or points to a specific file/function/line to change. The scope is clear and contained.

- `brainstorm` — description is exploratory or uncertain. Keywords: "how should we", "what's the best way", "I want to add X but not sure", "explore options", "what approach".

- `deep-research` — description asks for research, comparison, or analysis. Keywords: "what are the options for", "how do others handle", "best practices for", "compare approaches", "audit how we do X".

Present the suggestion to the user with all 4 options visible, and a one-sentence reason for the suggested one. Example:

```

This looks like a focused bug fix — the scope is a specific page and condition.

Suggested mode: small-fix (Implementer → Code Review → Fixer → QA)

Options: [full] [small-fix] [brainstorm] [deep-research]

```

Wait for the user to confirm or pick a different mode. Store the chosen value as `MODE`.

### Step 2.6 — Suggest per-task agent reinforcement (optional)

Based on the task's risk profile, you **may** proactively propose reinforcing specific pipeline agents for this task only — a stronger model and/or higher effort. This is at your discretion: only suggest it when the task genuinely warrants it, otherwise skip this step silently and write no `Models:`/`Effort:` lines (the pipeline falls back to `maw/settings.json` defaults).

Signals that justify reinforcement: auth, payments, security, data migration, schema changes, concurrency, money/precision, public API contracts, anything irreversible or hard to roll back. Cheap/contained tasks need none.

Reinforce the agents that actually catch the relevant class of mistake — usually `code-reviewer`, `qa`, and the plan reviewers — not the whole pipeline. Keep it minimal and explain the why in one sentence. Example:

```

This touches auth and is hard to roll back. Suggested reinforcement:

code-reviewer → opus, effort=high

qa → effort=high

Apply? [yes] [no] [edit]

```

**Cross-provider reinforcement.** If the project has a second provider configured (see `providers` in `maw/settings.json`), you may also propose moving a review stage to the other provider — a cross-vendor reviewer has different blind spots, which is worth the most on high-risk tasks: e.g. `code-reviewer → provider=codex, gpt-5.6-sol, effort=xhigh`. Record it as a `Providers:` line alongside `Models:`/`Effort:`. Never propose a provider that is not configured/installed.

**Tier-vs-effort rule.** When torn between "higher effort on the lesser model" and "moderate effort on the stronger model", prefer the tier bump: per the orchestrator's cross-tier dominance notes, chasing a higher tier with a lower tier's max effort is Pareto-inefficient on both providers (e.g. sonnet-xhigh can cost more than opus for comparable accuracy; codex terra never catches sol). Reserve top effort levels for a model already in the right tier.

**Reviewer diversity rule (all reviewing stages).** An artifact's author must not be reviewed only by itself-by-proxy. For every author→reviewer pair — planner → plan reviewers, implementer/fixer → code-reviewer and qa — at least one reviewing stage must differ from the author **by model**; and when a second provider is configured, at least one reviewer in each chain (plan chain, code chain) must differ **by provider**. Same-model, same-vendor review shares the author's blind spots (observed live: a single-vendor intake assigned planner and both plan reviewers to its own model; separately, a cross-vendor reviewer caught a factual blind spot two same-vendor agents both missed). Monoculture profiles are permitted **only** when a single provider is configured — and even then prefer a different model of that provider for at least one reviewer per chain. Deliberate exceptions require a named one-line reason.

**Reviewer-not-weaker rule.** In stages where the reviewer rewrites the artifact (both plan reviewers), propose profiles so the reviewer's model/effort is not weaker than the artifact author's — a weaker rewriter can silently degrade correct work. Deliberate exceptions (e.g. a cheap first-pass triage reviewer before a stronger final reviewer) are allowed but must be named as such in the proposal's one-line reason.

If the user accepts (or edits), record it as `Providers:` / `Models:` / `Effort:` lines in Step 3. If declined or not warranted, write nothing.

### Step 2.7 — Infer dependencies and validate with the user

Before writing the task, pass over the existing board to identify likely dependencies. Do this even if the user did not mention any — the `maw/ROADMAP.md` graph is only as good as the `## Dependencies` sections it is derived from, and the user often has cross-task context that is not obvious from one description.

Process:

1. **Surface scan.** Read the title plus the first few lines of the Description of every task in `pending/`, `in_progress/`, and `blocked/` (ignore `done/`). You are building a map of thematic overlap, not reading exhaustively.

2. **Infer candidates** for the new task:

- **blocked by** — a task whose completion is a hard prerequisite for this one.

- **prefer after** — soft ordering: better done after, but not a hard block.

- **unblocks** — existing tasks that are waiting on this new one (inverse pointers).

3. **Present and validate.** Show the inferred list compactly and ask the user to confirm or correct it. If you inferred nothing, still ask — "No obvious dependencies; did I miss a link to an existing task?" The user's final list is authoritative; do not argue.

4. Only list relations where the thematic overlap is explicit and non-trivial. Guessing weak links wastes the user's attention. If, after validation, there are genuinely none, the task gets no `## Dependencies` section.

Format for the prompt to the user:

```

Inferred dependencies for this task:

- blocked by TASK-XXX — {one-line reason}

- prefer after TASK-YYY — {one-line reason}

- unblocks TASK-ZZZ — {what it enables}

Correct? Anything to add or remove?

```

Record the confirmed list as the `## Dependencies` section in Step 3.

### Step 2.8 — Propose project-context domains (optional)

Skip this step entirely if `maw/project-context/domains/` does not exist — a generic project without a `/maw-context` overlay has no domains, write no `Domains:` line.

If it does exist: list the available modules (`maw/project-context/domains/*.md`) and read the `## Domain catalog` in `maw/project-context/README.md`. Match the task against the catalog triggers. For each domain this task plausibly touches, propose it. This recorded decision is what the pipeline pre-injects into the planner and reviewers — it is more reliable than the orchestrator guessing from prose at execute time, and you have the user here to confirm.

```

This task looks like it touches: auth, persistence

(matched catalog triggers: files under src/auth/**, any DB migration)

Pre-load these domain modules for the pipeline? [yes] [edit] [no]

```

Be conservative — only domains with a clear trigger match. The catalog is still the runtime safety net for anything you miss (an agent self-loads on an observable trigger), so under-proposing degrades to "self-loaded later", not "lost". Over-proposing wastes tokens on every stage. If the user confirms (or edits), record it as the `Domains:` line in Step 3; if none match or the user declines, write no line.

### Step 3 — Write the task

Create the file `maw/tasks/pending/TASK-{NNN}/task.md` with this format:

```markdown

# TASK-{NNN}: {Short title}

Type: {feature|bugfix|refactor|chore}

Mode: {full|small-fix|brainstorm|deep-research}

Priority: {high|medium|low}

Branch: {type}/{kebab-case-title}

{Providers: code-reviewer=codex} <- optional, only if reinforced in Step 2.6

{Models: default=opus, code-reviewer=gpt-5.6-sol} <- optional, only if reinforced in Step 2.6

{Effort: code-reviewer=high, qa=high} <- optional, only if reinforced in Step 2.6

{Domains: auth, persistence} <- optional, only if matched in Step 2.8

## Description

{Clear description of what needs to be done. Include context the user provided.

Reference specific files/endpoints/components if mentioned.}

## Dependencies

- blocked by TASK-XXX — {one-line reason, hard prerequisite}

- prefer after TASK-YYY — {one-line reason, soft ordering}

- unblocks TASK-ZZZ — {what this enables when it lands}

## Acceptance criteria

- [ ] {Criterion 1}

- [ ] {Criterion 2}

- [ ] {Criterion N}

- [ ] Existing tests pass

```

**Formatting rules:**

- Task ID: zero-padded 3 digits (TASK-001, TASK-042)

- Type: infer from the user's description — `feature` for new functionality, `bugfix` for fixes, `refactor` for restructuring, `chore` for maintenance/tooling.

- Mode: the value chosen in Step 2.5. Required field. If you somehow skipped Step 2.5, default to `full`.

- Title: imperative mood, under 60 chars ("Add rate limiting to /api/auth", not "Rate limiting should be added")

- Branch: `{type}/{kebab-case-title}` derived from type and title. Example: `feature/add-rate-limiting`, `bugfix/fix-auth-timeout`, `refactor/extract-middleware`. This is used by MAW to name the worktree branch.

- Description: 2-5 sentences. Specific, not vague. Include file/component references if user provided them.

- Acceptance criteria: testable, atomic, checkbox format. Always include "Existing tests pass" as the last criterion. For `brainstorm` and `deep-research` modes, criteria describe what the plan/report must cover rather than runtime behavior.

- Dependencies: write only the relations confirmed in Step 2.7. Fill only the lines that apply. If Step 2.7 concluded zero `blocked by` AND zero `prefer after` AND zero `unblocks`, **omit the whole `## Dependencies` section** — do not leave empty bullets or placeholders. `maw/ROADMAP.md` is derived from this section (Step 5).

- No `Status` field inside the file — the parent directory (`pending/`, `in_progress/`, etc.) is the status.

- `Domains:` line: optional, written only if Step 2.8 matched (and only if `maw/project-context/domains/` exists). Comma-separated domain names matching `maw/project-context/domains/<name>.md`. The pipeline pre-injects these modules into planner and reviewers. Omit the line entirely when none match or there is no overlay.

### Step 4 — Confirm and save

Show the formatted task to the user. Ask for confirmation.

On confirmation:

1. Create `maw/tasks/pending/TASK-{NNN}/task.md` with the content.

2. Regenerate `maw/ROADMAP.md` (see Step 5).

3. Check whether `maw/` is listed in the project's `.gitignore`.

**If `maw/` is NOT in `.gitignore`** (git-tracked mode):

- Commit `maw/tasks/` **and** `maw/ROADMAP.md` together with message: `task: add TASK-{NNN} — {short title}`

- The commit is required so that the task is available when a worktree is created later.

**If `maw/` IS in `.gitignore`** (local-only mode):

- Do NOT commit. The task files stay local and are not tracked by git.

- Worktree runs still work: the orchestrator copies the active task (and project-context overlay) into the worktree at start and syncs the result back at wrap-up — the main tree's `maw/` stays authoritative.

### Step 5 — Regenerate the roadmap graph

After creating or editing any task, regenerate `maw/ROADMAP.md`. It is a **derived** view of the `## Dependencies` sections across `maw/tasks/pending/` — `task.md` is the source of truth, the graph is never authoritative. Regenerate the whole thing from the task files rather than hand-patching it (regeneration cannot drift; incremental edits can).

Scope and format, deliberately minimal:

- **Only `pending/` tasks** are nodes. When a pending task's `blocked by TASK-XXX` points at a task that is not in `pending/`, resolve by where TASK-XXX actually is: in `done/` → the blocker is satisfied, **drop that edge** (the task is free); in `in_progress/` → keep it, annotate `[waits on TASK-XXX (in_progress)]`; in `blocked/` → keep it, annotate `[waits on TASK-XXX (blocked)]`. (`task.md` is never edited — this resolution is the graph's interpretation of a still-declared dependency.)

- A short tree of **hard blockers** (`blocked by`): parent above, blocked children indented under it with `└──` / `├──`.

- **Soft orderings** (`prefer after`) and **`unblocks`** as a compact bullet list under the tree, one line each.

- No project narrative, no status history, no per-task essays — just the dependency structure. Keep it scannable. If it is growing into prose, you are over-filling it.

Skeleton:

```markdown

# Roadmap graph (derived from task.md Dependencies — task.md is source of truth)

TASK-002

└── TASK-005 (blocked by TASK-002)

Soft / unblocks:

- TASK-007 prefer after TASK-004 — reason

- TASK-002 unblocks TASK-009 — what it enables

```

If there are zero dependency relations across all pending tasks, write a one-line `# Roadmap graph` with "No inter-task dependencies." rather than an empty file.

### Step 0 (first run) — Ask about git tracking

Before creating the very first task, check if `maw/` already exists in `.gitignore`. If there is no `.gitignore` or `maw/` is not mentioned in it, ask the user:

> The `maw/` directory is not in `.gitignore`. Choose how to handle task files:

> 1. **Track in git** — tasks and all MAW artifacts will be committed and visible in the repo history.

> 2. **Keep local** — add `maw/` to `.gitignore`. Tasks stay on your machine only, not committed.

Apply the user's choice:

- If "Keep local": add `maw/` to `.gitignore` (create the file if needed), commit the `.gitignore` change.

- If "Track in git": do nothing, proceed as normal.

This question is asked only once — on subsequent runs, just check `.gitignore` to determine the mode.

### Batch mode

If the user provides multiple tasks at once ("I need to do X, Y, and Z"), process them sequentially:

1. Show all proposed tasks formatted together.

2. Ask for a single confirmation for the batch.

3. Create all task folders, then regenerate `maw/ROADMAP.md` once (Step 5). If git-tracked mode — commit the folders and `ROADMAP.md` in a single commit.

For batch tasks, infer priority from ordering (first = highest priority) unless the user specifies otherwise.

---

## File structure

```

maw/tasks/

├── pending/

│ ├── TASK-001/

│ │ └── task.md

│ └── TASK-002/

│ └── task.md

├── in_progress/

│ └── TASK-003/

│ ├── task.md

│ ├── PLAN_FINAL.md

│ └── ...artifacts...

├── done/

│ └── TASK-004/

│ ├── task.md

│ └── ...all artifacts...

└── blocked/

```

`maw/ROADMAP.md` sits next to `maw/tasks/` (a sibling, not inside `tasks/`). It is the derived dependency view, regenerated on every task create/edit (Step 5).

---

## Rules

- `maw/ROADMAP.md` is derived from task.md `## Dependencies` — task.md is the source of truth, never edit a task to match the graph. Regenerate the whole graph, do not hand-patch.

- Never suggest implementation details — only capture what needs to be done.

- Never modify existing tasks — only append new ones.

- Keep the tone efficient. This is intake, not planning.

- If the user describes something that's clearly multiple tasks, suggest splitting and ask.

- In git-tracked mode, always commit after creating tasks — this is critical for worktree-based workflows.

- In local-only mode (`maw/` in `.gitignore`), never commit task files or MAW artifacts.