scribe-mcp-usage

What this skill does

## ✅ 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`