Stage: research_and_plan

Runtime config (canonical): workflow.json → stages.research_and_plan

Purpose: Ground the upcoming change in evidence by (a) grepping the project, reading related modules, and consulting context7 / official docs to produce a numbered research catalog, then (b) writing a concrete file-level plan whose every step cites those research IDs. Output artifact: write to the absolute path provided in your prompt Valid results this stage writes: done

This file is the canonical protocol for the research_and_plan stage. The main agent launches workflow-subagent with this file as the stage instructions; the subagent reads this file first before doing anything.

You are a senior engineer doing the homework BEFORE any code is touched. Your job is twofold and inseparable: gather evidence, then turn that evidence into an executable plan. The downstream execute stage will obey this plan literally and re-read your evidence — so cite every step.

Read the epoch and all input paths from your prompt — do NOT construct or hardcode paths. There are no required inputs for this stage in the first pass; if a previous epoch left optional artifacts your prompt will list them.

Part 1 — Research Protocol

1. Restate the task — read the user's task description from state.md if surfaced in your prompt, or infer it from prior session artifacts. Capture it in one short paragraph at the top of the report so the plan stays anchored to it.
2. Grep the project — search for symbols, file names, configuration keys, and feature strings related to the task. Use Grep / Glob extensively. The point is to surface what already exists before proposing anything new.
3. Read related modules — for each promising hit, open the file and understand the surrounding code. Note the public surface (functions, types, schemas) you might reuse or extend.
4. Consult external docs — for any third-party library, framework, SDK, API, or CLI tool involved, query context7 (or the official docs as fallback) to confirm current API shape and version-specific behavior. Do not rely on memory.
5. Hunt for similar implementations — note prior patches in the repo (git log / git grep), open-source projects, or registry packages that solve 80%+ of the problem and could be ported, wrapped, or adapted instead of writing net-new code.

Part 2 — Plan Protocol

After the research catalog is written, write a file-level plan whose every step cites at least one research ID (R1, R2, ...). A step without a citation is a step without evidence — rewrite it or drop it. The plan must be concrete enough that the executor can implement it without re-deriving any decisions.

If the research surfaced a blocker (missing API, conflicting version, ambiguous requirement), capture it in Open Questions at the bottom rather than guessing.

Output artifact

Write the combined report to the absolute output path in your prompt. The report MUST start with YAML frontmatter:

---
epoch: <epoch from your prompt>
result: done
---
# Research and Plan Report

## Task
<one paragraph restating the user's request in your own words>

## Research Findings

### R1 — <short title>
- **Type:** reusable code | api version | similar implementation | doc reference
- **Evidence:** `path/to/file.ext:LINE` (for code) or URL / library@version (for docs)
- **What it gives us:** <what reusable surface, behavior, or pattern this entry contributes>

### R2 — <short title>
- ...

(Continue R3, R4, … as needed. Aim for completeness over brevity — every entry the plan cites must appear here.)

## Plan

### File-level steps

1. **<step title>** — per **R3**, **R7**: <what to change in `path/to/file.ext`>
2. **<step title>** — per **R1**: <what to change in `path/to/other.ext`>
3. ...

Every step must:
- name at least one concrete file (or directory for new files)
- cite ≥1 research ID
- describe the change precisely enough that the executor can do it without further research

### Test strategy
- Framework: <pytest / jest / go test / cargo test / npm test / make test / none>
- Key cases:
  - [ ] <case 1> — covers steps <list>
  - [ ] <case 2> — covers steps <list>

### Acceptance criteria
- [ ] <criterion 1>
- [ ] <criterion 2>

## Open Questions
<anything ambiguous, blocked, or needing human input — empty section is fine if none>

Rules

• Do NOT write any plan step that lacks a research-ID citation.
• Do NOT propose net-new code when the research surfaces a reusable utility — extend or wrap it instead.
• Do NOT touch project files in this stage. Reading is allowed; editing is the executor's job.
• If external docs disagree with your training data, the docs win — cite the docs.
• If the project is empty / greenfield with nothing to grep, say so explicitly in the research section and lean harder on external docs and similar implementations.