Meridian:ai Phase

/meridian:ai-phase — AI Integration Phase Type

Spawns 3 parallel subagents (domain researcher, framework selector, eval planner) for a phase that integrates an LLM, AI model, or ML component. Produces AI-SPEC.md in the phase artifact directory. The plan phase soft-gates on this artifact for AI phases.

Position in workflow: ai-phase → spec-phase → discuss-phase → plan-phase → execute-phase

Arguments

• (no args) — spec the current pending/planned phase
• --phase <id> — specify a phase by ID
• --skip-eval — skip the eval planner subagent (faster, 2 subagents only)
• --skip-ai — bypass gate warning in /meridian:plan (emergency only)

Keywords

ai, llm, model, claude, openai, anthropic, gpt, embeddings, rag, agents, tool use, prompt engineering, eval, evaluation, guardrails, inference, fine-tuning, pre-plan

Procedure

Step 1: Find Target Phase

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from scripts.db import connect, get_db_path
from scripts.ai_phase import get_ai_context
conn = connect(get_db_path('.'))
ctx = get_ai_context(conn, phase_id=<phase_id_or_None>)
print(json.dumps(ctx, indent=2, default=str))
conn.close()
"

Pass the --phase <id> value as phase_id, or None if not specified.

If result contains "error", display it and stop — tell the user to run /meridian:plan first.

Store: phase_id, phase_name, description, acceptance_criteria, tech_stack, phase_dir, slug.

Step 2: Check for Existing AI-SPEC.md

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from pathlib import Path
from scripts.ai_phase import check_ai_artifact
result = check_ai_artifact(Path('<phase_dir>'))
print('exists' if result else 'missing')
"

If exists: ask the user — "AI-SPEC.md already exists for this phase. Re-run and overwrite? (y/N)". If No, print the path and exit.

Step 3: Scout the Codebase

Before spawning subagents, read the codebase for AI-relevant patterns:

1. Existing AI/LLM usage — check for anthropic, openai, langchain, llama_index imports
2. SDK versions — check pyproject.toml, package.json, requirements.txt for pinned versions
3. Prompt patterns — look for prompt templates, system prompts, message construction
4. Tool use / function calling — any existing tool definitions?
5. Caching — prompt caching, response caching, embedding stores?
6. Prior phase artifacts in <phase_dir> if present (RESEARCH.md, SPEC.md)

Synthesize into a 2-3 sentence brief of the current AI integration state. Pass as context to each subagent.

Step 4: Spawn AI Subagents (parallel)

Launch all subagents in a single parallel batch (same message). Use subagent_type: Explore for each.

Agent 1 — Domain Researcher:

Research the business domain and real-world application context for the following AI phase.

Phase: <phase_name>
Description: <description>
Tech stack: <tech_stack>
Acceptance criteria:
<formatted list>

Current AI integration state: <2-3 sentence brief from Step 3>

Research:
1. Domain expert evaluation criteria — how would a practitioner in this field judge
   whether the AI output is good? What does "good" look like vs "acceptable" vs "bad"?
2. Industry conventions — are there established approaches to this problem?
   What do production systems in this domain typically do?
3. Common failure modes — what goes wrong in production for this type of AI feature?
   Hallucination, latency, cost overruns, prompt injection, context window issues?
4. Regulatory and compliance context — is there any legal, privacy, or ethical context
   that constrains how AI can be used here? (GDPR, HIPAA, content policies, etc.)
5. User expectations — what will users expect from this AI feature?
   What will cause frustration or loss of trust?
6. Success criteria — 3-5 measurable criteria that define success for this AI integration
   from a domain perspective (not just technical correctness).

Do NOT read the codebase — this is pure domain and business research.

Agent 2 — Framework & Model Selector:

Select the optimal AI framework and model for the following phase.

Phase: <phase_name>
Description: <description>
Tech stack: <tech_stack>
Acceptance criteria:
<formatted list>

Current AI integration state: <2-3 sentence brief from Step 3>

Produce a decision matrix covering:
1. Task classification — what type of AI task is this?
   (text generation, classification, extraction, RAG, agents, tool use, embeddings, etc.)
