grimoire-refactor
Own only cross-stage coordination and final acceptance. Map owns navigation and source evidence; improve/simplify own their findings and recommendations; check executors own verification results. Reference those records rather than creating parallel stores. Use grimoire-map, grimoire-improve, grimoire-simplify, grimoire-test, grimoire-review, and grimoire-check for their respective responsibilities. Load each when used. Do not nest grimoire-loop. If a skill is unavailable, disclose it and use equivalent steps only when permitted; never claim it ran.
Execution contract
Before any writes, establish scope, analyze/implement mode, allowed write paths, persistence, permitted checks, and reporting. Match discovery to the task: function plus necessary callers/contracts/tests; module internals plus adjacent dependencies/consumers; full specified subsystem plus external seams; or every first-party module and cross-module seam for deep whole-repository work. Expand reads for affected contracts or uncertain reachability, not unrelated cleanup. Pass the selected scan scope to every child skill. Audit requests do not authorize code changes. Explicit no-write requests use in-memory observations and inline reports: create no map, ledger, or report files. Pass these restrictions to every child skill; standalone defaults cannot restore excluded work.
Comprehensive implementation authorization covers reversible in-scope internal rewrites without per-batch approval. Preserve observable behavior and public contracts; ask only for material scope expansion, contract changes, or irreversible actions. Multi-agent execution is optional and requires host/user permission. Serial execution retains the same coverage and verification.
1. Establish baseline
Use map to establish the scoped baseline source reference before publishing run state; record user changes to preserve, baseline check references, and acceptance criteria. Optimize understanding cost; there is no default LOC reduction target. Use LOC as a target only when the user explicitly requests a quantified compression goal. Only an explicitly required numeric threshold is a hard gate; targets are global, never worker quotas.
Use measurement.md when evaluating a user-specified LOC target; otherwise use relevant structural evidence without requiring a LOC baseline. Separate user targets' aspirational/required status from behavior and structural gates.
Read the shared coordination contract v1 for owner records and references, and coordination.md for handoffs and integration. When persistence is allowed, create .grimoire/refactor/<run-id>/state.json using run schema v2. Revalidate referenced owner evidence on resume; without persistence, use the same contract with inline artifacts.
2. Discover and synthesize
Extend the baseline map with scoped navigation, then use grimoire-improve and grimoire-simplify in analyze-only mode within the same scope. Have the analysis owners examine responsibility/state, control flow, duplication/dead code, abstractions/dependencies, and cross-module reuse where relevant. Omit irrelevant lenses with reasons, not unexamined in-scope subsystems. For subsystem/repository scans, require file-level coverage; function-level observations may leave the containing file partial. Search hits are not inspection. Keep unread/blocked regions visible and retain module results without loading the entire repository into one context.