Named Plans Registry

Named plans let one repo keep multiple Plans files without making every harness surface guess which file is authoritative.

Files

• Plans.md remains the default plan.
• plans/manifest.json registers additional named plans.
• .claude/state/active-plan.json stores the currently selected plan for local harness commands.

Example manifest:

{
  "schema_version": "plans-manifest.v1",
  "plans": {
    "default": "Plans.md",
    "roadmap": {
      "path": "plans/roadmap.md"
    }
  }
}

Commands

scripts/plan-registry.sh list
scripts/plan-registry.sh path roadmap
scripts/plan-registry.sh switch roadmap
scripts/codex-loop.sh start all --plan roadmap
scripts/plans-issue-bridge.sh --plan roadmap --format markdown
node scripts/generate-sprint-contract.js --plan roadmap 9.1.1

--plan NAME is intentionally explicit for long-running or export flows. The active plan is convenient for local work, but CI and release automation should pass the plan name directly when more than one plan exists.

Safety Rules

• Plan names may contain only letters, numbers, _, ., and -.
• Manifest paths must be relative to the project root.
• Absolute paths, .. traversal, and symlink escapes outside the repo are rejected before any plan is read.
• --plan cannot be combined with an explicit --plans PATH argument in the issue bridge.

Operational Rule

One harness run should use one named plan from start to finish. Do not switch the active plan while codex-loop or a worker run is in progress; start another run with a separate --plan value instead.