CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

Quick Links

New to meta-cc?

Start here: README.md - Installation and quick start
Understand the design: docs/core/principles.md - Core constraints
Integration guide: docs/guides/integration.md - Choose MCP/Slash

Development Workflow

Current plan: docs/core/plan.md - Phase roadmap and status
Build and test: Run make dev (quick) → make test-scoped PKGS=<pkgs> (scoped, seconds) → make commit (validate) → make push (full check)
Testing workflow: docs/guides/testing.md - Two-stage acceptance (scoped iteration + full gate)
Plugin development: docs/guides/plugin-development.md - Complete workflow

MCP Server Usage

MCP guide: docs/guides/mcp.md - Complete MCP reference (16 tools)
Quick test: Use MCP tool get_session_stats

Common Tasks

Fix test failures: make dev → Review errors → Fix → make commit
Query session data: Use MCP tools (see MCP Guide)
Update plugin: docs/guides/plugin-development.md
Manage prompts: /prompt-list (browse) | /prompt-find <keywords> (search) | /prompt-show <id> (view)

FAQ

Q: Tests failed after my changes - what should I do? A: Run make dev for quick iteration, then make commit to validate. Fix issues iteratively. If tests fail after multiple attempts, HALT development and document blockers.

Q: How do I iterate quickly instead of waiting ~60s for make commit on every edit? A: Use the two-stage acceptance workflow. Stage 1: make test-scoped PKGS=./internal/<pkg>/... runs just the touched package's tests plus a module-wide build in seconds. Stage 2: make commit is unchanged and remains the promotion gate before a task goes to ready/done. See docs/guides/testing.md.

Q: How much code can I write in one phase? A: Maximum 500 lines of code modifications per phase, 200 lines per stage. See docs/core/principles.md.

Q: Should I use MCP or Slash Commands? A: Quick rule: Natural questions → MCP | Repeated workflows → Slash. See docs/guides/integration.md.

Q: How do I query session data? A: Use consolidated query tools for common questions and the two-stage tools for custom jq:

// Consolidated query tools
query_session_signals({type: "errors", limit: 10})
query_session_signals({type: "tokens", stats_first: true})
query_session_content({role: "user", pattern: "fix.*bug"})

// Custom jq over selected files
execute_stage2_query({
  files: ["/path/to/session.jsonl"],
  filter: 'select(.type == "assistant")',
  transform: '{timestamp, usage: .message.usage}'
})

See MCP Query Tools Reference and Two-Stage Query Guide for complete documentation.

Q: Why are my MCP query results in a temp file? A: Results >8KB automatically use file_ref mode to avoid token limits. Read the file with the Read tool. This is hybrid output mode - queries return inline for small results (<8KB) and file_ref for large results (≥8KB). See MCP Query Tools Reference.

Q: Do I need to set limit parameter for MCP queries? A: No, by default queries return all results (hybrid mode handles large data). Only use limit when user explicitly requests a specific number. The system automatically switches to file_ref mode for large result sets.

Q: Which MCP query tool should I use? A: Follow this decision tree:

Query messages/content → Use query_session_content(role=user|assistant|tool|all)
Query signals/stats → Use query_session_signals(type=errors|tokens|system_errors|timestamps|tool_stats)
Query file history → Use query_file_activity(type=snapshots)
Maximum flexibility → Use get_session_directory → inspect_session_files → execute_stage2_query
Cross-provider history → Pass provider: "claude", provider: "codex", or provider: "all" to query and analysis tools See MCP Query Tools Reference for detailed guidance.

Q: How do I write jq expressions for MCP queries? A: Start simple and add complexity:

// Step 1: Select files
const dir = await get_session_directory({scope: "project"})

// Step 2: Filter by record shape
execute_stage2_query({
  files: dir.files,
  filter: 'select(.type == "assistant")'
})

// Step 3: Transform output
execute_stage2_query({
  files: dir.files,
  filter: 'select(.type == "user")',
  transform: '{timestamp, content: .message.content}'
})

Test jq locally first: echo '{"type":"user"}' | jq 'select(.type == "user")'. See Two-Stage Query Guide for common patterns.

Q: How do I update plugin version? A: Install git hooks (./scripts/install/install-hooks.sh) for automatic bumping, or use ./scripts/release/bump-plugin-version.sh [patch|minor|major]. See docs/guides/git-hooks.md.

Q: How does the prompt learning system work? A: Use /prompt-find, /prompt-list, and /prompt-show to manage a project-local library of optimized prompts stored in .meta-cc/prompts/library/. Browse your library with /prompt-list.

