- PreCompact hooks — Session learner and session transcript now fire on PreCompact. Session learner runs async as a checkpoint before compaction. Session transcript writes pre-compaction dialogue to
last-session.md, which context-injector picks up on SessionStart(compact) to restore conversation history after compaction. - Configurable stop checklist — New
stop_checklist_extraconfig key lets users add custom items to the quality checklist. - Configurable instruction reminders — New
instruction_remindersconfig key lets users add custom reminders injected on every message.
- Stop checklist reframed — Removed all "stopping" language. Checklist now reads as a task list ("Complete these tasks") instead of a wind-down signal ("Before stopping"). Prevents agents from deferring work.
- Context injection streamlined — Removed ceremonial header ("MUST understand before working") and footer ("Embody SOUL.md", "Confirm you understand", "Acknowledge this context"). Context is injected without requiring the agent to waste a turn parroting it back.
- Plan approval simplified — Condensed verbose archive instructions to two lines.
- Work-until loop — Removed all emojis from system messages and prompts.
- Action counter — Only resets when the checklist actually fires or on session start. No longer resets on trivial-task skip, so actions accumulate across stop attempts.
- Pebble nudge from plan-mode-tracker — Plan mode no longer injects Pebble reminders.
- Instruction reminder hook — injects a short reminder to follow CLAUDE.md instructions on every user message. Prevents instruction drift during long sessions.
- Session transcript — Removed per-entry and total output truncation. Full dialogue content is now preserved.
- Planning skill description — Optimized for triggering accuracy. Explicit "INSTEAD of EnterPlanMode" directive + methodology details (interviewing, parallel exploration, plan validation) improved eval recall from 0% to 95%.
- Audit skill references — Rewritten to use structural anti-patterns instead of naive grep patterns for more consistent detection.
- Missing noise markers — Added
<local-command-stdout>and<task-notification>toSYSTEM_NOISE_MARKERS. Session learner and session transcript were including these as real dialogue.
claude_runnershared module — Reusable Python module forclaude -psubprocess calls. Providesbuild_env(),build_args(),run(),parse_stream_json(), andload_template(). Ships in bothscripts/lib/(plugin) and.meridian/lib/(scaffolding).
- Session learner — Migrated to use
claude_runnerinstead of inline subprocess code andmeridian_configheadless helpers.
build_headless_env()/build_headless_args()frommeridian_config.py— Replaced byclaude_runner.
.meridian/.gitignore— Install artifacts (.version,.manifest,workspace/) are now gitignored by default.
- Terminal injection summary — The
systemMessageshowing injection details in the terminal was noisy and showing incorrect info. Context injection continues to work viaadditionalContext.
- Terminal injection summary — Context injector now outputs a
systemMessageshown directly in the user's terminal at session start. Shows what was injected (workspace, docs count, last session, plan, pebble, manual, soul, nested repos) and error count. Not visible to the agent.
- WORKSPACE.md scope tightened — SOUL.md and agent-operating-manual now consistently describe workspace as "slim current-state notepad." Verification in SOUL.md trimmed to one-liner deferring to manual.
- CODE_GUIDE.md moved to docs — No longer force-injected at every session. Now lives at
.meridian/docs/code-guide.mdwith frontmatter, discoverable via docs-index when task matchesread_whenhints. - Pebble context slimmed — Replaced
pb summary(4 sections, 20 closed issues) with targetedpb list --status in_progress+pb ready. Empty results produce no pebble-context tag. - Plan review hook removed — Agents follow planning skill instructions to run plan-reviewer. The blocking hook was redundant and couldn't detect if the reviewer already ran.
- Action counter simplified — Removed plan-specific action counting. General action counter preserved for stop hook threshold.
scripts/plan-review.py— ExitPlanMode blocking hook.claude/settings.json— stale daily-summary hook registrationplan_review_min_actionsconfig key- Plan action counter helpers from meridian_config.py
- Install script nuking .claude/ directories — Removed
migrate_old_installationfunction thatrm -rf'd.claude/hooks,.claude/agents,.claude/commands,.claude/skillson every update. This destroyed user-owned hooks likedaily-summary.py.
- Workspace framing consistency — Context injector, SOUL.md, and agent operating manual now all describe WORKSPACE.md as a "slim current-state notepad" instead of "persistent knowledge base" / "short-term memory." Prevents agents from re-bloating workspace content that the session learner trims.
- Stale compaction references — Removed "on compaction" from session learner firing description. It only fires at session end.
- Docs deletion path — Resolved
state_path()before injecting into prompt so the LLM agent can actually write to the docs-to-delete file. - Dead variable —
tool_countnow included in success log message. - Unused import — Removed
get_state_dirfrom session-learner imports.
- Session learner slimmed to 3 jobs — Removed the workspace-files job (preferences.md + lessons.md). Preferences belong in CLAUDE.md via the corrections job; lessons belong in domain docs via the docs job. Merged the next-steps job into the workspace job.
- Workspace scope tightened — WORKSPACE.md instructions now enforce a slim "current state notepad" — active work, key decisions, next steps only. No architecture descriptions, tech stack summaries, or implementation details.
- Context injection simplified — Stopped injecting preferences.md and lessons.md at session start. Only WORKSPACE.md is injected.
- Scaffolding templates — Removed default preferences.md and lessons.md from
.meridian/workspace/. Directory preserved via .gitkeep.
- Background subagents — 6 agent definitions now run in the background (explore, implement, code-reviewer, code-health-reviewer, docs-researcher, pebble-scaffolder).
- BrokenPipeError on session teardown — Replaced all
print(..., file=sys.stderr)with debug log file writes. Claude Code closes the stderr pipe during session teardown, causing BrokenPipeError when the hook tried to print status messages after completing work. - Session learner firing twice — Added
is_headless()guard to session-learner itself. Theclaude -psubprocess's SessionEnd was triggering a recursive session-learner run.
- Full transcript extraction — Removed all message truncation (previously 3000 chars for user/assistant, 2000 for thinking, 200 for tool inputs). Thinking blocks excluded entirely. Tool inputs passed through as-is.
- Session learner BrokenPipeError —
claude -psubprocess failures (broken pipe, OS errors) are now caught and logged instead of crashing the hook. Debug log captures stderr and last stdout lines on non-zero exit for diagnosis.
- Hooks firing in subprocesses — Added
is_headless()guard to all 7 unguarded hook scripts (stop-checklist, work-until-stop, action-counter, plan-mode-tracker, plan-approval-reminder, plan-review, reviewer-root-guard). Previously,claude -psubprocesses loaded the Meridian plugin via--setting-sources userand fired these hooks, injecting stop checklists and other noise into headless sessions. - Session learner dedup removed — Removed
was_recently_synced30-second dedup window. The lock file already prevents concurrent runs, and the dedup was silently dropping legitimate SessionEnd events.
- Session learner debug logging — Step-by-step trace to
session-learner.login the state directory, matching the daily-summary logging pattern. Covers every decision point: event check, transcript validation, extraction, prompt build,claude -pcall, and result.
- skill-creator and prompt-writing skills — General-purpose skills moved to personal skills directory (
~/.claude/skills/). They don't belong in the plugin.
- Session learner output — Output file now shows only the final summary, not intermediate narration between tool calls ("Now let me update..."). The
parse_stream_jsonfunction was collecting all text blocks from thestream-jsonoutput; now it only captures theresultentry.
extra_doc_dirsconfig: New config.yaml key to scan additional doc directories beyond.meridian/docs/and.meridian/api-docs/. Context injector and save-injected-files both support it.- Skip observability: Session learner logs early-exit reasons (wrong event, dedup, no transcript, lock held, below threshold) to JSONL via
log_skip(). - Subprocess isolation helpers:
build_headless_env()andbuild_headless_args()in meridian_config for spawning isolatedclaude -psubprocesses.
- Shared noise markers:
SYSTEM_NOISE_MARKERSandis_system_noise()extracted to meridian_config.py — session-learner and session-transcript both import from the shared source. - Session learner simplified: Dead SessionStart/compact/clear code paths removed. Only handles SessionEnd.
get_extraction_range()simplified to a single code path.run_workspace_agent()uses shared helpers. - Context injector streamlined: Removed 5-second
wait_for_session_learnersleep (waiting for a lock that never appears after SessionStart removal). UsesTRANSCRIPT_PATH_STATEconstant instead of hardcoded string.
- Session transcript surviving SessionEnd: The session learner's headless
claude -psubprocess triggered meridian hooks (installed at user scope), causingsession-cleanupto deletelast-session.mdright aftersession-transcriptwrote it. Headless sessions now setMERIDIAN_HEADLESS=1and all hook scripts exit immediately when this is detected.
- Session transcript cleanup:
last-session.mdnow deleted on/clearand compact, not just fresh startup.
- Simplified SessionStart hooks: Merged duplicate matcher entries into one. Session learner removed from SessionStart (runs at SessionEnd only). Hooks skip
resumeevents to avoid re-injecting context into resumed sessions. - Cleaned up session-cleanup: Removed redundant SessionEnd registration and dead code branches (
COMPACT_DELETE,SESSION_END_DELETE).
- Session transcript: Extracts user/assistant dialogue (no thinking, tool calls, or system noise) at session end and injects it at next session start. 30KB cap with recency bias. Shared constants and startup cleanup for stale transcripts.
- Stop checklist: Now prompts to update all relevant documentation (docs, workspace) instead of just CLAUDE.md.
- Plugin architecture: Meridian is now a Claude Code plugin. Hooks, agents, skills, and commands are discovered automatically by the plugin system — no more copying files into
.claude/. - Install flow: Two-command update:
meridian-updatefor.meridian/scaffolding,/plugin update meridian@markmdevfor hooks/agents/skills. - Utility scripts moved:
state-dir.sh,setup-work-until.sh, andlearner-log.pymoved from.claude/hooks/scripts/to.meridian/scripts/for stable agent-accessible paths. - Hook commands: All hook commands now use
${CLAUDE_PLUGIN_ROOT}/scripts/instead of$CLAUDE_PROJECT_DIR/.claude/hooks/.
- Plugin manifest:
.claude-plugin/plugin.jsonfor plugin system registration. - hooks.json:
hooks/hooks.jsonreplaces.claude/settings.jsonfor hook registration. - Migration support: Install script detects pre-plugin Meridian and cleans up old
.claude/files automatically. - Marketplace listing: Available via
/plugin marketplace add markmdev/claude-pluginsthen/plugin install meridian@markmdev.
.claude/directory: No longer ships with.claude/settings.json,.claude/hooks/,.claude/agents/,.claude/commands/, or.claude/skills/. All managed by the plugin system.- settings.json merge logic: The 70-line merge script in
install.shis gone — plugin system handles hook registration.
required-context-files.yaml: Unused feature removed along withparse_yaml_list()and all references.- Config flags: Removed
plan_review_enabled,code_review_enabled,pebble_scaffolder_enabled— all were always-on. Pebble scaffolder now triggers onpebble_enabledalone.
stop_hook_min_actionsdefault: Code defaults now match shipped config value of 15 (was 10 in code).
- Standardized workspace files:
.meridian/workspace/preferences.mdand.meridian/workspace/lessons.mdmaintained by session learner.
- Refactor and test-writer agents: The implement agent handles both tasks. Two fewer agents to maintain.
- Plan-file-sync hook: Extra complexity and point of failure. The agent manages plan files directly.
- CLAUDE.md writer skill: Session learner already handles CLAUDE.md updates.
- Context acknowledgment gate hook: Removed in favor of lighter-weight context injection.
- Permission auto-approver hook: Removed — Claude Code's built-in permission handling is sufficient.
- Subplan/epic planning system: Removed
active-subplanstate, epic phase workflow, and subplan references from all hooks, skills, and docs. Plans are simple now — no hierarchy.
- Session learner observability: JSONL history log (
session-learner.jsonl) with tool usage, timing, git diffs, and 50-entry rotation. Uses--output-format stream-jsonto parse what tools the learner agent used and which files it changed. - Session learner log viewer:
python .claude/hooks/scripts/learner-log.pydisplays formatted table of recent learner runs with status, duration, tool count, and file changes. - State directory helper:
.claude/hooks/scripts/state-dir.shresolves~/.meridian/state/<hash>/so agents and scripts can find state files. - Docs index for subagents:
save-injected-files.pywrites adocs-indexstate file listing all.meridian/docs/and.meridian/api-docs/entries with summaries, so subagents can discover available documentation.
- Reviewer agents return plain text: Code-reviewer, code-health-reviewer, and architect no longer create Pebble issues. They return findings as structured text — the main agent handles issue tracking.
- Docs skill renamed:
docs→create-docsto better reflect its purpose (creating.meridian/docs/knowledge files). - Injected PRs filtered to author:
gh pr listcommands in context injector now use--author @meinstead of showing everyone's PRs. - Session learner redesigned: Workspace as short-term memory, strict next steps, git context injection.
- Plan mode hook: Demands immediate skill activation on plan mode entry.
- Stale
.meridian/.statereferences: 22 references across 15 files still pointed to the old state path (moved in v0.4.0). Agents couldn't findinjected-files, andsetup-work-until.shwroteloop-stateto the wrong location. All references now usestate-dir.shhelper or compute paths at runtime viastate_path().
- Simplified context acknowledgment gate: No longer prescribes a specific format or checklist. The agent simply acknowledges what it sees in the injected context.
- Worktree setup guide in README: Documents how to symlink
.meridian/across git worktrees using the new external state directory.
- State directory moved to
~/.meridian/state/<hash>/: Ephemeral session state (counters, flags, locks) no longer lives inside.meridian/.state/. State is now stored per-working-directory in the user's home directory. This enables symlinking the entire.meridian/folder across git worktrees without sharing session state. Each worktree gets isolated state automatically via path hashing. - Hooks lib renamed:
config.py→meridian_config.pyto avoid name collisions with Python's built-inconfigmodule.
- Nested git repository context: The context injector now scans for nested
.gitdirectories (up to 3 levels deep) and injects their recent commits and current branch. Useful for workspaces containing multiple sub-projects. - Frontmatter enforcement in session learner: Job 1 (workspace pages) and Job 4 (docs) now require YAML frontmatter (
summary+read_when) on every.mdfile. Files without frontmatter are flagged as invisible to context routers. Existing files missing frontmatter get it added.
- add-frontmatter skill: Scans all .md files and adds/fixes YAML frontmatter (summary + read_when) for Reflex discovery.
- skill-creator skill: Guide for creating effective skills with progressive disclosure, bundled resources, and packaging.
- Session learner assistant mode: New
session_learner_mode: assistantconfig option. When enabled, the session learner can create, update, and delete files anywhere in the project (following existing directory conventions) instead of being restricted to.meridian/docs/and.meridian/workspace/. Designed for personal knowledge bases and AI assistant workspaces where the agent maintains daily logs, people files, research artifacts, etc.
- PEBBLE_GUIDE.md eliminated: 360-line guide no longer injected into agent sessions. Behavioral rules moved to agent operating manual (8 rules + work loop). CLI is self-documenting via improved
--helpoutput with examples. Net: ~360 fewer lines of injected context per session. - CODE_GUIDE addons: Merged hackathon and production addons into a single unified CODE_GUIDE.md.
- ADRs system: Empty directory removed. Decisions live in
.meridian/docs/now. - meridian-path-guard hook: Caused friction in dev environments. Removed from settings.json.
- save-context command: Superseded by session learner.
- meridian-wrapper: No longer needed.
- Pebble-scaffolder agent rewritten: Embeds commands reference directly instead of reading PEBBLE_GUIDE.md. Only creates issues — doesn't reference claim/close/comment workflows.
- Code-reviewer agent rewritten: Returns findings to main agent instead of writing files. Streamlined output format.
- Docs-researcher agent rewritten: Firecrawl-first with WebSearch/WebFetch fallback.
- Agent operating manual: Expanded Pebble section with 8 numbered rules, work loop example, and
pb --helpreference.
/docsskill: User-invoked skill for documenting codebase modules. Agent explores a module and produces.meridian/docs/files with frontmatter.- Session learner doc awareness:
scan_project_frontmatter()scans all frontmatter'd.mdfiles (3 levels deep). Session learner can now update any frontmatter'd doc.
- plan-approval-reminder.py:
sys.exit(1)→sys.exit(0)on JSON decode error; removed dead code. - permission-auto-approver.py: Bare
return→sys.exit(0)for consistency. - save-injected-files.py: Added missing
get_project_configimport (latent bug). - config.py: Removed stale "verification counts" from
get_pebble_context()docstring.
- Mandatory verification before handoff: SOUL.md, agent operating manual, and stop hook all require the agent to prove its work before stopping — run it, call it, load it. "It should work" is not accepted. New "Verification" section in operating manual with examples per work type.
- Required reading in workspace: Session learner now maintains a
## Required readingsection in WORKSPACE.md listing.meridian/docs/files the next agent must read before starting work.
- Session learner maintains docs/ fully: Job 4 now covers create, update, and delete. Agent marks outdated docs for deletion by writing paths to
.meridian/.state/docs-to-delete; Python deletes them after the agent finishes.
- Orphaned workspace page cleanup: After each session learner run, workspace pages not linked from
WORKSPACE.mdare automatically deleted. Keeps.meridian/workspace/from accumulating stale pages.
adrs/INDEX.mdandapi-docs/INDEX.md: These files were already skipped by the frontmatter scanner (since v0.1.0) and served no purpose.
/ux-states-auditskill: Audits UI for missing loading, empty, and error states. Finds components that handle the happy path but leave other states blank. Implements missing states using the app's existing patterns./observability-auditskill: Audits code for observability gaps — debug logs left in, errors caught without being logged, missing context, untracked critical operations. Research-first: uses whatever observability tooling already exists in the app.
/error-auditupdated: Now explicitly covers the UI layer — data fetches that swallow errors and render blank, error boundaries that catch but show nothing, async operations with no error state in the UI.
/error-auditskill: Audits code for silent error swallowing, fallbacks to degraded alternatives, backwards compatibility shims, and required config with default values. Fixes all occurrences and reports what changed.- Error handling rules in operating manual: New "Error Handling" section — no silent swallowing, no silent fallbacks, no backwards compat shims, no default values for required config.
- Session learner creates docs: Session learner agent (Job 4) now creates docs in
.meridian/docs/with propersummary+read_whenfrontmatter for significant knowledge from the session — architectural decisions, integrations, debugging discoveries, gotchas.
- Session learner prompt saved for inspection: The full prompt sent to the session learner agent (transcript entries, workspace, CLAUDE.md contents) is now saved to
.meridian/.state/session-learner-prompt.mdon each run, alongside the existing output file.
- Dead file tree code:
_build_file_tree(), constants, helpers, andfile_tree_max_files_per_dir/file_tree_ignored_extensionsconfig options. File tree was removed from context in v0.1.4 but ~117 lines of code remained.
- Pre-compaction warning hook:
token-limit-warning.pydeleted. Session learner now handles workspace updates, CLAUDE.md learning, and next steps automatically after compaction — making the manual pre-compaction save redundant. auto_compact_offconfig option: Depended on the pre-compaction hook to trigger. Removed from config.yaml and config.py.pre_compaction_sync_enabled/pre_compaction_sync_thresholdconfig options: No longer needed.
- Removed file tree from injected context: Was noisy and token-heavy. Agent can explore the codebase with tools when needed.
- Stronger docs guidance: Docs reminder now tells the agent to update docs when making changes to documented topics and create new docs for decisions and gotchas. Documentation is part of the work, not an afterthought.
- Next steps in workspace: Session learner now maintains a "Next steps" section at the bottom of WORKSPACE.md after each compaction/clear — 2-5 actionable items so the next agent knows what to work on.
- Setup guide expanded: CLAUDE.md snippet now includes workflow guidance (stop and re-plan when things break, use subagents liberally, staff engineer self-check) and autonomous bug fixing (write reproducing test first, then fix without hand-holding).
- Docs "read when" reminder: After the docs index listing, a reminder tells the agent to read relevant docs before coding when the task matches a hint, and to keep docs current.
- Descriptive plan names: Plan files are renamed from random slugs (e.g.
linked-beaming-crayon.md) to descriptive kebab-case names (e.g.add-user-auth.md) when archived after approval. - Setup guide:
.meridian/SETUP_GUIDE.mdwith a CLAUDE.md snippet users can copy to enable proactive documentation — the agent creates docs in.meridian/docs/for decisions, learnings, and features without being asked.
- Frontmatter-based docs injection: ADRs, API docs, and the new
.meridian/docs/directory are now scanned for YAML frontmatter (summary,read_when) instead of injecting INDEX.md files. Agent sees a compact listing of what each doc covers and when to read it. Full docs are read on demand.
.meridian/docs/directory: General-purpose docs folder for agent-created documentation. Automatically scanned and injected like ADRs and API docs.extract_frontmatter()andscan_docs_directory(): New utilities in config.py for parsing doc frontmatter.
- Session learner double-fire on /clear: Added timestamp-based dedup — session learner skips if it already ran within 30 seconds, preventing duplicate processing when
/clearfires both SessionEnd and SessionStart.
- Workspace sync race condition: Fixed parallel hook timing where context injector checked for the session learner lock before it was created. Session learner now acquires the lock immediately on compact/clear (before transcript validation), and context injector waits up to 5 seconds for the lock to appear. Previously the lock was acquired late, so context injector saw no lock and injected the old workspace.
- Workspace injected before session learner finishes: Context injector now waits for the session learner lock to release on compact/clear before injecting workspace. Previously hooks ran in parallel, so the old workspace was injected before the session learner could update it.
- Session learner output saved:
claude -pagent output now saved to.meridian/.state/session-learner-output.mdfor inspection.
- Hook logs no longer cleared: Removed
clear_hook_logs()from session-cleanup. Hook logs persist across sessions — each hook overwrites its own file naturally, so no accumulation.
- Hook logs now markdown: Hook output logs in
.meridian/.state/hook_logs/are now.mdfiles with readable metadata (timestamp, event, decision) and content rendered as markdown instead of raw JSON.
- File tree default:
file_tree_max_files_per_dirdefault increased from 40 to 2000. - Stop hook threshold:
stop_hook_min_actionsdefault changed from 10 to 15.
reset-token-warning.py: Merged intosession-cleanup.py. Was a standalone hook that only deleted one flag file.
- Dead
CLEAR_DELETEcode path:session-cleanup.pynow registered forSessionStart:compact|clearevents. Previously only ran onstartupandSessionEnd, making the clear/compact cleanup lists unreachable (audit finding #1).
- Hook file renames for clarity: 7 hooks renamed to better reflect their purpose:
claude-init.py→context-injector.py— injects project context at session startpost-compact-guard.py→context-acknowledgment-gate.py— blocks until agent reads contextpre-stop-update.py→stop-checklist.py— pre-stop checks (review, tests, commits)pre-compaction-sync.py→token-limit-warning.py— warns near compaction thresholdclear-precompaction-flag.py→reset-token-warning.py— resets token warning flaginjected-files-log.py→save-injected-files.py— saves injected file list to stateworkspace-sync.py→session-learner.py— updates workspace and learns from corrections
- Session learner: Now uses Opus 4.6 (was Sonnet) and learns from user corrections by updating
~/.claude/CLAUDE.md(global) or<project>/CLAUDE.md(project-specific). When the user corrects the agent's behavior, the correction is saved as a permanent instruction.
- Hook output logging: All hooks now log their output to
.meridian/.state/hook_logs/{hook-name}.jsonfor debugging and inspection. Newlog_hook_output()helper inconfig.pyreplaces directprint(json.dumps())calls. Logs are cleared on session start and/clear.
- JSONDecodeError exit codes:
work-until-stop.py,pre-stop-update.py,plan-review.py, andpost-compact-guard.pynow exit with code 0 (silent) instead of code 1 (error) on JSON parse failure, consistent with all other hooks. - Missing event validation:
plan-file-sync.pyandpermission-auto-approver.pynow validatehook_event_namebefore processing, consistent with other hooks. - Install preserves plans:
.meridian/plans/and.meridian/subplans/added toSTATE_PATTERNSandis_state_file()ininstall.sh, preventing loss of archived plans on update. - Config merge operator precedence: Fixed Python ternary precedence bug in
install.shconfig merge script that prevented version comments from being written correctly. - Dev CLAUDE.md stale references: Removed references to deleted features (task-manager skill, task-backlog, .mcp.json, implementation reviewer, browser verifier, periodic reminders, MCP servers). Renamed Beads to Pebble. Updated config table and architecture diagram. Added code-health-reviewer to review agents section.
- PermissionRequest hook format:
meridian-path-guard.pynow uses the correct PermissionRequest output format (hookSpecificOutput.decision.behavior) instead of Stop hook format. Previously may have silently failed to block invalid paths. - UserPromptSubmit hook format:
plan-mode-tracker.pynow uses JSONadditionalContextinstead of rawprint("<system-message>"). Previously context may have been silently dropped. required-context-files.yamlpreserved on update: Added toSTATE_PATTERNSarray ininstall.shto matchis_state_file()behavior.- Pebble fallback in agents:
architect.mdandcode-health-reviewer.mdno longer unconditionally assume Pebble is enabled. They check availability first. - Error message path:
reviewer-root-guard.pynow shows correct path.meridian/.state/injected-files. - Docstring accuracy:
pre-stop-update.pyno longer references deleted memory feature.
- Dead hook file:
plan-tracker.py— not registered insettings.json, never fired. - Dead code in
config.py: Removed 11 unused functions (read_file,get_required_files,parse_yaml_dict, 3 worktree helpers,get_action_counter, 4 pending-reads functions), 2 unused constants (PENDING_READS_DIR,RESTART_SIGNAL), and 2 unused parameters onbuild_injected_context. - Dead config: Removed
claudemd_ignored_folders(commented out, no implementation) fromconfig.yaml. - Dead state reference: Removed
code-reviewer-activefromsession-cleanup.pycleanup lists (no hook creates this file). - Dead YAML sections: Removed unused
coreandproject_type_addonssections fromrequired-context-files.yaml(injection is hardcoded inbuild_injected_context). - Stale migration: Removed
session-context.md→WORKSPACE.mdmigration code frominstall.sh. - Stale reference: Removed
.mcp.jsonfrom setup command in project CLAUDE.md. - Duplicate banner: Merged two
companyAnnouncementsentries into one insettings.json. - Build artifacts: Removed
.DS_Storeand__pycache__files from distribution.
- File tree config documented:
file_tree_max_files_per_dir(default: 40) andfile_tree_ignored_extensionsnow documented inconfig.yaml.
- Workspace sync agent: Dedicated headless
claude -psession that updates the workspace automatically by analyzing the session transcript. Fires synchronously on compaction and/clear(before context injection), and on session end. Extracts user messages, assistant text/thinking, and tool calls (without results) since the last compaction boundary. Runs with--setting-sources "user"to avoid loading project hooks. - Transcript path persistence:
claude-init.pysaves the transcript path to.meridian/.state/transcript-pathso the workspace sync agent can find the old transcript after/clear(which creates a new transcript file).
- Planning skill: Non-Goals section: Plans now require a
Non-Goalssection that explicitly fences scope to prevent implementation drift. - Planning skill: Current State section: Plans document what exists today — relevant files, data flows, constraints — before proposing changes.
- Planning skill: Self-Review checklist: Four verification items before finalizing: existing controls integration, state invariants, transaction boundaries, and verification executability.
- Workspace maintenance is automatic: Removed workspace update reminders from stop hook and pre-compaction hook. SOUL.md updated to reflect that a dedicated agent handles workspace maintenance.
- PR listings show authors: Open and merged PRs in injected context now display the author's username. Open PRs show
#123 Title (author) [branch], merged PRs show#123 Title (author) merged 2 days ago. - Injected files have descriptions: Each file injected at session start now has a bold description above it explaining its purpose and how the agent should treat it (e.g., "Agent operating manual. This is authoritative — follow these procedures at all times.").
- Injected context saved to state:
claude-init.pywrites the built context to.meridian/.state/injected-contextfor debugging and inspection. - Pebble plan decomposition rule: Plans with explicit phases/steps must be decomposed into Pebble child tasks before implementation starts.
agent-operating-manual.md: Removed standalone file. Content is covered by SOUL.md, planning skill, and other injected context.
- Install script preserves ADR directory:
.meridian/adrs/is now preserved on update, preventing loss of Architecture Decision Records.
- Workspace reframed as persistent knowledge library: Workspace is no longer described as "session state" or "current state." It's a growing library of project knowledge — decisions, lessons, architecture, gotchas — that accumulates across sessions. Updated SOUL.md, agent-operating-manual, stop hook, and pre-compaction hook.
- Merged
session-reload.pyintoclaude-init.py: Both hooks were identical. Now a singleclaude-init.pyhandles all SessionStart events (startup, compaction, clear). Deletedsession-reload.py. - Docs-researcher uses generic web research: Agent no longer references Firecrawl specifically. Uses "relevant MCPs or skills if available" for web research.
- Simplified agent tool lists: Removed hardcoded MCP tool references from
plan-reviewer.md,code-reviewer.md, anddocs-researcher.md. Agents use whatever tools are available in their environment. - External Tools rule softened: Operating manual no longer marks it as "STRICT RULE". Still recommends checking
api-docs/INDEX.mdbefore using external APIs.
.mcp.json: Removed bundled MCP server configuration (Context7, DeepWiki, Firecrawl). Users configure their own MCP servers as needed.docs-researcher-tracker.py: Removed PostToolUse hook that tracked docs-researcher spawning.docs-researcher-stop.py: Removed SubagentStop hook that blocked docs-researcher from stopping without writing files.block-task-output.py: Removed PreToolUse hook that blocked TaskOutput tool.docs_researcher_write_requiredconfig option: Removed fromconfig.yamlandconfig.py.DOCS_RESEARCHER_FLAGconstant: Removed fromconfig.py.SubagentStophook section: Removed fromsettings.json(no remaining SubagentStop hooks).- MCP references from README: Removed MCP Servers section, Context7/DeepWiki/Firecrawl documentation, and related FAQ.
trim_workspacefunction: Removed workspace trimming. Workspace grows without limit — agent reorganizes into sub-pages instead of losing old knowledge.workspace_max_linesconfig option: Removed fromconfig.yamlandconfig.py.
- Project file tree at session start: Context injection now includes a compact TOON-style file tree of the entire project. Uses Python
os.walkinstead oftreecommand — no external dependency. Excludes common noise directories (node_modules, .git, pycache, dist, build, target, vendor, etc.).
- Injection order: SOUL.md and WORKSPACE.md moved to bottom: Both files are now injected last (before work-until loop state), placing them closest to the agent's working context for highest attention. Previous order had them near the top.
- Planning skill: plan review and TLDR sections: Plans now include a Plan Review step (run plan-reviewer, score 9+ to proceed) and end with a TLDR — 2-4 sentences summarizing the plan.
- SOUL.md: ask for what you need: Agents ask the user for tools, access, or resources instead of silently falling back to worse approaches.
- SOUL.md: end-to-end verification: Agents verify their own work by exercising it — hitting endpoints, creating test users, running flows with real data. Build passing is not verification.
- Workspace guidance strengthened: Emphasizes writing things down early and often, creating pages per topic, not batching updates at the end.
- Workspace system: Replaces
session-context.mdwith a living knowledge base. Agent maintains.meridian/WORKSPACE.mdas a root file linking to sub-pages in.meridian/workspace/. Based on the "15-minute rule" — anything not written down is gone in 15 minutes.
- Work-until loop state injected at session start: Active loop is now surfaced in context injection so the agent knows it's in a loop after compaction or
/clear. - Stop hook mentions both reviewers: Checklist now says to run
code-reviewerandcode-health-reviewerin parallel. - SOUL.md: Continuity section rewritten around workspace and the 15-minute rule.
- Agent-operating-manual: Session Context section replaced with Workspace section. Encourages proactive note-taking, page creation, and graph-style linking.
- Stop hook: Prompts to update workspace instead of session-context.
- Pre-compaction hook: Prompts to update workspace instead of session-context.
- Context injection: Injects
WORKSPACE.mdinstead ofsession-context.md. - install.sh: Preserves
WORKSPACE.mdandworkspace/on update. Migratessession-context.mdtoWORKSPACE.mdfor upgrades from older versions. - config.yaml:
session_context_max_linesrenamed toworkspace_max_lines(default: 500).
- session-context.md: Replaced by workspace system. All references removed from hooks, agents, commands, config, and docs.
- worktree-context.md: Removed worktree context system. Deleted file,
WORKTREE_CONTEXT_FILEconstant,get_worktree_context_path(),trim_worktree_context(),worktree_context_max_linesconfig option, and all references from hooks, install.sh, and README.
- Planning skill: interviewing emphasis: Interviewing is now framed as the most important part of planning. Every unasked question is an assumption that breaks during implementation. Each round of answers should trigger deeper follow-ups.
- Planning skill: unlimited exploration agents: Explicitly overrides the 3-agent concurrency default. Spawn 5, 10, 15 agents simultaneously — no limit. Aggressive follow-up rounds expected (2-4 rounds before ready to plan).
- Opus 4.6 simplification pass: Stripped ~1,850 lines of enforcement harnesses that compensated for earlier model limitations. Opus 4.6 is smarter — trust it more, enforce less.
- Planning skill (193→83 lines): Kept interview loop, deep exploration, no-TBD rule, verification. Removed Execution Table, agent count table, ASCII diagram templates, PRD criteria.
- Agent-operating-manual (253→84 lines): Removed obvious engineering guidance (CI failures, dependency management, verification judgment). Kept plan management, Pebble, External Tools rule, DoD, Hard Rules.
- CODE_GUIDE.md (138→56 lines): Removed Naming, Comments, Constants, Security, Functions sections. Kept Type Safety, Error Handling, Code Org, Breaking Changes, Logging, Testing, Frontend/Backend.
- Agent prompts trimmed: explore (129→42), refactor (183→36), test-writer (171→36), implement (151→54). Code-reviewer stays as-is (forcing functions are valuable).
- Post-compact guard simplified: Lighter acknowledgment prompt, concise instead of numbered list.
- Permission auto-approver rewritten: Removed dead memory-related code paths that would have crashed at runtime.
- README.md cleaned: Removed ~20 stale references to deleted features.
- install.sh cleaned: Removed memory.jsonl from preserved state files.
- Memory system: Deleted
memory.jsonl,memory-curatorskill (SKILL.md + 3 scripts). Removed all references from hooks, agents, config, and docs. Session context is sufficient for cross-session continuity. - Periodic reminder hook: Deleted
periodic-reminder.py. Removed from all 4 settings.json event matchers, config.yaml, and session-cleanup.py. - Edits-since-review counter: Removed tracking from action-counter.py, stop prompt, and config.py helpers.
- SOUL.md for agent identity: New
.meridian/SOUL.mddefines who the agent is — a craftsman with opinions, not a chatbot waiting to be told what to do. Covers core truths, working style, communication principles, and what agents can do without asking. Inspired by OpenClaw's workspace bootstrap approach.
- Simplified hook prompts: Hooks are now triggers, not re-training sessions. Pre-compaction and stop prompts reduced from ~150 lines to ~35 lines each. The agent knows HOW from SOUL.md — hooks just remind WHEN.
- Stripped agent-operating-manual: Removed identity/personality content now in SOUL.md. Manual focuses purely on Meridian procedures: planning workflows, Pebble tracking, code review cycles.
- Removed context file headers: session-context.md and worktree-context.md are now just entries — no instructional headers. Agent knows how to use them from SOUL.md.
- ADR injection reduced: Only injects ADR index, not all individual ADRs. Agent reads specific ADRs when needed during planning.
- ADR template: Agent knows how to write ADRs without a template file.
- Current Focus section in session-context: New persistent section at the top of session-context.md that maintains high-level work context ("Working on: Auth system", "Phase: OAuth integration"). Gets UPDATED (not appended) when major work shifts. Prevents agents from losing macro-level context after several sessions.
- Stop hook prompts about Current Focus: Now reminds agent to update the Current Focus section when major work changes.
- Pre-compaction hook prompts about Current Focus: Same guidance added to pre-compaction context saving.
- Git log now shows user's commits only: Filters to
--author={user_email}so you see your commits, not everyone's. - Git log shows all branches: Added
--allflag to show commits across all branches. - Git log shows branch decoration: Branch names shown at branch tips (e.g.,
(main),(feature-branch)). - Git log shows relative timestamps: Each commit shows "2 hours ago", "3 days ago", etc.
- Onboarding system: Removed
/onboard-userand/onboard-projectskills, profile injection, and related prompts. Simplified the system. - Plan agent blocking: Plan agents are now allowed and encouraged during planning. Removed
block-plan-agent.pyhook andplan_agent_redirect_enabledconfig option.
- Plan mode messages: Now encourage using Plan agents for concrete implementation details alongside the
/planningskill.
- pebble-scaffolder now uses Opus: Changed from Sonnet to Opus for better quality issue creation.
- code-health-reviewer has Quality Bar: Added threshold to prevent diminishing returns on repeated passes. Only creates issues with concrete maintainability impact.
- Context injection now includes PRs: Shows last 5 open PRs and last 5 merged PRs via
gh pr list.
- git log increased to 20 commits: Was 5, now 20 for better context.
- meridian-wrapper moved to .meridian/bin/: Wrapper is now at
.meridian/bin/meridian-wrapperinstead ofbin/. Uses script location to find project root.
- Root guard now includes implement, refactor, test-writer: These agents read
injected-filesand must be spawned from project root to work correctly.
- implement and test-writer agents now use Opus: Changed from Sonnet to Opus for better quality implementation and test generation.
- TaskOutput block message: Instead of telling agent to "sleep briefly in a loop", now instructs to stop and wait for notification. Background agents notify on completion automatically.
- Install script now copies bin/ directory: The
meridian-wrapperscript is now properly distributed viainstall.sh.
- Auto-restart wrapper (
bin/meridian-wrapper): Bash script that runs Claude in a loop. Whenauto_compact_off: trueand context fills up, agent writes to.meridian/.state/restart-signaland stops. Wrapper detects the signal and restarts Claude with the prompt from the signal file (default: "continue"). Eliminates manual/clearstep.
- Pre-compaction hook for auto-restart: When
auto_compact_off: true, hook now instructs agent to write restart signal file and stop, instead of telling user to run/clear.
- Agents now actually read injected files: Replaced vague "read all files listed there" with explicit numbered procedure in all 7 agents. Now says: "1. Read injected-files, 2. For EACH file path listed, read that file, 3. Only proceed after reading ALL". Agents were reading the index file but not the files inside it.
- diff-summarizer agent: Removed — not useful in practice.
- ASCII diagrams in plans: Planning skill now requires ASCII diagrams for UI mocks (with edge cases), data flow, and architecture. Clearer than prose descriptions.
- ASCII diagrams in communication: Agent-operating-manual now encourages using ASCII diagrams when explaining visual concepts to users.
- Architect dual mode: Architect can now review proposed plans (not just existing code). Plan review mode evaluates architectural soundness before implementation.
- Condensed review agent prompts: Both
architectandcode-health-reviewernow use declarative "use your judgment" style instead of verbose checklists. Trusts the model's expertise. - Architect during planning: Added guidance in agent-operating-manual to run architect for plans with architectural implications (new modules, boundary changes, major refactors).
- Architect agent exploration: Added "Explore First" section requiring the agent to understand codebase patterns before critiquing architecture. Finds similar modules, identifies established patterns, maps architecture.
- Review agents read-only: Removed Write tool from
architectandcode-health-revieweragents. They now only create Pebble issues via CLI, no file writing fallback.
- architect agent: Reviews codebase architecture for structural issues — module boundary violations, dependency direction, layer violations, abstraction inconsistency, API drift, circular dependencies. Creates Pebble issues with recommendations. Use during planning or after large changes.
- ADR system: Architecture Decision Records in
.meridian/adrs/. Captures architectural decisions with context, rationale, and consequences. Injected at session start alongside memory. Main agent writes ADRs after decisions are made (not the architect — architect advises, team decides).
- Planning workflow: Added step to check existing ADRs before researching codebase.
- Context injection: ADRs directory now injected at session start (INDEX.md + all ADR files except TEMPLATE.md).
- reviewer-root-guard: Added
architectandcode-health-reviewerto the list of agents that must be spawned from project root. - Exploration encouragement: Strengthened language in planning skill and agent-operating-manual to encourage spawning many Explore agents (5-15 for complex tasks, 10-20 for major refactors). Includes concrete examples and frames shallow exploration as causing brittle plans.
- Planning skill condensed: Reduced from 409 to 163 lines (60% reduction). Removed templates the model already knows, redundant checklists, verbose examples. Preserved load-bearing content: verbatim requirements, core loop, exploration numbers, handoff test, no-TBD rule, execution table.
- code-health-reviewer agent: New agent that finds dead code, bloat, duplication, pattern drift, and over-engineering. Use after large tasks, end of feature work, or when code has gone through many iterations. Sets its own quality standard (doesn't learn from potentially degraded existing code). Explores codebase to find reusable utilities. Scopes to recent commits + one level out.
- Dual reviewer workflow: Stop hook and agent-operating-manual now instruct to run both code-reviewer (bugs, logic) and code-health-reviewer (maintainability) in parallel after completing work.
- Reading injected-files is now mandatory for agents: Added "NEVER skip reading context" as the FIRST critical rule in all 5 agents (implement, code-reviewer, plan-reviewer, test-writer, refactor). Previously it was just a workflow step that agents could skip.
- TaskOutput blocking actually works now: The hook was using
toolName(camelCase) instead oftool_name(snake_case), so it wasn't blocking anything.
- Parallel code review workflow in stop hook: Stop hook now instructs to run code-reviewer in background, group issues by file, and spawn implement agents in parallel (1 file = 1 agent). Matches the guidance in agent-operating-manual.
- Active plan paths always in injected-files: State file paths for
active-planandactive-subplanare now always included ininjected-files, even if no plan exists at session start. Subagents can now see plans approved mid-session.
- Plan review findings must be addressed: Even when plan-reviewer returns score 9+, the agent must address ALL findings before exiting plan mode. Present each finding to the user, either update the plan or get user confirmation to skip (mark as
[USER_DECLINED]). No need to re-run reviewer if score was already 9+. - New "Plan Review Findings" section in agent-operating-manual: Documents the workflow for handling plan-reviewer findings regardless of score.
- TaskOutput blocked: Hook prevents using TaskOutput tool. Background agents notify on completion automatically — no need to poll.
- Parallel plan execution: Plans now include an "Execution Table" mapping each step to an agent (implement/refactor/test-writer/main) and parallel group. Main agent delegates to specialized agents and spawns parallel groups simultaneously.
- Parallel code review fixes: Code review section updated — run code-reviewer in background, group issues by file, spawn implement agents in parallel (1 file = 1 agent).
- injected-files for agents: implement, refactor, and test-writer agents now read
.meridian/.state/injected-filesto get the same project context as the main agent.
- CodeRabbit parallel workflow: Updated coderabbit-task.md with parallel fix pattern — group comments by file, spawn implement agents in parallel.
- cd boilerplate: Removed
cd "$CLAUDE_PROJECT_DIR"from 6 agents (code-reviewer, implement, diff-summarizer, refactor, test-writer, plan-reviewer). Agents are always spawned from project root.
- Code review is an explicit loop: Agent operating manual now shows numbered steps: run reviewer → fix ALL issues → run reviewer AGAIN → repeat until 0 issues. Emphasizes "do not assume fixes are correct — reviewer must verify."
- Fix ALL code review issues: Added explicit instruction to fix p0, p1, AND p2 issues — no exceptions. Agents were skipping p2 "suggestions."
- Epic planning requires workflow section: Planning skill now instructs agents to copy a required workflow template into every epic plan. The template shows the 9-step per-phase workflow (mark in progress → plan mode → subplan → plan-reviewer → approval → move to subplans/ → implement → code-reviewer → mark complete).
- Epic plans contain everything: Clarified that verbatim requirements and all findings go in the epic plan. Subplans are for detailed implementation focus, not to replace discovery.
- Periodic reminder interval: Default increased from 10 to 20 actions. Reduces noise while maintaining focus.
- Periodic reminder format: Uses
<system_reminder>XML tags instead of[REMINDER]:prefix.
- Plan file sync timing: Moved from UserPromptSubmit to PreToolUse. The user message (containing the slug) isn't written to transcript until after UserPromptSubmit fires, so the hook couldn't find the new slug after
/clear.
- Planning skill reframed: Shifted from checkbox mentality to "handoff test" — could someone implement this plan without asking questions? Added "Finding Gaps" section with simulation technique. Lists are now "starting points, not completeness criteria." Added "entry point context" to flow specifics.
- Context injection deduplication: Files are now deduplicated by resolved path. If
active-planandactive-subplanpoint to the same file, it's only injected once.
- Planning skill reminder on EnterPlanMode: When agent uses
EnterPlanModetool, context is injected reminding to invoke/planningskill.
- Code reviewer parent context: Now explicitly requires
Parent task: <task-id>(not the epic) in the prompt. Issues from code review belong to the task being reviewed, even if closed. - Stop hook code review prompt: Now instructs main agent to pass the specific task ID, not the epic. Includes
pb list --parent <epic-id>hint.
/save-contextcommand: Manual trigger to save context before/clearor/compact. Prompts agent to update session-context, memory, Pebble issues, and worktree context.
- PRD sections in planning: For complex work (new projects, unclear scope, multi-phase), plans can include PRD sections (Vision, Problem Statement, User Stories, Feature Spec, MVP Scope) before implementation details. Agent asks user whether to include PRD sections when criteria detected.
- EnterPlanMode tracking: Plan mode state now updates immediately when agent uses
EnterPlanModetool, not just on next user message. - Utility agents guidance: Agent operating manual now documents when to use non-enforced agents (explore, docs-researcher, test-writer, refactor, implement, diff-summarizer).
- Pebble scaffolder for subplans: Instructions now explicitly cover three scenarios: epic plans (scope=epic), subplans (scope=task with parent=phase ID), and standalone tasks. Prevents "epic already exists" confusion when planning phases.
- Plan file sync overwrite: When slug changes after /clear, always overwrite the new plan file with old content. Previously skipped if new file had stale content from previous sessions.
- Commit nudge: Stop hook, periodic reminder, and pre-compaction hook now show uncommitted file count and nudge to commit for smaller, logical commits.
- Plan archival preserves original: No longer clears the global plan file after copying to project folder.
- Simplified code-reviewer counter: Reset happens on spawn (PreToolUse) instead of completion (SubagentStop). Removed
code-reviewer-stop.pyhook.
- Memory edit counter: Removed
edits-since-memorytracking — added no value over the existing memory prompt.
- Plan file sync on /clear: New
plan-file-sync.pyhook tracks the current plan file by reading slug from transcript. When user clears and Claude Code assigns a new slug, the hook copies plan content to the new file automatically. current-plan-autostate file: Tracks the Claude Code plan file path (~/.claude/plans/[slug].md), separate fromactive-planwhich tracks archived plans.
- Plan archival uses
cpcommand: Plan approval instructions now tell Claude to use bashcpinstead of manual read/write for copying plans to.meridian/plans/.
- Agent descriptions improved: Updated frontmatter descriptions for diff-summarizer, docs-researcher, implement, explore, refactor, and test-writer to explain WHEN to use each agent, helping the main agent discover and invoke them appropriately.
- Datetime in stop/pre-compaction prompts: Both hooks now include current timestamp so agents know when context entries were written.
- Recent commits in context: Session start now injects
git log --oneline -5alongside datetime and uncommitted changes.
- PLAN STATE prompt: Now only shows when actually in plan mode (plan-mode-state = "plan"), not when an active plan file exists.
- Active plan state files: Instructions now specify that
active-planandactive-subplanstate files must contain absolute paths, not relative paths.
- Four new utility agents:
test-writer— Generates comprehensive tests for files/functions. Detects testing framework, learns patterns from existing tests, runs tests after generation.refactor— Mechanical refactors (rename, extract, move) with semantic symbol search. Handles imports/exports, verifies with typecheck/tests.diff-summarizer— Generates PR descriptions from branch changes. Reads git diff and commits, follows project PR template if present.implement— Executes detailed implementation specs autonomously. Spawn multiple in parallel for independent tasks. Reports ambiguity instead of asking questions (non-blocking).
- Auto-compact off mode: New
auto_compact_offconfig option. When enabled, agent saves context at pre-compaction then STOPS. User manually runs/clearfor cleaner session resets. - Epic planning system: Planning skill now detects large multi-phase projects and proposes epic planning with subplans for each phase.
- Plan management system: Plans are copied to
.meridian/plans/(or.meridian/subplans/) on approval. State files track active plan/subplan. - Context injection improvements: Session start now includes current datetime and
git diff --statfor uncommitted changes. - Nested Pebble hierarchy example: PEBBLE_GUIDE.md now shows Epic → Phases → Tasks → Verifications structure.
- Planning skill improvements:
- Acceptance criteria per step — what "done" looks like
- Test cases for behavioral changes — input → output examples
- Verification section at end of plan with review checkpoints for large plans (5+ phases)
- No literal code — describe structure, not copy-paste snippets
- Anti-patterns section — repetition, obvious details, micro-steps
- Session context philosophy: Changed from "append journal" to "living document with current state". Update existing entries for same task/phase instead of appending duplicates. Skip task tables (use Pebble), obvious reasoning.
- Pre-compaction hook: Writes to
.meridian/or.claude/paths now bypass blocking (these ARE the context-saving actions). - Plan approval reminder: Now includes instructions to archive plans to project folder.
- feature-writer agent: Deprecated in favor of acceptance criteria built into planning skill.
- feature-writer-check.py hook: No longer needed.
- plan-tracker.py hook: Disabled to not conflict with new plan management (file still exists but removed from settings.json).
- New state files:
active-subplan - Stop hooks bypass all checks when
auto_compact_off: trueandPRE_COMPACTION_FLAGexists - Removed
feature_writer_enforcement_enabledconfig option
/clearnow behaves like auto-compact: Changed SessionStart hook matchers so/cleartriggers the same hooks ascompact. State (action-counter, plan-mode-state, etc.) is now preserved instead of reset. Users can disable auto-compact and use/clearmanually for cleaner context without CC's file duplication.
- implementation-reviewer agent: Deleted — agent follows plans anyway, reviewer added no value
- browser-verifier agent: Deleted — never used in practice
- thinking-guide.md: Replaced by
/thinkcommand
- Edit tracking for code review: Tracks file edits since last code review. Counter shown in stop prompt so agent can't claim "this was a small bug fix" after hundreds of edits. Resets when code-reviewer completes.
- Edit tracking for memory: Tracks file edits since last memory update. Prevents dismissing memory entries with "nothing significant happened" after substantial work.
- CodeRabbit workflow guidance: New "Responding to Review Feedback" section in agent-operating-manual — reply inline to comments, don't defer valid issues as "out of scope", create Pebble issues for findings.
- Verification judgment guidance: Agent-operating-manual now instructs to scale verification to the change — don't run full test/lint/typecheck suite after trivial single-line fixes.
- code-reviewer-stop.py: New SubagentStop hook that resets edit-since-review counter when code-reviewer completes.
/thinkcommand: New command for explicit thinking mode. User invokes/think [LINES] [TOPIC]to start structured thinking. Replaces auto-injected thinking-guide.md.
- Planning skill completely rewritten: Removed rigid numbered phases (0-9) that caused "7-phase 500-line" plans regardless of task complexity. New philosophy: "Plans are documentation of understanding, not templates." Core loop: ASK → EXPLORE → LEARN → MORE QUESTIONS? → REPEAT. Spawn as many agents as needed. Run follow-up explorations when findings raise questions. Required specifics: data, flow, decisions, existing patterns to reuse.
- pebble-scaffolder: Now supports flexible scopes (epic, task, bug, follow-up) instead of always creating epic hierarchies. Main agent passes scope hint based on work size.
- plan-approval-reminder: Updated guidance to tell main agent to assess scope and pass appropriate hint (epic/task/bug/follow-up) to pebble-scaffolder.
- docs-researcher: Now installs npm packages to temp folder for inspection (
mktemp -d && npm install) instead of assuming they're already in node_modules. - code-reviewer: Output folder changed from
implementation-reviews/tocode-reviews/. - Stop prompt: Now shows edit counts for both code review and memory sections.
- New state files:
edits-since-review,edits-since-memory,code-reviewer-active - Memory scripts (
add_memory_entry.py,edit_memory_entry.py) now reset memory counter on update - Removed
implementation_review_enabledconfig option - Cleaned up all implementation-reviewer and browser-verifier references from: config.py, README.md, agent-operating-manual.md, reviewer-root-guard.py, work-until-stop.py, pre-stop-update.py
- Pre-compaction hook: Now prompts to save plan state FIRST (before Pebble, before session context) when in plan mode or with active plan. Instructs agent to capture verbatim requirements — all user messages and AskUserQuestion exchanges without paraphrasing.
- Planning skill: Strengthened Verbatim Requirements section with explicit "DO NOT paraphrase. DO NOT compress. DO NOT summarize." and changed from capturing "important" follow-up context to capturing ALL follow-up context. Section header now includes "WRITE THIS FIRST".
- reviewer-root-guard: Now enforces project root for
docs-researcheragent (same as plan-reviewer, code-reviewer, etc.). Blocks spawning from subdirectories with clear error message.
- Pre-compaction sync hook: Fixed token counting that always returned 0. The hook was reading the last line of the transcript, which is often a "progress" entry (hook execution log) without usage data. Now searches backwards through the transcript to find the most recent entry with
message.usagedata.
- Planning skill: Plans now require explicit "Read first:" sections listing doc paths for each step. External API docs and project docs must be referenced by file path so the implementation agent knows exactly what to read before coding.
- plan-action-counter: Simplified lightweight plan detection. Renamed
plan-action-starttoplan-action-counter. Now increments directly while in plan mode instead of snapshot-and-diff approach. Clearer logic, same behavior. - Context acknowledgment: Now includes
api-docs/INDEX.mdwhen present, reminding agent to read doc files before using listed APIs. - injected-files: Added
api-docs/INDEX.mdso reviewer agents also know which APIs are documented.
- plan-action-start cleanup: Removed redundant
clear_plan_action_startcalls fromplan-review.py. Now only cleared inplan-approval-reminder.pyafter user approves the plan, ensuring action count is preserved if user rejects and continues planning.
- State file cleanup regression: Fixed v0.0.27 regression where session-cleanup.py was nuking the entire
.meridian/.state/directory on startup. Now uses per-file deletion with explicit lists for each event type (startup, clear, SessionEnd). Files likeactive-planandloop-stateare now correctly preserved across all events.
- PEBBLE_GUIDE.md rewritten: Comprehensive documentation improvements based on real agent feedback:
- New Quick Reference organized by workflow (what to work on, epic overview, issue details)
- New Epic Management section documenting
pb summary,pb dep tree,pb list --parent - New Finding Issues section documenting
pb searchandpb blocked -v - Verification workflow expanded: verify immediately, what to do when blocked
- Dependencies section now shows self-documenting
--blocked-by/--blocksflags on create - All features already existed — agents just didn't know about them
- Pebble CLI developer spec (
docs/pebble-cli-dev-spec.md): Implementation spec for 4 CLI improvements (remove --json warning, verification status hint,pb dep add --needs/--blocks,pb ready --type) - Pebble improvements spec (
docs/pebble-improvements-spec.md): Analysis of agent feedback, what exists vs what needs building
- Onboarding interview system: Two new skills that capture context through conversation instead of manual documentation:
/onboard-user— Learns user preferences, communication style, autonomy levels, quality standards. Saves to~/.claude/meridian/user-profile.yaml(global, applies to all projects)./onboard-project— Learns project context, criticality, security requirements, priorities. Saves to.meridian/project-profile.yaml(per-project).- Interviews are comprehensive but adaptive — irrelevant questions are skipped based on previous answers.
- Post-compaction hook prompts agent to offer onboarding when profiles are missing.
- Thinking process: New workflow for complex problems and post-compaction re-orientation:
- Short prompt (
.meridian/prompts/thinking-guide.md) injected at session start. - Guides agent to write iterative thoughts to
.meridian/.scratch/thinking-*.mdbefore acting. - Freeform exploration — no structure, no pressure, messy is fine.
- Planning skill now has Pre-Phase Thinking for complex tasks.
- Short prompt (
- Context injection expanded: User and project profiles are now injected at session start (when they exist).
- New:
.claude/skills/onboard-user/SKILL.md,.claude/skills/onboard-project/SKILL.md,.meridian/prompts/thinking-guide.md - New helpers in
lib/config.py:get_user_profile_path(),get_project_profile_path(),user_profile_exists(),project_profile_exists(),get_onboarding_status() - Updated:
config.py(profile injection, thinking guide injection),post-compact-guard.py(onboarding prompts),planning/SKILL.md(Pre-Phase Thinking)
- Worktree context preservation: Install script now preserves
worktree-context.mdentries on update, only refreshing the header (same behavior assession-context.md).
- Timestamp format: Context entries now use
YYYY-MM-DD HH:MMformat (added time to worktree context).
- PEBBLE_GUIDE:
pending_verificationstatus — auto-set when closing issues with open verifications. Enforces that verification actually happens before full closure. - PEBBLE_GUIDE:
pb dep relate/unrelate— bidirectional non-blocking links for issues that share context without blocking each other.
- Worktree context entry format: Entries should start with what task/epic was being worked on, then explain what was done, issues found, and current state.
- Stale state file paths: Fixed references to
.meridian/.loop-stateand.meridian/.active-planin prompts and README — now correctly point to.meridian/.state/directory.
/prompt-writingskill: General-purpose prompt writing skill for any AI system. Covers removing redundancy, removing noise, sharpening instructions, and keeping load-bearing content.- Deferral prohibition in planning: Planning skill now explicitly prohibits deferrals ("TBD", "needs investigation", "figure out later"). All investigation must happen during planning, not implementation.
- Deferral detection in plan-reviewer: New Phase 6 detects and flags deferred investigation as critical findings.
- State directory consolidation: All ephemeral hook state files now live in
.meridian/.state/for cleaner organization. - Worktree context sharing: New
worktree-context.mdin main worktree for sharing high-level context across git worktrees. Stop and pre-compaction hooks prompt for standup-style updates. Auto-trims toworktree_context_max_lines(default: 200). - docs-researcher flag tracking: New PostToolUse hook (
docs-researcher-tracker.py) creates flag when docs-researcher spawns. SubagentStop hook checks flag for reliable agent detection. - install.sh settings.json merge: Fresh installs now merge user's existing hooks with Meridian's hooks instead of overwriting.
- Session cleanup simplified: Now deletes entire
.meridian/.state/directory on startup instead of individual files. - claudemd-writer skill: Fixed missing YAML frontmatter (name, description fields).
- memory-curator skill: Cleaned up — removed wrapper tags, excessive dividers, consolidated Field Guidelines section. 143 → 110 lines.
- Worktree context guidance: Stop and pre-compaction hooks now use standup-style guidance (2-3 sentences, what was worked on and achieved, no technical implementation details).
- Removed pre-compaction-sync.log: No longer logs token calculations to file.
- New:
.claude/skills/prompt-writing/SKILL.md,.claude/hooks/docs-researcher-tracker.py,.meridian/worktree-context.md - New constants in
config.py:STATE_DIR,DOCS_RESEARCHER_FLAG, worktree detection functions (get_main_worktree_path(),is_main_worktree(),get_worktree_name()),trim_worktree_context() - Migrated all flag paths to use
STATE_DIR:PENDING_READS_DIR,PRE_COMPACTION_FLAG,PLAN_REVIEW_FLAG,CONTEXT_ACK_FLAG,ACTION_COUNTER_FILE,REMINDER_COUNTER_FILE,PLAN_ACTION_START_FILE,PLAN_MODE_STATE,ACTIVE_PLAN_FILE,INJECTED_FILES_LOG,LOOP_STATE_FILE - Updated: All hooks referencing state files, all agent files referencing
.injected-files,.gitignore
- Lightweight plan detection: Skip plan-reviewer and feature-writer enforcement when fewer than
plan_review_min_actions(default: 20) actions occurred since entering plan mode. Quick plans skip heavyweight review. /coderabbit-reviewcommand: Wrapper for/work-untilthat handles CodeRabbit AI review cycles. Automatically addresses Critical, Major, Minor, and Out-of-diff comments; skips Nitpicks.- Skip-if-unchanged guidance: Stop hook now tells agent to skip re-running implementation/code reviewers if no significant code changes since last run.
- Four new config options:
code_review_enabled— Control code reviewer separately from implementation reviewer (default: true)docs_researcher_write_required— Block docs-researcher if it didn't write to api-docs (default: true)pebble_scaffolder_enabled— Control auto-scaffolding after plan approval (default: true)plan_agent_redirect_enabled— Control Plan agent → planning skill redirect (default: true)
- Work-until command refactored: Extracted loop instructions to shared
.meridian/prompts/work-until-loop.md. Both/work-untiland/coderabbit-reviewuse the same file, reducing duplication. - Removed legacy sprint_active detection: Cleaned unused code from
post-compact-guard.pythat referenced removed/pb-sprintcommands.
- New:
.claude/commands/coderabbit-review.md,.meridian/prompts/work-until-loop.md,.meridian/prompts/coderabbit-task.md - New config helpers in
lib/config.py:save_plan_action_start(),get_plan_action_count(),clear_plan_action_start() - Updated:
config.py,plan-mode-tracker.py,plan-review.py,feature-writer-check.py,plan-approval-reminder.py,docs-researcher-stop.py,block-plan-agent.py,post-compact-guard.py,session-cleanup.py,work-until.md,config.yaml
- docs-researcher SubagentStop hook: Blocks docs-researcher agent from stopping if it hasn't used the Write tool. Ensures API documentation is actually written to
.meridian/api-docs/. - Pebble context injection: Session start now injects
pb summary --pretty(active epics) andpb history --type create,close --pretty(recent activity) when Pebble is enabled. Provides immediate visibility into project state. - feature-writer enforcement hook: Optional PreToolUse hook blocks ExitPlanMode if plan is missing verification features (
<!-- VERIFICATION_FEATURES -->marker). Enable viafeature_writer_enforcement_enabled: truein config.yaml (default: false). - Verification issues with
--verifiesflag: New Pebble relationship type for verification issues. Verification issues target the task they verify rather than being children. Ready behavior: verification appears inpb readyonly after its target closes.
- Plan-review-blocked flag timing: Flag now clears after plan approval (in PostToolUse), not on second ExitPlanMode attempt. Prevents premature flag clearing.
- Pebble Scaffolder path fix: Added to reviewer-root-guard.py so it reads PEBBLE_GUIDE.md from correct location.
- "Fix something → check Epic" guidance: Agent operating manual now instructs to check relevant Epic/backlog when fixing bugs or making improvements discovered during work.
- Session-context.md header: Now explicitly states "DO NOT read this file" since it's already injected at session start.
- install.sh header update: Installer now updates session-context.md header while preserving user entries (uses
<!-- SESSION ENTRIES STARTmarker). - Verification issue guidance: Agent operating manual and PEBBLE_GUIDE.md now explain: if verification can't be performed, don't close — add a comment explaining what's blocking verification.
- PEBBLE_GUIDE.md verification section: Complete rewrite explaining
--verifiesflag, ready behavior, and evidence requirements. - pebble-scaffolder agent: Updated to use
--verifiesflag for verification issues instead of parent-child relationship.
- New:
docs-researcher-stop.pySubagentStop hook,feature-writer-check.pyPreToolUse hook - New config option:
feature_writer_enforcement_enabled(default: false) - Updated:
config.py(get_pebble_context, stop prompt),plan-review.py,plan-approval-reminder.py,reviewer-root-guard.py,settings.json,agent-operating-manual.md,PEBBLE_GUIDE.md,pebble-scaffolder.md,feature-writer.md,code-reviewer.md,implementation-reviewer.md,install.sh,session-context.md
- install.sh: One-line installer and updater. Supports version pinning (
-v X.X.X), preserves state files on update (memory, session-context, api-docs, config), merges new config options automatically. - pebble-scaffolder agent: Creates Pebble issue hierarchy (epic, tasks, verification subtasks) from approved plans. Reads PEBBLE_GUIDE.md for rules, parses plan phases and verification features, creates all issues with proper parent-child relationships and dependencies. Invoked automatically after plan approval when Pebble is enabled.
- feature-writer agent: Generates 5-20 verification features per plan phase. Features are testable acceptance criteria with concrete steps. Supports any verification type (UI, API, CLI, Library, Config/Infra, Data).
- plan-approval-reminder hook: Now instructs main agent to invoke pebble-scaffolder instead of manually creating issues.
- PEBBLE_GUIDE.md: Added verification subtasks section explaining how to verify and close with evidence.
- agent-operating-manual.md: Compacted from 447 to 145 lines (68% reduction) following prompt-writing-guide principles.
- CODE_GUIDE.md: Expanded Type Safety section (35 lines) emphasizing compiler strictness, no
any, library type reuse. Variable section sizes instead of artificial uniformity. - CODE_GUIDE_ADDON_PRODUCTION.md: Reorganized by concern (Security, Reliability, Data, Observability, Build & Deploy). Removed Strengthen/Add labels.
- task-backlog system: Removed in favor of Pebble for task tracking. Removed task-backlog.yaml injection, startup-prune-completed-tasks.py hook, and related code.
- docs-researcher agent: New Opus-powered agent that researches external tools, APIs, and products using Firecrawl. Builds comprehensive knowledge docs in
.meridian/api-docs/covering current versions, API operations, rate limits, best practices, and gotchas. - Firecrawl MCP server: Added to
.mcp.jsonfor web scraping capabilities. All reviewer agents now have access to Firecrawl tools. - API docs system: New
.meridian/api-docs/directory with INDEX.md. Injected at session start so agents know which external tools are documented. - External API documentation requirement: Strict new rule — no code using external APIs unless documented in api-docs. Agent operating manual has full workflow for checking INDEX.md and running docs-researcher.
- Renamed Beads to Pebble: Issue tracker renamed from "Beads" to "Pebble" throughout. Commands changed from
bdtopb. All hooks, agents, guides updated. - Planning skill external API phase: New mandatory Phase 4 (External API Documentation) before decomposition. All external libraries must be documented via docs-researcher before implementation begins.
- Planning skill follow-up section: New guidance for appending bug fixes/improvements to existing plan files rather than overwriting.
- Periodic reminder simplified: Now prints text directly instead of JSON-wrapped output. Added reminder about api-docs and docs-researcher.
- Work-until command safety: Added check to ensure command runs from project root directory.
- New:
docs-researcher.mdagent,.meridian/api-docs/INDEX.md - Updated:
.mcp.json,planning/SKILL.md,agent-operating-manual.md,config.py,periodic-reminder.py,work-until.md, all agents referencing Beads→Pebble
- Explore agent: New Opus-powered agent for deep codebase exploration. Use when you don't know where to start, need broad research across many files, or context window is filling up. Returns comprehensive findings with file paths, line numbers, code snippets. Read-only — cannot modify files.
- Pebble audit trail enforcement: Stop hook and pre-compaction-sync now emphasize that already-fixed bugs still need issues ("The fix happened, but the record didn't"). Pebble section moved before session context (higher priority). Renamed to "PEBBLE (AUDIT TRAIL)" to reinforce purpose.
- Implementation-focused pebble language: Changed "future improvements" and "ideas worth tracking" to "bugs found, broken code, missing error handling, problems that need attention" — language that matches what agents encounter during implementation.
- Condensed prompts (preserving behavior):
- Planning skill: 445 → 150 lines (66% reduction). Two interview phases (business requirements before discovery, technical after). Professional judgment to push back on suboptimal suggestions. No artificial plan size limits.
- CLAUDE.md writer skill: 292 → 89 lines (70% reduction)
- Reviewer agents: 1,204 → 454 lines total (62% reduction). All workflow steps, quality criteria, and orphan issue prevention preserved.
- Explore vs direct tools guidance: Updated agent-operating-manual and planning skill with decision table for when to use Explore agents vs direct tools (Glob, Grep, Read).
- New:
explore.mdagent - Updated:
planning/SKILL.md,claudemd-writer/SKILL.md,plan-reviewer.md,implementation-reviewer.md,code-reviewer.md,browser-verifier.md,agent-operating-manual.md,PEBBLE_GUIDE.md,config.py,pre-compaction-sync.py,periodic-reminder.py
- Human documentation emphasis: Planning skill and plan-reviewer now treat human-facing documentation as equally important to CLAUDE.md. Phases adding user-visible functionality REQUIRE human docs (README, API docs, etc.), not just agent docs.
- Plan mode tracker clarity: Now explicitly tells users to "Send /planning in the chat" when plan mode activates.
- Plan-reviewer doc checks expanded: New red flag for phases that add user-visible features without README/user doc updates.
- Updated:
plan-reviewer.md,plan-mode-tracker.py,planning/SKILL.md
- Periodic reminder system: Injects short reminder about key behaviors every N actions (tool calls + user messages). Configurable via
reminder_intervalin config.yaml (default: 10). Resets on session start. Non-blocking — usesadditionalContext. - Important user messages in session-context: Session context now captures important user instructions, preferences, and constraints that should persist across sessions. Agent can copy user prompts verbatim if needed.
- Research Before Implementation: New section in agent-operating-manual.md with mandatory research steps and exploration mindset. Emphasizes searching before assuming something doesn't exist.
- Reviewer agents prevent orphaned issues: Implementation reviewer, code reviewer, and browser verifier now include guidance to check existing issues, connect to parent work, use
discovered-fromdependencies, and set proper blockers. Every issue should have at least one connection. - Planning skill research emphasis: Added "Before Planning to Create Anything New" subsection — search for existing API endpoints, utilities, components before proposing new ones.
- Action counter reset timing: Counter now resets when stop hooks fire (not on every user message). Prevents counter drift when user interrupts mid-work.
- Session context separator detection: Fixed to use
SESSION ENTRIES STARTmarker instead of---.
- New:
periodic-reminder.pyhook,REMINDER_COUNTER_FILEconstant in config.py - Updated:
session-context.mdheader,agent-operating-manual.md,config.py(stop hook, separator detection),action-counter.py,pre-stop-update.py,implementation-reviewer.md,code-reviewer.md,browser-verifier.md,planning/SKILL.md
- CLAUDE.md section in stop hook: Prompts agent to create/update CLAUDE.md when creating new modules or making significant architectural changes.
- Work-until requires reviewers: Before outputting completion phrase, agent MUST run Implementation Reviewer and Code Reviewer. Loop continues until reviewers return 0 issues.
- Stop hook improvements:
- Implementation review: Clarified trigger ("after finishing a plan, epic, or large multi-file task") and added
cd $PROJECT_DIRinstruction - Memory section: Rewritten to explain the critical test clearly, references
/memory-curatorskill - Pebble section: Expanded with explicit guidance (close, create, update, comment) — removed PEBBLE_GUIDE.md reference (already in context)
- Implementation review: Clarified trigger ("after finishing a plan, epic, or large multi-file task") and added
- Reviewer agents navigate to project root: All reviewers (implementation, code, plan, browser) now
cd "$CLAUDE_PROJECT_DIR"as Step/Phase 0 before reading.injected-files. - Injected files use absolute paths:
.meridian/.injected-filesnow contains absolute paths instead of relative paths. - claudemd-writer skill: Emphasizes "Commands first" — setup/test commands should be at the top of CLAUDE.md files. Removed hard line limits (50/100), replaced with "every line competes for Claude's attention". Added precedence note.
/pb-sprintand/pb-sprint-stopcommands: Superseded by/work-untilwhich provides stop-hook enforcement. The pb-sprint workflow template lacked enforcement mechanism.
- Deleted:
pb-sprint.md,pb-sprint-stop.md,pb-sprint-init.py,pb-sprint-stop.py,.claude/scripts/directory - Updated:
config.py,work-until-stop.py,injected-files-log.py,implementation-reviewer.md,code-reviewer.md,plan-reviewer.md,browser-verifier.md,claudemd-writer/SKILL.md,README.md
- Work-until loop (
/work-until): Iterative task completion loop that keeps Claude working until a condition is met./work-until TASK --completion-phrase "PHRASE"— loops until<complete>PHRASE</complete>is output (must be TRUE)--max-iterations N— auto-stop after N iterations- Task prompt is resent each iteration; session-context preserves history
- Normal stop hook checks (memory, session context, tests) run between iterations
- Session context rules: Header now explicitly states to add entries at BOTTOM and re-read fully if partial read was done.
- Stop hook refactored: Extracted prompt building to shared
build_stop_prompt()helper inlib/config.py. Reduced from 337 to 81 lines. - CLAUDE.md section removed: Stop hook no longer prompts for CLAUDE.md review (now handled in plans).
- Reviewer agents: Added "Critical Rules" section — NEVER read partial files, Step 0 is MANDATORY.
- New
work-until-stop.pyStop hook for loop control - New
.claude/commands/work-until.mdslash command - New
.claude/hooks/scripts/setup-work-until.shsetup script - New loop helpers in
lib/config.py:is_loop_active(),get_loop_state(),update_loop_iteration(),clear_loop_state(),build_stop_prompt() - Added
.loop-stateto.gitignore
- Injected files log: New hook logs all injected context files to
.meridian/.injected-fileson session start/compact/clear. Includespebble_enabledandgit_comparisonsettings. - Self-loading reviewer agents: Implementation Reviewer, Code Reviewer, and Browser Verifier now auto-load context from
.injected-files— no prompts needed.
- Stop hook simplified: No longer requires manual prompts for reviewers. Just says "spawn Implementation Reviewer agent" and "Code Reviewer agent".
- Reviewer agents have Step 0: All three reviewer agents now read
.meridian/.injected-filesas first step to get plan, settings, and context files.
- New
injected-files-log.pySessionStart hook - Updated:
implementation-reviewer.md,code-reviewer.md,browser-verifier.md,pre-stop-update.py - Added
.injected-filesto.gitignore
- Plan tracker hook: Automatically tracks active plan by watching Edit/Write/Read operations on
.claude/plans/files. Saves to.meridian/.active-planfor injection after compaction. - Pebble workflow improvements:
- One task at a time: Only ONE issue should be
in_progressat any moment. Must transition current issue (block/defer/close) before claiming another. - Discovered work pattern: Full pattern for handling blockers vs deferrable work discovered during implementation.
- Comment before closing: Must add comment with file paths and implementation details before closing any issue. Prevents false closures.
- One task at a time: Only ONE issue should be
- Pattern consistency rules: New guidance requiring agents to read full files and follow established patterns (factory functions, naming, error handling, logging).
- Full file reads required: Agents must NEVER use offset/limit to read partial files. Partial reads miss context and lead to inconsistent code.
- Implementation reviewer: Now checks for pattern consistency violations (e.g., direct instantiation when factory exists).
- Plan injection for Pebble: Plans now inject after compaction for Pebble workflows via
.active-planfile (previously only worked with task-backlog.yaml).
- New
plan-tracker.pyPostToolUse hook for Edit|Write|Read matcher - Updated
config.pyto inject from.meridian/.active-plan - Added
.active-planto.gitignore - Updated:
agent-operating-manual.md,CODE_GUIDE.md,implementation-reviewer.md,PEBBLE_GUIDE.md
- PEBBLE_GUIDE.md: Comprehensive Pebble reference guide for agents. Single source of truth for commands, dependency types, and best practices. Injected at session start when Pebble is enabled.
- Pebble guidance centralized: All hooks/prompts now reference
PEBBLE_GUIDE.mdinstead of duplicating command examples. Reduces maintenance burden and ensures consistency. - Dependency types clarified: Only
blocksaffectspb ready. Parent-child, related, and discovered-from are informational only — this was a common source of confusion. - Ready Front model: Guide teaches "Ready Front" thinking instead of "phases". Walk backward from goal to create correct dependencies.
- Cognitive trap documented: Explicit warning about temporal language ("A before B") inverting dependencies. Use requirement language ("B needs A").
- PM-style descriptions: Expanded guidance on writing comprehensive issue descriptions with Purpose/Why This Matters/Requirements/Acceptance Criteria/Context sections.
--parentflag: Corrected from--deps parent:<id>to--parent <id>throughout.
- Removed 150+ line
PEBBLE_PROMPTfromlib/config.py, now injectsPEBBLE_GUIDE.mdfile directly - Updated:
plan-approval-reminder.py,pre-stop-update.py,pre-compaction-sync.py,code-reviewer.md,implementation-reviewer.md,pb-sprint-init.py,pb-sprint.md,config.yaml
- Browser verifier agent (experimental): Manual QA agent using Claude for Chrome MCP. Verifies implementations by actually using the application in a browser — tests user flows, checks visual appearance, creates issues for failures.
- Action counter for stop hook: Stop hook skips if fewer than
stop_hook_min_actions(default: 10) tool calls since last user input. Prevents hook from firing on trivial interactions. - Interview depth guidance: Planning skill now explicitly allows up to 40 questions across multiple rounds for complex tasks.
- Documentation planning phase: Planning skill now has mandatory Phase 4.5 requiring explicit CLAUDE.md and human documentation steps for each implementation phase.
- Documentation verification in plan reviewer: Plan reviewer now checks that every phase has documentation steps (Phase 3.5).
- Trust plan claims: Plan reviewer no longer rejects plans claiming packages/versions/models "don't exist" — user may have access to private/internal/beta resources.
- Memory context in plan reviewer: Plan reviewer now reads
memory.jsonlin Phase 1 for domain knowledge before analyzing plans.
- Code reviewer rewritten (CodeRabbit-style): Complete rewrite with 8-phase deep analysis workflow — Load Context, Change Summary, Deep Research, Walkthrough (forcing function), Sequence Diagrams (forcing function), Find Issues, Create Issues, Cleanup. Reviews now include detailed walkthroughs and sequence diagrams to ensure deep understanding.
- Implementation reviewer simplified: Replaced multi-type reviewers (phase/integration/completeness) with single checklist-based approach. Extract every item from plan → verify each individually → create issues for incomplete items.
- Issue-based review system: Both reviewers now output issues instead of scores. No more 1-10 scoring — just issues or no issues. Loop until all issues resolved.
- Pebble integration in reviewers: When
pebble_enabled: true, reviewers create Pebble issues directly instead of writing to files. - Direct tools over Explore agents: Planning skill now instructs to use Glob/Grep/Read directly for codebase research. Explore agents only for answering direct conceptual questions.
- Stop hook section reorder: Sections now ordered by priority (lower in prompt = higher priority): Implementation Review → Memory → Session Context → CLAUDE.md → Pebble → Human Actions → Tests/Lint/Build (highest priority).
- Stop hook text condensed: More concise instructions while preserving key information.
- Pre-compaction sync improved: Better guidance on what survives compaction (concrete decisions, file paths, error messages) vs what doesn't (vague summaries, implicit context).
- Pre-compaction Pebble instructions: When Pebble enabled, prompts agent to create issues for findings discovered during session.
- Agent operating manual simplified: Removed redundant Requirements Interview section (~90 lines), replaced with reference to planning skill Phase 0.
- New
ACTION_COUNTER_FILEconstant andstop_hook_min_actionsconfig option in.claude/hooks/lib/config.py - New
action-counter.pyhook tracks tool calls, resets on UserPromptSubmit - Reviewers pass
pebble_enabledflag to control output mode - Plan reviewer has new "documentation" finding category
- Plan approval reminder (Pebble mode): Now instructs to create ALL sub-tasks upfront (not just first phase), add dependencies BETWEEN sub-tasks within each phase, and write comprehensive PM-style descriptions with Purpose/Requirements/Acceptance Criteria sections. Previously, agents would only create Phase 1 sub-tasks, skip inter-subtask dependencies, and write terse technical descriptions.
/pb-sprintautonomous workflow: New slash command starts a comprehensive workflow for completing Pebble work (epics, issues with dependencies, any scoped work). Appends workflow template tosession-context.mdthat survives context compaction./pb-sprint-stop: Removes the workflow section when sprint is complete.- Sprint workflow detection: Acknowledgment hook detects active sprint workflow and prompts agent to resume from where it left off.
- Auto-approve for plans: Write/Edit to paths containing
.claude/plans/now auto-approved. - Auto-approve for Pebble CLI: All
pbcommands now auto-approved.
- Planning mandatory in sprint: Workflow template now explicitly requires planning for every issue — "No exceptions — even if the issue is 'detailed' or 'simple'".
- Session context marker clarified: Changed from
<!-- Session entries below this line... -->to<!-- SESSION ENTRIES START - Add timestamped entries below, oldest at top -->. - Reviewer streaming warning: Added prominent warning about context pollution when listening to reviewer agent streaming output.
- Session-context.md added to reviewer files: Reviewers now read session context for additional context.
- Slash commands use Python scripts (not bash heredocs) because
$CLAUDE_PROJECT_DIRunavailable in slash command context. - Scripts derive project root from
__file__path and print template so agent sees it immediately. - Workflow section goes at bottom of session-context.md; regular entries go above it.
- Rolling session context file: New
.meridian/session-context.mdreplaces per-task context files. Always injected at session start regardless of task status. Agent saves key decisions, discoveries, and context that would be hard to rediscover. - Automatic context trimming: When session context exceeds
session_context_max_lines(default: 1000), oldest entries are trimmed while preserving the header. - CLAUDE.md decision criteria in stop hook: Stop hook now shows when to create/update CLAUDE.md (new module, public API change, new patterns) vs when to skip (bug fixes, refactoring, internal details).
- Timestamped session entries: Session context entries now use
YYYY-MM-DD HH:MMformat instead of just dates.
- Simplified context injection: Removed per-task context file injection and task file tracking. Session context is always available, even without a formal task.
- Stop hook updated: Now prompts to update
session-context.mdinstead ofTASK-###-context.md. - Pre-compaction sync updated: Now prompts to save to
session-context.mdbefore compaction. - Agent operating manual updated: New "Session Context" section explains how to use the rolling context file.
- Plan approval reminder rewritten: Now explicitly lists all 3 required steps (create task folder, copy plan, add backlog entry) with exact YAML format. Previously agent would only copy the plan and skip the backlog entry.
- Memory curator stricter criteria: New critical test: "If I delete this entry, will the agent make the same mistake again — or is the fix already in the code?" Explicit SHOULD/SHOULD NOT lists. One-time bug fixes, SDK quirks, and agent behavior rules no longer belong in memory.
- Stop hook memory guidance updated: Reflects stricter memory criteria — add patterns affecting future features, don't add one-time fixes.
- Pebble prompt improvements: Added
pb statsfor project health,pb close <id1> <id2> ...for closing multiple issues, and explicit priority format note (use 0-4 or P0-P4, NOT "high"/"medium"/"low"). - Pebble reminders in hooks: When Pebble is enabled, reminders appear in context acknowledgment (check project state), stop hook (update issues), and plan mode tracker (use Pebble to track work).
- Task file tracker hook:
task-file-tracker.pyremoved — no longer needed with rolling session context. - Per-task context file injection: Task context files (
TASK-###-context.md) are no longer auto-injected. Task folders still exist for plans/docs. sibling_reposconfig: Removed unused configuration option that was never implemented.
- Pebble integration: Optional Git-backed issue tracker for AI agents. When
pebble_enabled: truein config.yaml, agents receive comprehensive instructions for using Pebble to manage work: understanding project state (pb ready,pb list,pb blocked), creating well-researched issues, managing dependencies, using molecules (epics with execution intent) and gates (quality checkpoints). Agents are instructed to proactively suggest creating issues during conversations.
- Context injection order: Reordered for better context flow — task backlog now appears before task context files; Pebble prompt (when enabled) appears before agent operating manual.
- CLAUDE.md review suggestions: Stop hook detects changed files via
git statusand lists all CLAUDE.md files on path from root to changed folders. Shows (exists) or (missing - create if needed) for each. - Configurable CLAUDE.md ignored folders: New
claudemd_ignored_foldersin config.yaml to skip folders from review suggestions (defaults: node_modules, .git, dist, build, coverage, pycache, .next, .nuxt, .output, .cache, .turbo, .parcel-cache, .vite, .svelte-kit). - Task file auto-tracking: New
task-file-tracker.pyPostToolUse hook tracks when agent accesses files in.meridian/tasks/**. Tracked files are automatically injected after compaction even if the task isn't intask-backlog.yaml. Tracking file cleared after injection.
- Stop hook enhanced: Now includes CLAUDE.md review section prompting agent to create/update module documentation for changed areas.
- Context acknowledgment message: Now reminds agent to retry the blocked action after acknowledging context (prevents skipping steps after compaction).
- Requirements Interview phase: Planning skill now has mandatory Phase 0 that requires thorough user interview before any exploration. Covers functional requirements, edge cases, technical implementation, UI/UX, constraints, and scope boundaries.
- Professional Judgment section: Agent operating manual now instructs agents to push back on wrong/suboptimal user suggestions. Explain what's wrong, why, propose 2+ alternatives, let user decide.
- Worktree-safe IDs: Memory entries (
mem-0001-x7k3) and task folders (TASK-001-x7k3) now include random 4-char suffixes to prevent ID collisions when running parallel Claude sessions via git worktrees. - Interview mindset guidance: Agents should assume they don't know enough, ask non-obvious questions, go deep not broad, interview continuously.
- "Clarify → then act" → "Interview → then act": Core behavior now emphasizes iterative questioning (2-3 questions → answers → deeper follow-ups) before implementation.
- Plan structure template: Now includes "Requirements (from Interview)" section documenting functional requirements, edge cases, constraints, and out-of-scope items confirmed with user.
- Quality checklist: Added "Requirements interview completed" and "Edge cases documented" checkboxes.
- Pre-compaction sync double-fire bug: Removed logic that cleaned flag when tokens dropped below threshold. Hook now fires exactly once per session when crossing threshold.
- Code reviewer agent (
.claude/agents/code-reviewer.md): Line-by-line review of all code changes. Reviews for bugs, security, performance, and CODE_GUIDE compliance. Handles different git states (feature branch, uncommitted, staged). - Completeness reviewer: New
review_type: completenessfor implementation-reviewer verifies every plan item was implemented. - CLAUDE.md writer skill (
.claude/skills/claudemd-writer/): Comprehensive guidance for writing effective CLAUDE.md files. Covers hierarchical injection, "less is more" principle, what/how/why structure. - Plan mode tracker (
plan-mode-tracker.py): UserPromptSubmit hook detects Plan mode entry and prompts agent to invoke planning skill. - Session cleanup hook (
session-cleanup.py): Cleans up plan-mode state on session end, compaction, and /clear. - Path guard hook (
meridian-path-guard.py): Blocks writes to.meridian/or.claude/folders outside project root. Prevents agents from creating duplicate config folders in subfolders. - Human actions docs workflow: Pre-stop hook now prompts agent to create actionable docs in
.meridian/human-actions-docs/when work requires human setup (env vars, service accounts, etc.). - Dependency management guidance: Agent operating manual now includes strict workflow for adding dependencies—always query registry, never rely on training data for versions.
- CI failure fix cycle: Agent operating manual documents how to handle test/lint/build failures (read full output, fix root cause, verify).
- Testing strategy in planning: Planning skill now includes testing requirements section with
AskUserQuestionfor test depth preferences.
- Multi-reviewer strategy expanded: Pre-stop hook now requires 4 parallel reviewers: phase reviewers, integration reviewer, completeness reviewer, and code reviewer. Exact prompts provided for each.
- Subagent limits relaxed: Agent operating manual and planning skill now document that >3 subagents are allowed for thorough exploration and review phases.
- "Never without alternatives" audit: Fixed 7 prohibitions that lacked alternatives across CODE_GUIDE.md and agent-operating-manual.md. Every "never do X" now includes "do Y instead".
- Memory-curator scripts: Fixed misleading help text—scripts use auto-detected project root, not
CLAUDE_PROJECT_DIRenv var. - Detail completeness in planning: Planning skill now requires explicit steps for every mentioned integration, service, or module.
- TDD addon (
CODE_GUIDE_ADDON_TDD.md): Deprecated. Testing guidance moved to planning skill. Agents should always write tests; depth is task-specific. - TDD references: Cleaned up from config.py, required-context-files.yaml, config.yaml.
- user_provided_docs: New section in
required-context-files.yamlfor custom documentation. User docs are injected first, before memory and core files. - Auto-approve plan copying:
permission-auto-approver.pynow auto-approvescpcommands from~/.claude/plans/for plan archival. - Task creation reminder:
create-task.pynow outputs next steps including reminder to copy plan from~/.claude/plans/.
- CLAUDE_PROJECT_DIR enforcement: All hooks and scripts now require
CLAUDE_PROJECT_DIRenvironment variable with no fallbacks. Prevents scripts from creating files in wrong locations when agent cd's to subfolders. - Pre-compaction sync: Improved token calculation and logging.
- Cleaner context injection: Removed noisy
=separator lines from injected context header/footer.
- relevant-docs.md: Deprecated file removed. Use
user_provided_docsinrequired-context-files.yamlinstead.
- Context injection: Session hooks (
claude-init.py,session-reload.py) now inject file contents directly viaadditionalContextinstead of requiring Read tool calls. Files are wrapped in XML tags with explanatory header and acknowledgment footer. - Planning skill (
.claude/skills/planning/SKILL.md): Replaces the Plan agent. Main agent now plans directly while retaining full conversation context. Uses Explore subagents for codebase research. - Plan agent blocker (
block-plan-agent.py): Hook that intercepts Plan agent calls and redirects to the planning skill. - Multi-reviewer architecture: For large projects, spawn multiple focused implementation-reviewers (one per phase) plus integration reviewer(s). All reviewers run in parallel and write output to
.meridian/implementation-reviews/. - Mandatory Integration phase: Every multi-module plan must include an explicit Integration phase covering wiring, entry points, config, data flow, and error propagation.
- Strict quality checks: Implementation reviewer now flags hardcoded values, TODO/FIXME comments, and unused/orphaned code.
- Planning workflow: Main agent creates plans directly using the planning skill instead of delegating to a Plan subagent. This preserves full conversation context—important details discussed with the user won't be lost during planning.
- Plan content policy: Plans now describe WHAT and WHY, not HOW. No code snippets or pseudocode (even in English). Describe the destination, not the driving directions.
- Context acknowledgment flow:
post-compact-guard.pysimplified to block first tool call and require acknowledgment of injected context before proceeding. - Task status filtering: Changed from whitelist (
in-progress,active) to blacklist approach (not indone,completed,finished,cancelled,archived). - Implementation reviewer output: Now writes reviews to files (
$CLAUDE_PROJECT_DIR/.meridian/implementation-reviews/) instead of returning directly. UsesCLAUDE_PROJECT_DIRfor absolute paths.
- Plan agent (
.claude/agents/plan.md): Replaced by the planning skill. The skill provides the same methodology but allows the main agent to retain conversation context.
- Token calculation double-counting: Removed duplicated ephemeral values from calculation
- TASK-TASK prefix bug: Fixed duplicate prefix in context file paths
- Absolute path handling: All agents now use
CLAUDE_PROJECT_DIRenvironment variable - Logging always happens: Token logging now occurs even when pre-compaction flag is active
- Context files added to required reads after compaction
- Plan archival workflow:
plan-approval-reminder.pynow instructs agent to copy plans from Claude Code's ephemeral location (~/.claude/plans/) to task folders (.meridian/tasks/TASK-###/plan.md). Plans persist across sessions. - In-progress task injection:
session-reload.pyandclaude-init.pynow parsetask-backlog.yamland inject in-progress tasks at the top of context with XML tags (<in_progress_tasks>,<task_###>). Plan files from in-progress tasks are automatically added to required reads. - Token calculation logging:
pre-compaction-sync.pynow logs all calculations to.meridian/.pre-compaction-sync.logwith request IDs for debugging. - Task backlog helpers: New
get_in_progress_tasks()andbuild_task_xml()functions in shared config module.
- Planning workflow: Main agent now instructed to delegate to Plan agent instead of manually writing plans. Plan agent must save plans to
.claude/plans/and can use Explorer subagents. - Pending reads: Changed from single JSON file to directory-based marker files (
.meridian/.pending-context-reads/*.pending). File deletion is atomic, fixing race conditions when agent reads files in parallel. - Absolute paths everywhere: All hooks and memory-curator scripts now use
CLAUDE_PROJECT_DIRenvironment variable for absolute paths. Fixes issues when agent is in subdirectories. get_additional_review_files(): Now acceptsabsolute=Trueparameter to return absolute paths.
- Race condition when agent reads required context files simultaneously
- Relative paths failing when agent cd's into subdirectories
- Memory curator scripts failing due to relative path resolution
- CODE_GUIDE.md refactored: Complete rewrite from 121 numbered rules to organized sections with headers. Now has shared "General" section for cross-cutting concerns (TypeScript, Error Handling, Security, Testing, Config). Removed universal rules (naming conventions, "comments explain why"), removed niche rules (stampede control, COOP/COEP), removed arbitrary numbers ("~150 lines"), softened absolutes to "prefer X unless Y".
- CODE_GUIDE_ADDON_HACKATHON.md refactored: Streamlined with headers, generalized provider names (no more Auth0/Clerk/Firebase specifics), added graduation checklist.
- CODE_GUIDE_ADDON_PRODUCTION.md refactored: Principles only, removed specific tech details (TS flags, distroless images, SBOM). Removed dark mode requirement. Focus on what to strengthen, not how.
- CODE_GUIDE_ADDON_TDD.md refactored: 244 → 87 lines. Removed code skeletons and output templates. Kept core TDD workflow and "Confirm Test Cases with User" section.
- agent-operating-manual.md: Added "Never Do" section (no silent pivots, no arbitrary metric targets, no silent error swallowing). Added "Verify Before Assuming" and "Reading Context Effectively" sections. Added DoD anti-patterns ("NOT done if"). Changed question guidance to encourage asking more.
- task-manager SKILL.md: Added "New Task vs Continue Existing" criteria. Added inline context.md template with Origin section.
- memory-curator SKILL.md: Added good/bad examples for when to create entries.
- TASK-000-context.md template: Added Origin section for planning decisions.
- PR link references from all documentation files
- Arbitrary line count guidance from all guides
- Code skeletons from TDD addon
- Output format templates from TDD addon
- Specific tool/flag names from production addon (kept as principles)
- Pre-compaction sync hook (
pre-compaction-sync.py): Monitors token usage from transcript and prompts agent to save context before conversation compacts. Configurable threshold (default 150k tokens). - Smart context guard (
post-compact-guard.pyrewrite): Tracks required file reads in.meridian/.pending-context-reads. Allows Read tool for pending files, blocks other tools until all required files are read. No more "read files twice" problem. - Required context files config (
.meridian/required-context-files.yaml): Centralized config for files that must be read on session start/reload. Supports core files, project-type addons, and TDD addon. - Plan review hook (
plan-review.py): Requires plan-reviewer agent before exiting plan mode. Configurable viaplan_review_enabledin config.yaml. - Shared helpers module (
.claude/hooks/lib/config.py): Extracted common code (YAML parsing, config reading, flag management) from hooks to reduce duplication. - New config options in
.meridian/config.yaml:plan_review_enabled: Toggle plan-reviewer requirement (default: true)implementation_review_enabled: Toggle implementation-reviewer in pre-stop hook (default: true)pre_compaction_sync_enabled: Toggle pre-compaction context save prompt (default: true)pre_compaction_sync_threshold: Token threshold for pre-compaction warning (default: 150000)
- Task workflow simplified: Removed
TASK-###.yamlandTASK-###-plan.mdfrom task template. Plans are now managed by Claude Code in.claude/plans/. Task folders contain onlyTASK-###-context.mdas the primary source of truth. - task-backlog.yaml: Now includes
plan_pathfield pointing to Claude Code plan files. - TASK-###-context.md template: Enhanced with Status section, Key Decisions & Tradeoffs section, and structured Session Log format.
- session-reload.py: Simplified post-compaction instructions since context should already be saved by pre-compaction hook. Now reads from required-context-files.yaml.
- claude-init.py: Now reads from required-context-files.yaml instead of hardcoded file list.
- All hooks refactored to use shared helpers module, reducing code duplication.
TASK-###.yamltemplate file (objective, constraints, requirements now live in Claude Code plan)TASK-###-plan.mdtemplate file (plans managed by Claude Code).claude/hooks/prompts/session-reload.md(prompt now generated dynamically).meridian/.needs-context-reviewflag (replaced by.pending-context-readssmart tracking)
startup-prune-completed-tasks.pyhook, triggered on startup/clear, that automatically archives olderdone/completedtasks. Only the 10 most recent completed tasks stay intask-backlog.yaml, and pruned tasks move totask-backlog-archive.yamlplus.meridian/tasks/archive/.edit_memory_entry.pyanddelete_memory_entry.pyscripts for the memory-curator skill, enabling safe updates/removals in.meridian/memory.jsonl.SKILL.mdnow documents how to run both scripts.permission-auto-approver.py, a PermissionRequest hook that silently whitelists known-safe Meridian actions (memory/task skills, backlog edits, etc.).settings.jsonnow invokes this hook for every PermissionRequest event.
- Task-manager and memory-curator SKILL guides were heavily trimmed to remove noisy guidance. Both are now shorter, strictly action-focused, and avoid repeating information that bloated the context.
relevant-docs.mdnow describes section-based doc requirements (“when working on X, read Y”) instead of forcing Claude to read every listed file on startup. Hooks will prompt Claude to read only the docs tied to the area it’s actively working on.