prime-plans

Human-in-the-loop planning skills for Prime Agent: researched, refined Markdown plans before any code changes.

prime-plans turns a rough repository-change request into a traceable Markdown plan, refines that plan with reviewer or criticizer subagent passes, and hands an accepted plan to a persistent Prime Agent goal that drives implementation until verified complete. It is built on Prime Agent's native project skill layout, persistent IPython kernel, rlm subagents, and agent_message family messaging — no separate execution engine.

Repository: https://github.com/Optim-Agent/prime-plans

Install

The skill set installs once, globally — every project then uses it without copying files.

Fastest: paste this prompt into your Prime Agent session and let the agent do it:

Install the prime-plans skill set for Prime Agent, following the Install section of https://github.com/Optim-Agent/prime-plans: clone the repo to ~/.prime/prime-plans (if that directory already exists, git -C ~/.prime/prime-plans pull instead), then add the absolute path $HOME/.prime/prime-plans/.prime/agent/skills to the skills array in ~/.prime/agent/settings.json (create the file/array if missing, preserve existing entries, use an absolute path). Verify the five SKILL.md files exist under that path, then tell me to restart Prime Agent or run /reload.

Manual install:

git clone https://github.com/Optim-Agent/prime-plans.git ~/.prime/prime-plans

Then register the skills directory in ~/.prime/agent/settings.json (absolute path recommended; ~ is expanded, but relative paths resolve against each session's cwd):

jq --arg p "$HOME/.prime/prime-plans/.prime/agent/skills" \
  '.skills = ((.skills // []) + [$p] | unique)' \
  ~/.prime/agent/settings.json > ~/.prime/agent/settings.json.tmp \
  && mv ~/.prime/agent/settings.json.tmp ~/.prime/agent/settings.json

(If settings.json does not exist yet, create it with echo '{}' > ~/.prime/agent/settings.json first — or just write { "skills": ["$HOME/.prime/prime-plans/.prime/agent/skills"] } with the path expanded.)

Restart Prime Agent or run /reload, then from any repository ask:

Create a plan for <your change>

Update an existing install with git -C ~/.prime/prime-plans pull plus /reload.

Notes:

• The skills resolve their shared references/ and scripts/ relative to the clone, so no per-project merging is needed. If you previously merged skill copies into a project's .prime/agent/skills/, remove them — project copies shadow the global ones on name collisions.
• Planning state and preferences are still per target workspace (.git/prime_plans/ in the repo you run the skills against); nothing is shared across projects except the skill files themselves. .git/prime_plans/config.json is not an install artifact; it is created per target workspace when language, reviewer, or criticizer settings need persisted config.

Skill Set

The public surface is exactly five project skills, installed under .prime/agent/skills/:

Skill	Use it when
create-a-small-plan	A small scoped repo change needs 1 to 3 planning questions. Recommended refinement: one criticizer round, then accept for execution.
create-a-plan	A broad or risky change needs 5 to 10 planning questions and web research. Recommended refinement: one reviewer round, then one criticizer round, then accept for execution.
create-a-big-plan	An open-ended or high-risk effort needs 10 or more planning questions and web research. Recommended refinement: one round of three concurrent reviewers consolidated by the main agent, then one criticizer round, then accept for execution.
diagnose-before-plan	A bug, CI failure, regression, incident, RCA, or broken behavior needs diagnosis before planning.
reference-before-plan	Downloaded projects, articles, papers, or docs must be analyzed before planning choices are safe.

Workflow

1. Inspect the target repository read-only.
2. Initialize workspace state with the helper script (auto git init when the workdir safely has no repository).
3. Ask one planning question at a time, using the standard choice order: recommended option first, Other second-last, Auto-complete last.
4. Ask the mandatory final scope confirmation before writing PLAN_v1.md.
5. Write PLAN_vN.md artifacts with stable IDs and a ## Verifier Checklist.
6. After each plan version, ask the refinement mode question — never run a reviewer/criticizer round without the user (or Auto-complete) selecting it. Refinement uses delegated subagents (or current-session passes). Default recommended sequences: create-a-small-plan — one criticizer round; create-a-plan — one reviewer round, then one criticizer round; create-a-big-plan — one round of three concurrent reviewers consolidated by the main agent, then one criticizer round. Once a level's sequence is complete, the recommended next option is accepting the plan for execution.
7. Ask the native handoff question without Auto-complete: Execute this plan now as a Prime Agent goal, Stop after planning, or Other.
8. If approved, leave the planning workflow and execute as a persistent Prime Agent goal: goal.create(...) with a compact brief pointing at the accepted plan and its ## Verifier Checklist, so the goal loop drives execution across turns until goal.complete(). If another goal is already pending, execution proceeds normally with no new goal.

Runtime Layout

Machine state stays inside the resolved git common directory, so it is never tracked and needs no .gitignore entries:

.git/prime_plans/
  config.json
  active.json
  runs/<run-id>/
    run.json
    decisions.jsonl
    subagents.jsonl
    refs.jsonl
  tmp/
  cache/

Public artifacts stay in the repository:

docs/prime-plans/YYYY-MM-DD-topic/
  DECISIONS.md
  PROBLEM_ANALYSIS.md     # diagnose-before-plan only
  REF_ANALYSIS.md         # reference-before-plan only
  PLAN_v1.md
  PLAN_v1_reviewer_comments.md
  PLAN_v2.md

Large downloaded references stay outside the target repository by default, under ~/.cache/prime-plans/refs/, with summaries and citations copied into the artifact directory.

Workspace State

State resolves through git rev-parse --git-common-dir with GIT_DIR-family environment variables scrubbed, so subdirectories share the enclosing repository's state and linked worktrees share one state home. When a workdir safely has no git repository — no .git entry, not inside a work tree, not the home directory or filesystem root — the helper auto-runs git init (never commits) so the state has a home. A legacy .prime_plans/ directory from earlier versions is migrated automatically on first use, resumably and non-destructively. State does not travel with clones; a fresh clone starts empty while committed docs/prime-plans/ artifacts persist.

Stable preferences live in config.json:

• language.tag for the visible language used by questions and artifacts;
• reviewer / criticizer blocks with mode (delegated-subagent or current-session), model_selector, and confirmed_at;
• artifact root, normally docs/prime-plans.

Each role's model is confirmed once, at that role's first actual use — inherit the main agent's model or pick from the live rlm.find_models() list — and reused thereafter. If a persisted selector later becomes unavailable, set-role --reset-confirmation re-triggers the question. Per-spawn effort is intentionally not configurable: Prime Agent subagents inherit the main session's thinking level, so the real lever is the main session's thinking level at spawn time.

Helper Commands

The state helper is standard-library Python and intentionally small:

python3 scripts/prime_plans_state.py init --workdir .                 # ensure repo + state (auto git init when safe)
python3 scripts/prime_plans_state.py show --workdir .                 # read-only config dump; never mutates
python3 scripts/prime_plans_state.py set-language --workdir . --tag en --source user
python3 scripts/prime_plans_state.py set-role --workdir . --role reviewer --model-selector <selector-or-inherit> --confirmed
python3 scripts/prime_plans_state.py set-role --workdir . --role criticizer --reset-confirmation
python3 scripts/prime_plans_state.py start-run --workdir . --topic "<topic>" --skill create-a-plan --request-text "<original request>"
python3 scripts/prime_plans_state.py record-subagent --workdir . --run-id <run-id> --role reviewer --name <child> --session-dir <dir>

Safety Model

The supported boundary is planning discipline, durable state, and explicit handoff. Before the native execution handoff, the workflow writes only .git/prime_plans/ state and docs/prime-plans/ artifacts — never target source, configs, or tests. Reviewer and criticizer subagents are read-only and report back through agent_message or artifact files.

Auto-complete may answer planning and refinement questions. It must never approve native execution, destructive cleanup, install waivers, publishing, deployment, merge, push, credential use, or anything that changes external state.

Project Layout

.prime/agent/skills/                 The five project skills
references/                          Shared workflow, state/config, and plan template contracts
scripts/prime_plans_state.py         State helper CLI (stdlib only)
scripts/validate_skills.py           Skill set structure validator
tests/                               pytest suite
docs/prime-plans/                    Public planning artifacts (this repo's own runs)

Verification

Run the repo-native proof:

python3 scripts/validate_skills.py
python3 -m pytest -q

Contributing

Small fixes can go straight to PR. For larger behavior changes, create a docs/prime-plans/ plan artifact first so the intent is reviewable before code changes.

Development rules:

• keep helper code standard-library only;
• keep the public skill inventory to the five skills above unless a release plan explicitly changes it;
• preserve the .git/prime_plans state path and the docs/prime-plans artifact path;
• do not broaden Auto-complete across native handoff or external state changes;
• keep reviewer and criticizer sessions read-only;
• update tests for user-visible behavior changes.

License

MIT. See LICENSE.