2. Model candidates — evaluate 2-4 models suitable for this task. For each:
   - Provider and model name (e.g. Anthropic claude-sonnet-4-6, OpenAI gpt-4o)
   - Strengths for this specific use case
   - Weaknesses and known limitations
   - Context window, output constraints, pricing tier
3. Framework candidates — evaluate 1-3 integration patterns:
   - Direct SDK (anthropic, openai, boto3)
   - Orchestration framework (LangChain, LlamaIndex, Haystack)
   - Agentic framework (Claude Code SDK, AutoGen, CrewAI)
   For each: integration complexity, flexibility, community support, maintenance burden
4. Recommendation — pick ONE model and ONE integration approach.
   Justify the choice in 3-5 sentences. Explain what you ruled out and why.
5. Implementation notes — key SDK usage patterns, prompt caching opportunities,
   streaming vs batch considerations, retry and error handling guidance.
   Verify current model IDs in the provider documentation before you recommend one.

Read the codebase to check for existing patterns. Quote file paths and line numbers.

Agent 3 — Eval Planner (skip if --skip-eval):

Design the evaluation strategy for the following AI phase.

Phase: <phase_name>
Description: <description>
Tech stack: <tech_stack>
Acceptance criteria:
<formatted list>

Current AI integration state: <2-3 sentence brief from Step 3>

Design:
1. Critical failure modes — list 5-8 ways this AI feature can fail silently or
   produce harmful output. Be concrete and specific to this use case.
2. Eval dimensions — for each failure mode, define a measurable rubric:
   - Dimension name
   - What it measures
   - How to measure it (LLM-as-judge prompt, regex, human review, automated test)
   - Pass/fail threshold
3. Test dataset — what examples should the eval set include?
   How many? Where will they come from? Any adversarial cases?
4. Tooling recommendation — pick one eval framework or approach:
   (pytest with LLM judge, Braintrust, LangSmith, PromptFoo, custom harness)
   Justify why it fits this phase.
5. Guardrails — what input/output guardrails are required?
   (content filtering, length limits, PII stripping, structured output validation)
   Give concrete implementation guidance with code snippets where possible.
6. Production monitoring — 3-5 metrics to track in production:
   (latency p50/p99, cost per call, error rate, user feedback, eval score drift)
   How to alert when these degrade?

Be specific — generic eval advice is useless. Tie everything to this phase's deliverable.

Collect all results (or 2 if --skip-eval).

Step 5: Write AI-SPEC.md

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from pathlib import Path
from scripts.db import connect, get_db_path
from scripts.ai_phase import write_ai_spec_md, mark_ai_complete
conn = connect(get_db_path('.'))
path = write_ai_spec_md(
    phase_dir=Path('<phase_dir>'),
    phase_name='<phase_name>',
    phase_id=<phase_id>,
    domain='''<domain_findings_verbatim>''',
    framework='''<framework_findings_verbatim>''',
    eval_strategy='''<eval_findings_verbatim_or_empty_string>''',
)
mark_ai_complete(conn, <phase_id>)
conn.close()
print(str(path))
"

Paste verbatim findings from each subagent.

Step 6: Display Summary

## AI Spec Complete: <Phase Name>

Artifact: <phase_dir>/AI-SPEC.md
Subagents: domain ✓  framework ✓  eval ✓ (or skipped)

### Model & Framework Selection

**Recommended model:** <model name>
**Integration approach:** <framework/SDK choice>
**Rationale:** <1-2 sentences>

### Top Failure Modes

<3-5 most critical failure modes with severity>

### Eval Dimensions

<rubric table: dimension | measure | threshold>

Next: /meridian:spec-phase --phase <phase_id>
  spec-phase will incorporate AI requirements into acceptance criteria.

Gate Behavior

/meridian:plan and /meridian:execute can check for AI-SPEC.md using ai_gate():

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from pathlib import Path
from scripts.ai_phase import ai_gate
result = ai_gate(Path('<phase_dir>'))
print(json.dumps(result, indent=2))
"

• passed: true → proceed normally
• passed: false → print the warning string; user can bypass with --skip-ai

This is a soft gate — it warns but does not block execution.

What Each Subagent Covers

Output Artifact Structure

.planning/phases/<slug>/
└── AI-SPEC.md          ← written by this skill
    ├── Domain & Problem Framing
    ├── Framework & Model Selection
    └── Evaluation Strategy, Guardrails & Monitoring