Q: Where are saved prompts stored? A: Project-local storage in .meta-cc/prompts/library/ (not tracked by git by default). You can commit selectively if you want to share with your team. The directory is auto-created on first save.

Q: How do I find a saved prompt? A: Three methods (from fastest to most flexible):

Direct search (recommended): /prompt-find <keywords> - Fast, deterministic search
- Example: /prompt-find phase plan execute
- Uses keyword matching, no LLM overhead
Manual search: grep, rg, or file browser
- Files are plain markdown in .meta-cc/prompts/library/

Q: What if I don't want to save prompts? A: Saving is completely optional. Just press Enter or answer "n" when prompted. The save option won't appear again until you optimize another prompt.

Q: How do I browse my saved prompts? A: Use the slash commands (recommended) or shell tools:

List all prompts: /prompt-list
- Filter by category: /prompt-list category=release
- Sort by usage: /prompt-list sort=usage (default, most used first)
- Sort by date: /prompt-list sort=date (most recent first)
- Sort alphabetically: /prompt-list sort=alpha
View prompt details: /prompt-show <prompt-id>
- Example: /prompt-show phase-execution-001
- Supports partial ID matching: /prompt-show phase
Search prompts: /prompt-find <keywords>
- Example: /prompt-find debug error analysis
Shell commands: ls -lt .meta-cc/prompts/library/ to see files by date
Search tools: rg "keyword" .meta-cc/prompts/library/ to search content

Slash Command Summary:

/prompt-find <keywords> - Search for prompts
/prompt-list [category=X] [sort=usage|date|alpha] - List all prompts
/prompt-show <prompt-id> - View full prompt details

Q: Can I delete or edit saved prompts? A: Yes, they're just markdown files:

Delete: rm .meta-cc/prompts/library/release-simple-001.md
Edit: vim .meta-cc/prompts/library/release-simple-001.md
Archive: Edit YAML frontmatter, set status: archived

Q: Can I share prompts with my team? A: Yes, commit to git:

git add .meta-cc/prompts/library/release-*.md
git commit -m "docs: share release process prompts"
git push

Q: How do I back up my prompt library? A: Simple directory copy:

# Backup
cp -r .meta-cc/prompts ~/backups/project-prompts-$(date +%Y%m%d)

# Restore
cp -r ~/backups/project-prompts-20251027/.meta-cc/prompts .meta-cc/

Q: Can I use prompts across multiple projects? A: Currently project-local. A future update may add global library in ~/.meta-cc/ for cross-project sharing.

Project Overview

meta-cc (Meta-Cognition for Claude Code) analyzes Claude Code session history to provide metacognitive insights and workflow optimization.

Architecture

MCP-based architecture:

MCP Server: Provides 16 tools for session history analysis and query
Claude Integration: Slash commands for prompt management

Key principle: MCP server handles data extraction and query. Claude performs semantic understanding and recommendations.

Repository Structure

See docs/reference/repository-structure.md for complete directory guide.

Key directories:

plugin-src/ - Plugin entry point (slash commands, skills), published via .claude-plugin/marketplace.json
cmd/mcp-server/ - MCP server implementation
internal/ - Core logic (parser, analyzer, query)
docs/ - Technical documentation

Core Constraints

See docs/core/principles.md for complete details.

Code Limits:

Phase: ≤500 lines of code modifications
Stage: ≤200 lines of code modifications

Development Methodology:

TDD: Write tests before implementation
Test Coverage: ≥80%
Testing Protocol: Run make commit after each Stage

Testing Failure Protocol:

If tests repeatedly fail → Stop immediately
Document failure state and blockers
Do NOT proceed until resolved

Quay Workspace Boundary

Routine findings may be filed as meta-cc tasks only when every intended code or documentation write belongs to this repository or one of its Git worktrees.

Findings whose fix belongs to another repository must be reported only. Do not create a local task, dispatch an agent, or modify that repository.

Every routine-filed execution task must declare scope.owner_repo: meta-cc and a repository-relative ## Touches section.

Development Quick Start

Build and Test

make dev           # Quick dev build (format + build, <10s)
make test-scoped PKGS=./internal/<pkg>/...  # Scoped fail-fast check (<10s)
make commit        # Pre-commit validation (workspace + tests, <60s)
make push          # Full check before push (all checks + lint, <120s)
make test          # Run tests only
make lint          # Static analysis
make test-coverage # Coverage report

See docs/guides/testing.md for the two-stage acceptance workflow.

Before committing:

Run make commit to ensure code passes essential validation
Fix any issues reported
Before pushing, run make push for full verification

Plugin Development

Local development setup:

