Execute

/meridian:execute — Execution Engine

Run plans via fresh-context subagents with TDD enforcement and 2-stage review.

Arguments

• --phase — Execute specific phase (default: current phase)
• --plan — Execute single plan
• --wave — Execute specific wave only
• --no-review — Skip 2-stage review (not recommended)
• --inline — Execute in current context instead of subagent

Procedure

Step 1: Determine What to Execute

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from scripts.db import connect, get_db_path
from scripts.state import compute_next_action, get_phase, list_plans
conn = connect(get_db_path('.'))
action = compute_next_action(conn)
print(json.dumps(action, indent=2, default=str))
conn.close()
"

If action is execute or execute_plan, proceed. Otherwise, show the required action.

Step 2: Transition Phase to Executing

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import transition_phase
conn = connect(get_db_path('.'))
transition_phase(conn, , 'executing')
conn.close()
"

Step 3: Execute Plans by Wave

For each wave (starting from 1):

3a. Get plans for current wave

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_plans_by_wave
conn = connect(get_db_path('.'))
plans = get_plans_by_wave(conn, , )
print(json.dumps(plans, indent=2, default=str))
conn.close()
"

3b. For each pending plan in the wave:

1. Mark plan as executing:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import transition_plan
conn = connect(get_db_path('.'))
transition_plan(conn, , 'executing')
conn.close()
"

1. Check freeze state before dispatching:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from scripts.db import connect, get_db_path
from scripts.freeze import get_freeze
conn = connect(get_db_path('.'))
frozen = get_freeze(conn)
conn.close()
print(json.dumps({'frozen_directory': frozen}))
"

If freeze is active, verify plan's filestocreate and filestomodify are within the frozen directory. If any file is outside, warn the user and ask for confirmation before proceeding.

1. Inject learnings into subagent prompt:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.learnings import get_learnings_for_prompt
conn = connect(get_db_path('.'))
print(get_learnings_for_prompt(conn, phase_id=))
conn.close()
"

1. Check for retro prompt (auto-scheduling):

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from scripts.db import connect, get_db_path
from scripts.auto_learn import check_phase_for_retro_prompt
conn = connect(get_db_path('.'))
print(json.dumps(check_phase_for_retro_prompt(conn)))
conn.close()
"

If should_prompt is True, suggest running /meridian:retro after execution completes.

1. Dispatch subagent with the implementer prompt (prompts/implementer.md):

• Use Agent tool with subagent_type: "general-purpose"
• Include plan description, files to create/modify, test command
• Include project context from phase's context_doc
• Include learnings section from step 3
• If TDD required, include TDD protocol from discipline-protocols.md

1. On success: Mark plan complete with commit SHA:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import transition_plan
conn = connect(get_db_path('.'))
transition_plan(conn, , 'complete', commit_sha='')
conn.close()
"

1. On failure: Mark plan failed and suggest learning:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import transition_plan
conn = connect(get_db_path('.'))
transition_plan(conn, , 'failed', error_message='')
conn.close()
"

After marking failed, suggest a learning:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from scripts.db import connect, get_db_path
from scripts.auto_learn import suggest_learning_from_failure
conn = connect(get_db_path('.'))
suggestion = suggest_learning_from_failure(conn, , '')
print(json.dumps(suggestion, indent=2, default=str))
conn.close()
"

If the plan is later fixed, ask the user: "Save this as a learning?" and use /meridian:learn to persist.

3c. Plans in the same wave CAN be dispatched in parallel using multiple Agent calls.

Step 4: After All Plans Complete

Transition phase to verifying:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import transition_phase
conn = connect(get_db_path('.'))
transition_phase(conn, , 'verifying')
conn.close()
"

Step 5: Verify Acceptance Criteria

Check each acceptance criterion against the implemented code. Run tests.

Step 6: Two-Stage Review (unless --no-review)

Stage 1 — Spec Compliance: Launch Agent with prompts/spec-reviewer.md

• Does implementation match plan descriptions?
• Are all acceptance criteria met?
• Are specified files created/modified?

Stage 2 — Code Quality: Launch Agent with prompts/code-quality-reviewer.md

• Code cleanliness and readability
• Security concerns
• Performance considerations
• Convention adherence

Step 7: Complete Phase

If review passes:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import transition_phase
conn = connect(get_db_path('.'))
transition_phase(conn, , 'reviewing')
transition_phase(conn, , 'complete')
conn.close()
"

If review fails, transition back to executing with notes on what needs fixing.

Step 8: Checkpoint

Create automatic checkpoint after phase completion:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import create_checkpoint
conn = connect(get_db_path('.'))
create_checkpoint(conn, trigger='phase_complete', phase_id=)
conn.close()
"

Step 9: Export and Show Next Action

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.export import export_state
from scripts.db import connect, get_db_path
from scripts.state import compute_next_action
export_state('.')
conn = connect(get_db_path('.'))
import json
print(json.dumps(compute_next_action(conn), indent=2, default=str))
conn.close()
"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mattjaikaran
• Source: mattjaikaran/meridian
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.