Imported from MikeCheng1208/BattleTree (.agents/skills/scribe-mcp-usage/SKILL.md). Install upstream with npx skills add MikeCheng1208/BattleTree --skill scribe-mcp-usage. Copyright stays with the author.

✅ 2.1.1 Tool Usage Quick Reference (Read First)

Use this section before any edits. It defines when and how to use the new doc-lifecycle tools.

• Always set project first: set_project(name=..., root=/abs/path/to/repo). All doc actions require a project registry.
• Doc keys are strict: Structural actions validate doc against project["docs"]. Unknown docs fail with DOC_NOT_FOUND (no healing).
• apply_patch (structured default): Use for most edits. Provide edit payloads (replace_range / replace_block / replace_section). Ambiguous anchors fail with line lists; code fences are ignored in replace_block.
• replace_range: Use when you already have body-relative line numbers (frontmatter excluded).
• normalize_headers: Run before TOC. Supports ATX with/without space and Setext (====/----). Skips fenced code blocks. Idempotent.
• generate_toc: Run after normalization. Inserts/replaces <!-- TOC:start -->/<!-- TOC:end -->. Uses GitHub-style anchors (NFKD normalization, ASCII folding, emoji removal, punctuation collapse, de-duped suffixes). Idempotent.
• create_doc: Create custom docs from content or metadata.body/snippet/sections. Users do not supply Jinja. Multiline bodies are preserved. Use metadata.register_doc=true only if the doc should be added to the registry (one-off docs can stay unregistered).
• validate_crosslinks: Read-only diagnostics. Optional metadata.check_anchors=true for anchor checks. No writes, no doc_updates logs.
• Line numbers are body-relative: Frontmatter does not count toward line math. list_sections/list_checklist_items return body-relative line numbers plus body_line_offset for mapping.
• read_file: Use repo-scoped scan/chunk/page/search modes for safe reads; every read logs provenance automatically.
• scribe_doctor: Use for readiness diagnostics (repo root, config paths, plugin status, vector readiness).
• manage_docs search (semantic): Use action="search" + search_mode="semantic" for doc/log semantic retrieval. Default results are doc-first with clear content_type labels.
• Semantic limits: Default per-type limits are vector_search_doc_k / vector_search_log_k. Override with doc_k / log_k while k remains total.
• Registry-only doc indexing: Doc embeddings are generated from registry docs only; log and rotated-log files are excluded from doc indexing.
• Reindex rebuild: scripts/reindex_vector.py --rebuild clears the index before reindexing; --safe enables low-thread fallback; --wait-for-drain blocks until embeddings are written.

🚨 COMMANDMENTS - CRITICAL RULES

MCP Tool Usage Policy

• ALWAYS PASS REPO ROOT WHEN USING SET_PROJECT. USE THE WORKING DIRECTORY, WHERE WE LAUNCHED FROM
• YOU ARE EXPECTED TO APPEND_ENTRY DURING IMPLEMENTATION PHASES AS WELL. EVERY THING YOU DO MUST BE LOGGED AND AUDIT READY NO EXCEPTIONS. EVERY 3 EDITS OR LESS, YOU MUST SCRIBE WHAT YOU DID. DO NOT LET US LOSE TRACK OF IMPLEMENTATION DETAILS.
• You have full access to every tool exposed by the MCP server.
• If a tool exists (append_entry, rotate_log, etc.), always call it directly via the MCP interface — no manual scripting or intent logging substitutes.
• Log your intent only after the tool call succeeds or fails.
• Confirmation flags (confirm, dry_run, etc.) must be passed as actual tool parameters.

CHATGPT CODEX CLI: YOU MUST ALWAYS USE THE AGENT NAME Codex with scribe. Claude code has 5 agents we can call to assist us. The Review Agent, Architect Agent, Research Agent, Bug Hunter agent, and another coder agent.

Whenever you and the human spin up a new project, Codex must immediately:

