mattjaikaran /meridian:plan — Planning Pipeline
Brainstorm → Context Gather → Generate Plans with Wave Assignments.
Arguments
<goal>— What to build (required on first run, or creates milestone)--milestone <id>— Target milestone (default: active milestone)--phase <id>— Plan a specific phase (skip brainstorming)--deep— Office hours mode: force 5 strategic questions before brainstorming--scale <small|medium|large>— Override auto-detected scale (stored in DB)
Procedure
Step 1: Ensure Meridian is Initialized
Check for .meridian/state.db. If missing, run /meridian:init first.
Step 2: Check Current State
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from scripts.db import connect, get_db_path
from scripts.state import get_status, compute_next_action
conn = connect(get_db_path('.'))
status = get_status(conn)
action = compute_next_action(conn)
print(json.dumps({'status': status, 'action': action}, indent=2, default=str))
conn.close()
"
Step 2.5: Scale Detection
Detect project scale to auto-tune planning depth.
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from scripts.db import connect, get_db_path
from scripts.state import list_phases
from scripts.scale import detect_scale, get_scale_override
conn = connect(get_db_path('.'))
override = get_scale_override(conn)
conn.close()
# Count phases in active milestone if known
scale = detect_scale('.', override=override)
print(json.dumps(scale, indent=2))
"
If --scale <value> was passed, persist the override first:
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.scale import set_scale_override
conn = connect(get_db_path('.'))
set_scale_override(conn, '<scale_value>')
conn.close()
"
Scale rules:
small(<5k LOC, ≤3 phases): skip context-gathering subagent, use fast planning. No --deep.medium(default): standard pipeline (Steps 4–6 as written).large(≥50k LOC or ≥10 phases): force --deep discovery (Step 3.5), run parallel research subagents before Step 5.
Display scale decision banner before proceeding:
## Scale: <SMALL|MEDIUM|LARGE> (<source>)
<rationale>
Log the scale decision:
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import create_decision
conn = connect(get_db_path('.'))
create_decision(conn, 'Scale: <scale> — <rationale>', category='approach')
conn.close()
"
Step 3: Create Milestone (if needed)
If no active milestone exists, create one from the user's goal:
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import create_milestone, transition_milestone
conn = connect(get_db_path('.'))
create_milestone(conn, '<id>', '<name>', description='<description>')
transition_milestone(conn, '<id>', 'active')
conn.close()
"
Step 3.5: Deep Discovery (if --deep)
If --deep flag is present, ask these 5 forcing questions BEFORE brainstorming.
Use AskUserQuestion for each. Do NOT skip any.
- Who needs this? — "Who is the specific user or persona that benefits? Not 'everyone' — name the person or role."
- What's the status quo? — "How is this handled today without this feature? What workaround exists?"
- What's the narrowest wedge? — "What is the absolute smallest version that delivers value? Strip it to bare minimum."
- What breaks without it? — "What are the consequences of NOT building this? Who is hurt and how?"
- What does success look like? — "Describe a concrete, measurable outcome. How do we know it worked?"
After collecting all 5 answers, store them as a decision:
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import create_decision
conn = connect(get_db_path('.'))
create_decision(conn, 'Deep Discovery: <goal summary>', category='constraint',
rationale='''Who: <answer1>
Status Quo: <answer2>
Narrowest Wedge: <answer3>
Without It: <answer4>
Success: <answer5>''')
conn.close()
"
Feed these answers into Step 4 brainstorming and Step 5 context gathering. Use the "narrowest wedge" answer to constrain scope. Use the "success" answer to shape acceptance criteria.
Step 4: Brainstorm Phases
Think through the work as an architect:
- What are the major work units?
- What depends on what?
- What can be parallelized?
- What are the acceptance criteria for each phase?
Create phases in sequence order:
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import create_phase
conn = connect(get_db_path('.'))
create_phase(conn, '<milestone_id>', '<name>', description='<desc>',
acceptance_criteria=['criterion 1', 'criterion 2'])
conn.close()
"
Step 5: Context Gathering (per phase)
Small scale: skip this step — proceed directly to Step 6 with a brief inline context summary.
Medium/Large scale: dispatch a context-gatherer subagent.
Launch an Agent (subagent_type: Explore) with the prompt from prompts/context-gatherer.md, customized with:
- Phase name and description
- Project tech stack
- Acceptance criteria
Large scale only: also launch a second parallel Agent (subagent_type: general-purpose) focused on cross-phase risk analysis — what dependencies, shared state, or integration points could break when this phase is executed. Merge both agents' outputs before storing.
The subagent returns a context document. Store it:
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import update_phase, transition_phase
conn = connect(get_db_path('.'))
update_phase(conn, <phase_id>, context_doc='''<gathered_context>''')
transition_phase(conn, <phase_id>, 'context_gathered')
conn.close()
"
Step 6: Generate Plans
Based on the gathered context, break the phase into executable plans:
- Each plan = one subagent's worth of work
- Assign waves for parallelism (wave 1 first, wave 2 after wave 1 completes)
- Specify files to create/modify
- Set test commands
- Mark TDD required/not
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import create_plan, transition_phase
conn = connect(get_db_path('.'))
create_plan(conn, <phase_id>, '<name>', '<description>',
wave=1, files_to_create=['path/file.py'], test_command='uv run pytest tests/')
# ... more plans ...
transition_phase(conn, <phase_id>, 'planned_out')
conn.close()
"
Step 7: Export State
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.export import export_state
export_state('.')
"
Step 8: Show Plan Summary
Display all phases and plans in a table, showing wave assignments and dependencies.
Step 9: Record Decisions
Log any architectural or approach decisions made during planning:
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import create_decision
conn = connect(get_db_path('.'))
create_decision(conn, '<summary>', category='architecture', rationale='<why>')
conn.close()
"
Output
Show the full plan breakdown with phase sequence, plan waves, and next action.