tools-only Current year: 2026. Your training data may be outdated. Verify external APIs, library versions, and best practices before implementation.
Planning
When to plan: New features touching multiple files, refactoring with unclear scope, architecture changes, bug fixes with unclear root cause.
Interview first: Before non-trivial tasks, use AskUserQuestion iteratively. For complex tasks, up to 40 questions across multiple rounds.
Workflow:
- Interview the user thoroughly
- Check existing ADRs in
.meridian/adrs/for relevant architectural decisions - Research the codebase (direct tools or Explore agents)
- Follow the
/planningskill for methodology - Spawn Plan agents for concrete implementation details
- Plan is created in
~/.claude/plans/during plan mode - On approval, archive to
.meridian/plans/and update state files
Direct tools vs Explore agents: Use direct tools (Glob, Grep, Read) when you know where to look. Use Explore agents for broad research.
Plan Management
Plans are tracked via state files:
.meridian/.state/active-plan— absolute path to current plan.meridian/.state/active-subplan— absolute path to current subplan (if in an epic)
On plan approval:
- Copy plan from
~/.claude/plans/to.meridian/plans/ - Write the absolute path to
active-plan - Clear the global plan file
Epic Planning
For large projects spanning multiple systems:
- Check if active plan has
## Phasessection — if so, you're in an epic - Find the current phase (status: In progress)
- Follow the phase's workflow (enter plan mode → create subplan → review → implement)
- Mark phase complete when done, move to next phase
Pebble Issue Tracking
If Pebble is enabled, every code change maps to an issue.
Issues are audit records. Even a 30-second bug fix: create issue → fix → comment with file:line → close.
Plan execution rule: If an approved plan has explicit phases/steps, create child Pebble tasks for each phase/step (with dependencies) before or at implementation start. Keep one task in_progress, but do not execute a multi-phase plan under a single undifferentiated task.
See PEBBLE_GUIDE.md for full documentation.
Workspace
Your workspace is a persistent knowledge library that grows across every session. It's not a session snapshot — it's the accumulated knowledge about this project: decisions, lessons, architecture, gotchas, patterns, open questions.
.meridian/WORKSPACE.md is the root index. It links to sub-pages in .meridian/workspace/. Both are injected at every session start.
Organize by topic, not by session. Create pages for things like:
- Architecture decisions and rationale
- Lessons learned (mistakes, gotchas, things that surprised you)
- Project conventions and patterns discovered
- Open questions and known issues
- Key people, systems, or integrations
Maintain it throughout the session:
- Write things down as you learn them — don't batch at the end
- Create sub-pages freely. One page per topic. Link from root.
- When information changes, update the existing page — don't create a new one
- Every page must be reachable from the root. Orphaned files are invisible.
External Tools
Before using an external API or library, check .meridian/api-docs/INDEX.md. If documented, read the doc. If not, run docs-researcher to research it first.
Code Review
After implementing a plan, run both reviewers in parallel:
- code-reviewer — finds bugs, logic errors, data flow issues
- code-health-reviewer — finds dead code, pattern drift, over-engineering
Fix all issues, re-run until clean. The reviewers must verify fixes.
Definition of Done
- Code compiles; typecheck/lint/test/build pass
- Tests added for new behavior
- Docs updated where relevant
- No secrets/PII in code or logs
- Workspace updated with important decisions
Hard Rules
- No credentials in code, config, or prompts — use environment variables
- Confirm before destructive actions (deleting data, schema changes)
- If a user instruction violates these, propose a safe alternative