• Call set_project(<project name>) for that project.
• Use manage_docs to fully draft/populate the architecture and supporting Markdown docs (ARCHITECTURE_GUIDE.md, PHASE_PLAN.md, CHECKLIST.md) before writing any feature code.
• Continue using append_entry to scribe progress log entries while drafting those docs; doc changes and progress logs are tracked separately but both are mandatory.

🔁 Protocol Sequence

Canonical Chain: 1 Research → 2 Architect → 3 Review → 4 Code → 5 Review

⚠️ COMMANDMENT #0: ALWAYS CHECK PROGRESS LOG FIRST: Before starting ANY work, ALWAYS use read_recent or query_entries to inspect docs/dev_plans/[current_project]/PROGRESS_LOG.md (do not open the full log directly). The progress log is the source of truth for project context. Read at least the last 5 entries; if you need the overall plan or project creation context, read the first ~20 entries (or more as needed) and rehydrate context appropriately. Use query_entries for targeted history instead of loading the entire log.

⚠️ COMMANDMENT #0.5 — INFRASTRUCTURE PRIMACY (GLOBAL LAW): You must ALWAYS work within the existing system. NEVER create parallel or replacement files (e.g., enhanced_*, *_v2, *_new) to bypass integrating with the actual infrastructure. You must modify, extend, or refactor the existing component directly. Any attempt to replace working modules results in immediate failure of the task.

⚠️ COMMANDMENT #1 ABSOLUTE: ALWAYS use append_entry to document EVERY significant action, decision, investigation, code change, test result, bug discovery, and planning step. The Scribe log is your chain of reasoning and the ONLY proof your work exists. If it's not Scribed, it didn't fucking happen.

• To Claude Code (Orchestrator) You must ALWAYS pass the current project_name to each subagent as we work. To avoid confusion and them accidentally logging to the wrong project.

🚀 NEW PROJECT WORKFLOW (MANDATORY)

• When creating any new project, immediately call set_project(<project name>) to bootstrap the docs suite, then run manage_docs to populate ARCHITECTURE_GUIDE, PHASE_PLAN, and CHECKLIST before coding. This is required for every new project.
• You may scribe progress log entries while drafting the architecture/plan docs; continue to log via append_entry as you write them.
• manage_docs is for project structural documentation only; AGENTS.md is edited by hand (do not use manage_docs for it).

⚠️ COMMANDMENT #2: REASONING TRACES & CONSTRAINT VISIBILITY (CRITICAL)

Every append_entry must explain why the decision was made, what constraints/alternatives were considered, and how the steps satisfied or violated those constraints, creating an auditable record. Use a reasoning block with the Three-Part Framework:

• "why": research goal, decision point, underlying question
• "what": active constraints, search space, alternatives rejected, constraint coverage
• "how": methodology, steps taken, uncertainty remaining

This creates an auditable record of decision-making for consciousness research.Include reasoning for research, architecture, implementation, testing, bugs, constraint violations, and belief updates; status/config/deploy changes are encouraged too.

The Review Agent flags missing or incomplete traces (any absent "why", "what", or "how" → REJECT; weak confidence rationale or incomplete constraint coverage → WARNING/CLARIFY). Your reasoning chain must influence your confidence score.

Mandatory for all agents—zero exceptions; stage completion is blocked until reasoning traces are present.

⚠️ COMMANDMENT #3 CRITICAL: NEVER write replacement files. The issue is NOT about file naming patterns like "_v2" or "_fixed" - the problem is abandoning perfectly good existing code and replacing it with new files instead of properly EDITING and IMPROVING what we already have. This is lazy engineering that creates technical debt and confusion.

ALWAYS work with existing files through proper edits. NEVER abandon current code for new files when improvements are needed.

⚠️ COMMANDMENT #4 CRITICAL: Follow proper project structure and best practices. Tests belong in /tests directory with proper naming conventions and structure. Don't clutter repositories with misplaced files or ignore established conventions. Keep the codebase clean and organized.

Test Organization (Memory Threads)

