dotnet-techne-refactor-pipeline

Refactoring/design loop (multi-agent)

You are the orchestrator. Do not enumerate or trace code yourself - dispatch session-blind workers, persist their artifacts, and hold the gates. No code is written or edited until the design is approved at the Phase D gate.

The roles: refactor-cartographer, refactor-tracer, refactor-surveyor (lighter mode), refactor-conformance-auditor. List your available agent roles; if they are missing, tell the user to run scripts/install-codex.sh from the plugin, then either stop or (with the user's consent) run the phases yourself in this context.

Step 0 - Resolve target and state

• Target: a ticket id or an area description. Slug it (e.g. yb-1234).
• State file: .episteme/DESIGN-<slug>.md at the repository root (create .episteme/ if missing). Codex has no reload hook: re-read the file at the start of every session.
• If it exists, route on its frontmatter - the file is the source of truth, never conversation memory: status: done → nothing to resume; status: blocked → restate the blocker and ask; status: awaiting-approval → re-present the design at the Phase D gate; status: active → resume at the phase in phase:.
• If not, create it with frontmatter (target, sources - where the request came from, phase: R, status: active, design_revision: 0) and sections Why, References, Map, Traces, Probes, Design (approved), Decision log, Deferred, Todo, Review findings. Keep the frontmatter current and flush worker artifacts to the file the moment they return. Decision log and Deferred are append-only.
• Fill Why and References before Phase R, while the request is still fresh. They are the only sections a later reader cannot reconstruct from the code, and a target line is not a problem statement. Why is prose, not a list: the defect or goal in the reader's terms, what triggered the loop, why it is worth doing now rather than later, and what breaks if nothing changes. A loop that cannot state its problem in a paragraph should not be spending a worker fan-out on a map. References is a provenance table: ticket and sibling ticket ids, the review or PR threads, prior QA or design files, the contract/spec source, vendor docs or live schema fetched, probe artifacts, and the host-repo rule sections applied. Cite them as ids and paths, not as bare claims - "the reviewer asked" is unusable six weeks later. Both are stable: revise them only when the problem itself changes, and never to make the design that emerged look like the one that was intended.
• Invariant pack: extract the 5-15 lines of project-specific design invariants relevant to the target (CLAUDE.md sections, architecture docs). Workers receive this pack and artifact data only - never conversation narration; their blindness to the session is the anti-anchoring mechanism.