# 1. Edit source files
vim plugin-src/commands/prompt-find.md   # Slash command
vim plugin-src/commands/prompt-list.md   # Slash command
vim plugin-src/commands/prompt-show.md   # Slash command

# 2. Test in Claude Code (no build needed)

# 3. Run tests
make commit

See: docs/guides/plugin-development.md for complete workflow.

Version Management

Three methods:

Git Hook (automatic) — ⚠️ currently INOPERATIVE, for two independent reasons:
```
./scripts/install/install-hooks.sh  # One-time setup
# Then: git commit auto-bumps version on plugin-src/ changes
```
- .pre-commit-config.yaml:97 still matches ^\.claude/(commands|agents)/.*\.md$. That layout was replaced by plugin-src/ in 2026-03 (commit 2540243), so the plugin-version-bump hook can never fire.
- scripts/install/install-hooks.sh:13 exits 1 because the .githooks/ directory it copies from does not exist.
Until the pattern is repointed at plugin-src/ and the installer path is fixed, use method 2.

Manual script:

./scripts/release/bump-plugin-version.sh patch   # or minor/major

Full release:
```
./scripts/release/release.sh v1.0.0
```

See: docs/guides/git-hooks.md and docs/guides/release-process.md.

Commit Conventions

Use descriptive commit messages with scope prefixes:

docs: for documentation changes
feat: for new features
fix: for bug fixes
refactor: for code restructuring
test: for test-related changes

Include the Claude Code attribution footer:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Common Development Tasks

Fix Test Failures

# 1. Run tests
make test

# 2. Review errors
# (Analyze test output)

# 3. Fix issues
vim path/to/failing_test.go

# 4. Verify fix
make commit

Query Session Data (via MCP)

Consolidated query tools:

query_session_signals({type: "errors", limit: 10})
query_session_signals({type: "tool_stats", tool: "Read", limit: 20})
query_session_content({role: "user", pattern: "fix.*bug"})

Two-stage jq:

const dir = await get_session_directory({scope: "project"})
execute_stage2_query({
  files: dir.files,
  filter: 'select(.type == "assistant")',
  limit: 20
})

See:

MCP Query Tools Reference - Current MCP tool reference
Two-Stage Query Guide - Custom jq workflow
MCP Guide - Complete MCP reference

Update Plugin

Edit slash command:

vim plugin-src/commands/prompt-find.md
# Test in Claude Code immediately (no build needed)
git commit -m "feat: improve prompt-find matching"
# Version bump is manual: scripts/release/bump-plugin-version.sh
# (the git-hook path is currently inoperative — see "Version Management" above)

See: docs/guides/plugin-development.md for complete workflow.

Reference Documentation

Core Documentation:

Implementation Plan - Phase-by-phase roadmap
Design Principles - Core constraints and rules
Plugin Development - Complete plugin workflow
Repository Structure - Directory organization
Release Process - Release workflow
Git Hooks - Automatic version bumping

Integration and Usage:

Integration Guide - Choose MCP/Slash
MCP Guide - Complete MCP server reference (16 tools)

Reference:

JSONL Reference - Output format and jq patterns
Features - Advanced features overview
Examples & Usage - Step-by-step tutorials
Troubleshooting - Common issues

Architecture:

Technical Proposal - Architecture design
ADR Index - Architecture decision records. ADRs use the decision lifecycle (proposed → accepted → superseded | deprecated, or rejected), not the task/directive lifecycle — an ADR is a standing decision, never "done". Each ADR file carries YAML frontmatter (id, title, status, date) and is registered with the quay-native provider via QUAY_NATIVE_ADR_DIR in .quay/config.yml; query with quay adr list / quay adr get (MCP adr_list / adr_get).

Universal Methodology (project-independent):

Methodology Index - Software development methodologies
Documentation Management - Documentation methodology for Claude Code projects

Official Claude Code Documentation:

Navigation Menu

Repository navigation

CLAUDE.md

Quick Links

New to meta-cc?

Development Workflow

MCP Server Usage

Common Tasks

FAQ

Project Overview

Architecture

Repository Structure

Core Constraints

Quay Workspace Boundary

Development Quick Start

Build and Test

Plugin Development

Version Management

Commit Conventions

Common Development Tasks

Fix Test Failures

Query Session Data (via MCP)

Update Plugin

Reference Documentation

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Quick Links

New to meta-cc?

Development Workflow

MCP Server Usage

Common Tasks

FAQ

Project Overview

Architecture

Repository Structure

Core Constraints

Quay Workspace Boundary

Development Quick Start

Build and Test

Plugin Development

Version Management

Commit Conventions

Common Development Tasks

Fix Test Failures

Query Session Data (via MCP)

Update Plugin

Reference Documentation