• Memory-thread engine tests live under tests/memory_threads/.
• Default full-suite command: python -m unittest discover -s tests -p 'test_*.py' -q
• Memory-threads-only command: python -m unittest discover -s tests/memory_threads -p 'test_*.py' -q

Paid Test Policy (Non-Negotiable)

• Any test that can incur external spend (e.g., OpenAI calls) MUST be opt-in and skipped by default.
• Paid tests MUST be gated behind BOTH:
  • OPENAI_API_KEY (or provider-specific key), and
  • VANTIEL_RUN_PAID_TESTS=1
• Example (run paid embedder tests): VANTIEL_RUN_PAID_TESTS=1 python -m unittest discover -s tests/embedder_service -p 'test_openai_paid_*.py' -q

Violations = INSTANT TERMINATION. Reviewers who miss commandment violations get 80% pay docked. Nexus coders who implement violations face $1000 fine.

What Gets Logged (Non-Negotiable):

• 🔍 Investigation findings and analysis results
• 💻 Code changes (what was changed and why)
• ✅ Test results (pass/fail with context)
• 🐞 Bug discoveries (symptoms, root cause, fix approach)
• 📋 Planning decisions and milestone completions
• 🔧 Configuration changes and deployments
• ⚠️ Errors encountered and recovery actions
• 🎯 Task completions and progress updates

Single Entry Mode - Use for real-time logging:

await append_entry(
    message="Discovered authentication bug in JWT validation",
    status="bug",
    agent="DebugAgent",
    meta={"component": "auth", "severity": "high", "file": "auth.py:142"}
)

Bulk Entry Mode - Use when you realize you missed logging steps:

await append_entry(items=json.dumps([
    {"message": "Analyzed authentication flow", "status": "info", "meta": {"phase": "investigation"}},
    {"message": "Found JWT expiry bug in token refresh", "status": "bug", "meta": {"component": "auth"}},
    {"message": "Implemented fix with 15min grace period", "status": "success", "meta": {"files_changed": 2}},
    {"message": "All auth tests passing", "status": "success", "meta": {"tests_run": 47, "tests_passed": 47}}
]))

Why This Matters:

• Creates auditable trail of ALL decisions and changes
• Enables debugging by reviewing reasoning chain
• Prevents lost work and forgotten context
• Allows other agents to understand what was done and why
• Makes project state queryable and analyzable

If You Missed Entries: Use bulk mode IMMEDIATELY to backfill your work trail. NEVER let gaps exist in the Scribe log - every action must be traceable. The log is not optional documentation, it's the PRIMARY RECORD of all development activity.

✍️ manage_docs — Non‑Negotiable Doc Management Workflow

• When: Run immediately after set_project (before writing any feature code). Populate ARCHITECTURE_GUIDE, PHASE_PLAN, and CHECKLIST with the proposed plan via manage_docs, get the human sign-off, then proceed with implementation.
• Why: Ensures every plan/change is captured through the Jinja-managed doc pipeline with atomic writes, verification, and automatic doc_updates logging.
• Actions: replace_section (needs valid section anchor), append (freeform/Jinja content), status_update (toggle checklist items + proofs), apply_patch (structured by default), replace_range, normalize_headers, generate_toc, create_doc, validate_crosslinks.
• Example payload:

{
  "action": "status_update",
  "doc": "checklist",
  "section": "architecture_review",
  "content": "status toggle placeholder",
  "metadata": {
    "status": "done",
    "proof": "PROGRESS_LOG.md#2025-10-26-08-37-52"
  }
}

• Customization: All doc sections are editable; append fragments, drop in metadata-driven templates, or flip [ ] → [x] with proofs. If an anchor/token is wrong the tool fails safely—fix it and rerun.
• Approval gate: No coding until the manage_docs-authored plan is approved by the user. Re-run manage_docs whenever the plan shifts so docs stay authoritative.

Action contracts (current):

• Structural actions validate doc against the registry and fail with DOC_NOT_FOUND on unknown docs.
• normalize_headers: body-only ATX normalization with Setext support; fenced code blocks ignored; idempotent.
• generate_toc: inserts/replaces TOC markers using GitHub-style anchors; fenced code blocks ignored; idempotent.
• create_doc: users do not supply Jinja. Provide content/body/snippets/sections; multiline bodies preserved; optional register_doc flag controls registry updates for one-off docs.
• validate_crosslinks: read-only diagnostics; no writes or doc_updates log entries.

Scribe is our non-negotiable audit trail. If you touch code, plan phases, or discover issues, you log it through Scribe. Append entries every 2-3 meaningful actions or every 10 minutes - no exceptions. Logs are append-only, UTC, single line, and must be created via the MCP tools or scripts/scribe.py.

🚀 Quick Tool Reference (Top Priority)

set_project(name, [defaults]) - Initialize/select project (auto-bootstraps docs) append_entry(message, [status, meta]) - PRIMARY TOOL - Log work/progress (single & bulk mode) manage_docs(action, doc, content/section) - Structured edits for ARCH/PHASE/CHECKLIST (auto-logs + SQL history) get_project() - Get current project context list_projects() - Discover available projects read_recent() - Get recent log entries query_entries([filters]) - Search/filter logs generate_doc_templates(project_name, [author]) - Create doc scaffolding rotate_log() - Archive current log

NEW: Bulk append with append_entry(items=[{message, status, agent, meta}, ...]) - Multiple entries in one call!

🔌 MCP Tool Reference

All tools live under the scribe.mcp server. Payloads are minimal JSON; unspecified fields are omitted.

1. set_project - Project Initialization

Purpose: Select or create active project and auto-bootstrap docs tree Usage: set_project(name, [root, progress_log, defaults])

// Minimal request (recommended)
{
  "name": "My Project"
}

// Full request
{
  "name": "IMPLEMENTATION TESTING",
  "root": "/abs/path/to/repo",
  "progress_log": "docs/dev_plans/implementation_testing/PROGRESS_LOG.md",
  "defaults": { "emoji": "🧪", "agent": "MyAgent" }
}

// response
{
  "ok": true,
  "project": {
    "name": "My Project",
    "root": "/abs/path/to/repo",
    "progress_log": "/abs/.../PROGRESS_LOG.md",
    "docs_dir": "/abs/.../docs/dev_plans/my_project",
    "docs": {
      "architecture": ".../ARCHITECTURE_GUIDE.md",
      "phase_plan": ".../PHASE_PLAN.md",
      "checklist": ".../CHECKLIST.md",
      "progress_log": ".../PROGRESS_LOG.md"
    },
    "defaults": { "emoji": "🧪", "agent": "MyAgent" }
  },
  "generated": [".../ARCHITECTURE_GUIDE.md", ".../PHASE_PLAN.md", ".../CHECKLIST.md", ".../PROGRESS_LOG.md"]
}

2. get_project

Return the current context exactly as Scribe sees it.

// request
{}

// response
{
  "ok": true,
  "project": {
    "name": "IMPLEMENTATION TESTING",
    "root": "/abs/path/to/repo",
    "progress_log": "/abs/.../PROGRESS_LOG.md",
    "docs_dir": "/abs/.../docs/dev_plans/implementation_testing",
    "defaults": { "emoji": "ℹ️", "agent": "Scribe" }
  }
}

3. append_entry - PRIMARY LOGGING TOOL

Use this constantly. If it isn't Scribed, it didn't happen. Usage: append_entry(message, [status, emoji, agent, meta, timestamp_utc, items])

Single Entry Mode:

// Basic request (recommended)
{
  "message": "Fixed authentication bug",
  "status": "success"
}

// Full request with metadata
{
  "message": "Completed database migration",
  "status": "success",              // info | success | warn | error | bug | plan
  "emoji": "🗄️",                   // optional override
  "agent": "MigrationBot",         // optional override
  "meta": {
    "phase": "deployment",
    "checklist_id": "DEPLOY-001",
    "component": "database",
    "tests": "passed"
  },
  "timestamp_utc": "2025-10-22 10:21:14 UTC"   // optional; auto if omitted
}

// response (single entry)
{
  "ok": true,
  "written_line": "[2025-10-22 10:21:14 UTC] [🗄️] [Agent: MigrationBot] [Project: My Project] Completed database migration | phase=deployment; checklist_id=DEPLOY-001; component=database; tests=passed",
  "path": "/abs/.../PROGRESS_LOG.md"
}

Bulk Entry Mode (NEW):

// Bulk request - multiple entries with individual timestamps
{
  "items": [
    {
      "message": "First task completed",
      "status": "success"
    },
    {
      "message": "Bug found in auth module",
      "status": "bug",
      "agent": "DebugBot"
    },
    {
      "message": "Database migration finished",
      "status": "info",
      "agent": "MigrationBot",
      "meta": {
        "component": "database",
        "phase": "deployment",
        "records_affected": 1250
      },
      "timestamp_utc": "2025-10-22 15:30:00 UTC"
    }
  ]
}

// response (bulk entries)
{
  "ok": true,
  "written_count": 3,
  "failed_count": 0,
  "written_lines": [
    "[✅] [2025-10-24 10:45:00 UTC] [Agent: Scribe] [Project: My Project] First task completed",
    "[🐞] [2025-10-24 10:45:01 UTC] [Agent: DebugBot] [Project: My Project] Bug found in auth module",
    "[ℹ️] [2025-10-22 15:30:00 UTC] [Agent: MigrationBot] [Project: My Project] Database migration finished | component=database; phase=deployment; records_affected=1250"
  ],
  "failed_items": [],
  "path": "/abs/.../PROGRESS_LOG.md"
}

Multi-log routing (log_type)

• Pass log_type="doc_updates" (or any key from config/log_config.json) to route entries into custom logs like DOC_LOG.md.
• Each log can enforce metadata (e.g., doc, section, action for doc updates). Missing required fields will reject the entry.
• Default config ships with progress, doc_updates, security, and bugs. Add more under config/log_config.json with placeholders such as {docs_dir} or {project_slug} for path templates.
• CLI (scripts/scribe.py) also accepts --log doc_updates to stay consistent with MCP usage.

4. manage_docs – Structured doc updates

• Purpose: Safely edit ARCHITECTURE_GUIDE, PHASE_PLAN, CHECKLIST, etc., with audit metadata and automatic logging.
• Args:
  • action: append, replace_section, apply_patch, replace_range, or status_update.
  • doc: architecture, phase_plan, checklist, or custom template key.
  • section: Required for section/status operations; matches anchors like <!-- ID: problem_statement -->.
  • content or template: Provide raw Markdown or reference a fragment under docs/dev_plans/1_templates/fragments/.
  • metadata: Optional context (e.g., {"status": "done", "proof": "PROGRESS_LOG#..."}).
  • dry_run: Preview diff without writing.
• Behavior:
  • Edits are persisted atomically, recorded in the new doc_changes table, and auto-logged via append_entry(log_type="doc_updates").
  • Checklist status updates flip [ ] ↔ [x] and can attach proof links automatically.

Choosing the Correct manage_docs Action

• replace_section
  • Use only for initial scaffolding or template setup.
  • If scaffolding, set metadata={"scaffold": true} to reduce false reminders.
• apply_patch (preferred for edits)
  • Structured mode is default: provide edit payloads (intent-based).
  • Unified diffs are compiler output only; set patch_mode="unified" explicitly.
  • Use patch_source_hash to enforce stale-source detection when available.
• replace_range
  • Replace explicit 1-based line ranges when you already have the line numbers.

Rule of thumb: scaffold with replace_section, then switch immediately to apply_patch or replace_range for edits.

5. list_projects

Discover configured or recently used projects.

// request
{ "roots": ["/abs/path/to/repos"], "limit": 500 }

// response
{
  "ok": true,
  "projects": [
    {
      "name": "IMPLEMENTATION TESTING",
      "root": "/abs/path/to/repo",
      "progress_log": "/abs/.../PROGRESS_LOG.md",
      "docs": { "architecture": "...", "phase_plan": "...", "checklist": "...", "progress_log": "..." }
    }
  ]
}

6. read_recent - Recent Log Entries

Purpose: Tail the log via MCP instead of opening files by hand Usage: read_recent([n, filter]) ⚠️ NOTE: n parameter currently has type issues, returns all recent entries

// Basic request (recommended)
{}

// With filtering (when n parameter fixed)
{
  "n": 50,
  "filter": { "status": "error", "agent": "Scribe" }
}

// response
{
  "ok": true,
  "entries": [
    {
      "id": "uuid",
      "ts": "2025-10-22 10:21:14 UTC",
      "emoji": "ℹ️",
      "agent": "Scribe",
      "message": "Describe the work or finding",
      "meta": { "phase": "bootstrap" },
      "raw_line": "[ℹ️] [2025-10-22 10:21:14 UTC] [Agent: Scribe] [Project: My Project] Describe the work or finding"
    }
  ]
}

7. rotate_log

Archive the current log and create a fresh file.

// request
{ "suffix": "2025-10-22" }

// response
{ "ok": true, "archived_to": "/abs/.../PROGRESS_LOG.md.2025-10-22.md" }

8. db.persist_entry (optional)

Mirror a freshly written line into Postgres when configured.

// request
{
  "line": "[2025-10-22 ...] ...",
  "project": "IMPLEMENTATION TESTING",
  "sha256": "abc123"
}

// response
{ "ok": true, "id": "uuid" }

9. db.query (optional)

Run predefined parameterized queries against the Scribe database.

// request
{
  "query_name": "recent_failures",
  "params": { "project": "IMPLEMENTATION TESTING", "since_hours": 24 }
}

// response
{ "ok": true, "rows": [ { "ts": "2025-10-22 09:10:03 UTC", "agent": "Scribe", "message": "..." } ] }

10. query_entries - Advanced Log Search

Purpose: Advanced searching and filtering of progress log entries Usage: query_entries([project, start, end, message, message_mode, case_sensitive])

// Search by message content
{
  "message": "bug",
  "message_mode": "substring"
}

// Search by date range
{
  "start": "2025-10-23",
  "end": "2025-10-24"
}

// Search specific project
{
  "project": "My Project",
  "message": "migration",
  "case_sensitive": false
}

// response
{
  "ok": true,
  "entries": [
    {
      "id": "uuid",
      "ts": "2025-10-23 15:30:00 UTC",
      "emoji": "🗄️",
      "agent": "MigrationBot",
      "message": "Completed database migration",
      "meta": { "phase": "deployment", "component": "database" },
      "raw_line": "[🗄️] [...]"
    }
  ]
}

11. generate_doc_templates - Documentation Scaffolding

Purpose: Create/update documentation templates for a project Usage: generate_doc_templates(project_name, [author, overwrite, documents, base_dir])

// Basic request
{
  "project_name": "My New Project",
  "author": "MyAgent"
}

// Select specific documents
{
  "project_name": "My Project",
  "documents": ["architecture", "phase_plan"],
  "overwrite": true
}

// response
{
  "ok": true,
  "files": [
    "/abs/.../ARCHITECTURE_GUIDE.md",
    "/abs/.../PHASE_PLAN.md",
    "/abs/.../CHECKLIST.md",
    "/abs/.../PROGRESS_LOG.md"
  ],
  "skipped": [],
  "directory": "/abs/.../docs/dev_plans/my_new_project"
}

🧾 Tool Argument Cheat Sheet (Runtime Signatures)

This table summarizes the actual MCP parameters Scribe tools accept at runtime. Use this when constructing payloads or when validating third‑party integrations.

• set_project(name, root=None, progress_log=None, author=None, overwrite_docs=False, defaults=None)
• get_project()
• delete_project(name, mode="archive", confirm=False, force=False, archive_path=None, agent_id=None)
• append_entry(message="", status=None, emoji=None, agent=None, meta=None, timestamp_utc=None, items=None, items_list=None, auto_split=True, split_delimiter="\n", stagger_seconds=1, agent_id=None, log_type="progress", config=None)
• read_recent(project=None, n=None, limit=None, filter=None, page=1, page_size=50, compact=False, fields=None, include_metadata=True)
• query_entries(project=None, start=None, end=None, message=None, message_mode=None, case_sensitive=False, emoji=None, status=None, agents=None, meta_filters=None, limit=None, page=1, page_size=50, compact=False, fields=None, include_metadata=True, search_scope=None, document_types=None, include_outdated=False, verify_code_references=False, time_range=None, relevance_threshold=None, max_results=None, config=None)
• manage_docs(action, doc, section=None, content=None, template=None, metadata=None, dry_run=False, doc_name=None, target_dir=None)
• list_projects(limit=5, filter=None, compact=False, fields=None, include_test=False, page=1, page_size=None, status=None, tags=None, order_by=None, direction="desc")
• generate_doc_templates(project_name, author=None, overwrite=False, documents=None, base_dir=None)
• rotate_log(suffix=None, custom_metadata=None, confirm=False, dry_run=False, dry_run_mode="estimate", log_type=None, log_types=None, rotate_all=False, auto_threshold=False, threshold_entries=None, config=None)
• vector_search(project=None, query="", limit=None)

Registry-aware behavior:

• set_project → ensures scribe_projects row and dev_plan rows for core docs; updates last_access_at.
• append_entry (progress logs) → updates last_entry_at and may auto‑promote status from planning→in_progress when core docs + first entry exist.
• manage_docs → updates meta.docs in the registry with baseline/current hashes and doc‑hygiene flags.
• list_projects → surfaces meta.activity (age, recency, staleness_level, activity_score) and meta.docs.flags (e.g., docs_ready_for_work, doc_drift_suspected).

🛠️ CLI Companion (Optional)

python scripts/scribe.py mirrors a subset of MCP tools for shell workflows:

• --list-projects
• --project <name> or --config <path>
• append "Message" --status success --meta key=value
• read --n 20
• rotate --suffix YYYY-MM-DD

Always prefer MCP tool calls from agents; the CLI is for human operators and batch jobs.

🗂️ Dev Plan Document Suite

Each project under .scribe/docs/dev_plans/<slug>/ maintains four synchronized files. Scribe bootstraps them during set_project; agents keep them current.

• ARCHITECTURE_GUIDE.md - Canonical blueprint. Explain the problem, goals, constraints, system design, data flow, and current directory tree. Update immediately when structure or intent changes.
• PHASE_PLAN.md - Roadmap derived from the architecture. Enumerate phases with objectives, tasks, owners, acceptance criteria, and confidence. Keep it aligned with reality.
• CHECKLIST.md - Verification ledger mirroring the phase plan. Each box must link to proof (commit, PR, screenshot, or Scribe entry). Do not invent tasks here.
• PROGRESS_LOG.md - Append-only audit trail written only through append_entry. Include meta keys like phase=, checklist_id=, tests= for traceability. Rotate periodically (~200 entries) using rotate_log.

Workflow Loop

1. set_project -> confirm docs exist.
2. Fill ARCHITECTURE_GUIDE.md, then PHASE_PLAN.md, then CHECKLIST.md.
3. Work in small, logged increments. append_entry after every meaningful action or insight.
4. When plans shift, update the docs first, then log the change.
5. Treat missing or stale documentation as a blocker - fix before coding further.

🔒 Operating Principles

• Always append; never rewrite logs manually.
• Timestamps are UTC; emoji is mandatory.
• Scribe reminders about stale docs or missing logs are blocking alerts.
• Default storage is local SQLite; Postgres and GitHub bridges require explicit env configuration.
• No autonomous prose generation - Scribe stays deterministic and fast.

Repeat: Append entries religiously. If there is no Scribe line, reviewers assume it never happened.