Scribe Integration Guide
Scribe is the persistent audit trail for all Council work. Every significant action must be logged. Unlogged work is invisible to the team and to future agents.
This skill is THE canonical, complete reference for the Scribe MCP tool surface and workflow. It documents every registered Scribe tool (see the Full Tool Reference appendix), the mandatory startup sequence, the logging cadence, the document lifecycle, and bug/security reporting. If you are an agent or host that needs to discover or correctly call Scribe tools, this is the one-stop reference — re-open it any time with
/scribe-integration. For first-time install and connection (getting Scribe running and reachable), see the separate/scribe-onboardingskill; this guide assumes Scribe is already connected.
Evidence Family Boundary
scribe-integrationis the protocol entrypoint for Scribe work (startup sequence, logging cadence, docs lifecycle, bug/security reporting).- Retrieval evidence (semantic search, citations, corpus refresh) belongs to
scribe-rag-workflow. - Runtime/log evidence (daemon/web/process telemetry, incident traces, log-plane checks) belongs to
log-observability. - Browser runtime validation belongs to a dedicated browser-validation skill package; do not expand this skill into browser troubleshooting procedures.
Mandatory Startup Sequence
Before ANY work — reading files, editing code, planning — execute these two calls:
# 1. Activate project (sets context for all subsequent calls)
set_project(agent="<your-name>", name="<project_name>", root="<repo_root>")
# 2. Load recent context (understand what's happened before you)
read_recent(agent="<your-name>", limit=5)
Why this matters:
set_projectensures yourappend_entrycalls go to the right project log- Without
set_project, logs are orphaned in the default project read_recentprevents duplicating work already done- The base Scribe project is only for ephemeral tactical work; once a named workstream exists, stay on it
- Orchestrators must propagate the same active project to every delegated agent instead of silently falling back to the base project
Skip these two steps = your work gets rejected.
Project Binding Is Sticky
set_project is not a per-log call.
- Call
set_projectonce during startup for the active project. - Do not call
set_projectbefore everyappend_entry. - Keep using
append_entry,manage_docs,read_recent, and related Scribe calls on the active project context. - Re-run
set_projectonly when the operator/orchestrator changes the active project, or when anappend_entry/Scribe response indicates sentinel/fallback/base-project mode, project mismatch, or orphaned logging.
Logging with append_entry
Log every 2-3 significant actions. If it's not logged, it didn't happen.
Single Entry
append_entry(
agent="forge",
message="Fixed JWT validation — expiry now checked with 15min grace period",
status="success",
meta={
"reasoning": {
"why": "JWT tokens were accepted after expiry, allowing stale sessions",
"what": "Added expiry check with configurable grace period to auth.py:142",
"how": "Read auth.py scan_only, identified missing check, added with config fallback"
},
"file": "src/council_mcp/web/auth.py",
"line": 142
}
)
Status Levels
| Status | Use For |
|---|---|
info |
Investigation steps, reading files, planning |
success |
Completed work, passing tests, fixes verified |
warn |
Unexpected findings, degraded paths, skipped steps |
error |
Failures, blocked work, tool errors |
bug |
Bug discoveries (triggers bug tracking) |
plan |
Work plans, task decomposition, approach decisions |
Bulk Entries (Backfilling)
When you have multiple actions to log at once:
append_entry(
agent="forge",
items=json.dumps([
{"message": "Scanned auth.py — found JWT validation at line 142", "status": "info"},
{"message": "Identified missing expiry check", "status": "bug",
"meta": {"file": "auth.py:142"}},
{"message": "Added expiry check with 15min grace period", "status": "success"}
])
)
Global Log (Milestones)
For repo-wide milestones (phase completions, major decisions):
append_entry(
agent="atlas",
message="Phase 1 complete — auth system refactor shipped, 44/44 tests pass",
status="success",
log_type="global",
meta={"project": "council_unified_platform", "entry_type": "milestone"}
)
Reasoning Traces (Required)
Every append_entry for significant work MUST include reasoning in meta:
meta={
"reasoning": {
"why": "research goal or decision point that prompted this action",
"what": "constraints, alternatives considered, scope of change",
"how": "methodology, tools used, steps taken"
}
}
Document Management with manage_docs
Frontmatter, Status Intent, Topology, and Scaffold Quality Gates
- Narrative-doc frontmatter changes must use
frontmatter_updatewithmetadata.frontmatter. status_updateis checklist-only; using it on narrative docs must be treated as an intent error (DOC_STATUS_INTENT_MISMATCH).- Checklist item
metadata.statusis item state only; it must not update managed-doc frontmatter lifecyclestatus. - Managed-doc lifecycle status must use Scribe's canonical values:
scaffolded,in_progress,ready,complete,stale,superseded,blocked, orarchived. - Managed-doc frontmatter should include stable
id,doc_type,doc_name,status,summary,owners,tags, and typed topology when relevant. - Human-facing attribution should use display names such as
Forge,Atlas,Witness,Crucible,Blueprint,Arbiter,Loom, andQuill; preserve opaque runtime IDs only as secondary provenance when Scribe provides them. - Scaffold residue means not done; completion/readiness can be blocked with
DOC_NOT_DONE_SCAFFOLD_QUALITY. - Run
quality_checkbefore handoff on managed docs, runquality_handoff_checkbefore clean clock-out/handoff claims, and runproject_healthbefore closeout. - Configured log surfaces, including custom
logs:entries in.scribe/config/scribe.yaml, are not readiness-quality targets.
Quality warnings to treat as authoritative:
SCF_PLACEHOLDER_BRACKETSCF_TEMPLATE_PROSESCF_FAILED_WRITE_RESIDUESCF_EMPTY_FINDINGSCF_UNFILLED_APPENDIXSCF_TODO_ONLY_SECTIONSCF_LOG_TEMPLATE_ONLYSCF_FRONTMATTER_MISMATCHSCF_LIFECYCLE_STATUS_MISMATCHSCF_INDEX_STALESCF_INDEX_MISSINGSCF_DOC_UNINDEXEDSCF_NONCANONICAL_LOCATIONSCF_CHANGELOG_ENTRY_ID_MISSINGSCF_CHANGELOG_ENTRY_ID_INVALIDSCF_CHANGELOG_SUMMARY_MISSINGSCF_CHANGELOG_EVIDENCE_MISSINGSCF_CHANGELOG_DUPLICATE_SOURCE_KEYSCF_CHANGELOG_RAW_PROGRESS_DUMPSCF_CHANGELOG_AMBIGUOUS_BODY_STATUSSCF_CHANGELOG_ESCAPED_NEWLINESSCF_RESEARCH_CONTEXT_DRIFT
Topology and lifecycle warnings to treat as authoritative when present:
TOPOLOGY_MISSING_IDTOPOLOGY_DUPLICATE_IDTOPOLOGY_DANGLING_EDGETOPOLOGY_INVALID_EDGE_SHAPETOPOLOGY_READY_DEPENDS_ON_DRAFTTOPOLOGY_DEPENDENCY_CYCLEDOC_MISSING_SUMMARYDOC_STATUS_INVALIDDOC_STATUS_TRANSITION_BLOCKEDDOC_AGENT_ID_LEAKDOC_REGISTRY_MISSING
Document Topology MCP Usage
Use topology actions to keep the managed corpus deterministic and downstream-safe. These actions belong in normal Scribe workflow; do not invent a second registry, validator, semantic linker, or retrieval pipeline inside Scribe.
manage_docs(
agent="witness",
action="topology_scan",
dry_run=True
)
manage_docs(
agent="witness",
action="metadata_scan",
dry_run=True
)
manage_docs(
agent="forge",
action="metadata_repair",
metadata={"mode": "repair_safe"},
dry_run=False
)
manage_docs(
agent="witness",
action="ingestion_manifest_inspect",
dry_run=True
)
Repair modes:
report_only: produce findings and perform no writes.repair_safe: apply deterministic fixes only, such as generated IDs, canonical missing status, scalar-to-list normalization, and safe metadata shells.repair_assisted: produce an operator/agent review plan for ambiguous fixes.
Topology fields:
depends_onsupportsvalidatessupersedesblocked_bytouchesrelated_docs
Downstream export boundary:
- Scribe may generate sanitized local artifacts such as
doc_topology.json,work_topology.json, anddownstream_ingestion_manifest.jsonunder.scribe/indexes/. - These artifacts are derived outputs, not a second source of truth.
- Downstream consumers may build retrieval or graph systems from them; Scribe itself must stay deterministic and must not add embeddings, transformer classification, semantic guessing, or graph-RAG behavior.
Canonical research/index guidance:
- Keep research docs in flat
.scribe/docs/dev_plans/<project>/research/. - Maintain
research/INDEX.mdas the canonical index surface. - Treat noncanonical, stale, orphaned, or unindexed research states as warnings that must be resolved before done-state claims.
- Research docs for a named workstream must be created in the active Scribe project. A research artifact written to the repo root, base project, wrong dev-plan folder, wrong filename prefix, or another Scribe project is not accepted evidence.
- If a research doc lands in the wrong location/project, BLOCK downstream routing and use Scribe
manage_docs(action="rehome_doc", metadata={"target_project": "<active_project>"})or the dedicated Scribe rehome-doc tool if exposed. Do not move managed docs with shellmv,cp, ad hoc file writes, or git-only renames. - If
manage_docs(create)lands a research artifact in the wrong place, rehome it before writing substantive content. The clean sequence is create -> verify path/project -> rehome if needed -> write body -> quality_check -> index/readback. - Scribe quality checks are necessary but not sufficient. Coordinator/Witness should also scan for scaffold residue, duplicate headings, stale body status, noncanonical paths, escaped-newline sludge, and index drift before accepting research.
Project-level artifact guidance:
- Research docs belong in
research/INDEX.md. - Synthesis, review, architecture, phase-plan, checklist, and changelog documents are project-level artifacts, not research docs.
- Do not force synthesis/review/project-level docs into
research/INDEX.md; rely on project-level artifact health and quality surfaces.
Frontmatter Update MCP Usage
Use this for narrative-doc metadata, not checklist progress:
manage_docs(
agent="blueprint",
action="frontmatter_update",
doc_name="ARCHITECTURE_GUIDE",
metadata={
"frontmatter": {
"status": "ready",
"owners": ["blueprint"],
"summary": "Architecture plan ready for Witness review"
}
},
dry_run=True
)
Re-run with dry_run=False only after the preview shows the intended frontmatter keys. created_by and edit_trace are reserved lifecycle fields; do not try to author them manually.
Quality Check MCP Usage
Use this before handoff on managed docs:
manage_docs(
agent="witness",
action="quality_check",
doc_name="ARCHITECTURE_GUIDE",
dry_run=True
)
Treat blocking warnings as unfinished work. Lifecycle/status mismatch and changelog escaped-newline warnings are blockers, not cosmetic notes.
Quality Handoff MCP Usage
Use this before claiming clean handoff, completion, or clock-out for managed-doc work:
manage_docs(
agent="witness",
action="quality_handoff_check",
dry_run=True
)
If handoff_allowed is false, fix the listed managed docs before handing work back. Scaffold placeholders, failed-write residue, unresolved blockers, and serious topology warnings are not acceptable final-state paperwork.
Planning Doc Ownership vs Checklist Proof
- The coordinator may create and update the managed pre-research
SPECdoc with the operator. - That
SPECis problem-definition only: problem, goals, non-goals, constraints, and research questions. It is not an architecture doc, phase plan, or task package. - A usable
SPECis concrete enough that Lens can answer it; if the open questions are mushy or solution-biased, keep refining before research starts. - Blueprint owns planning-content updates in
ARCHITECTURE_GUIDE,PHASE_PLAN, and the planning structure ofCHECKLISTfor non-trivial named work. - The active coordinator owns verification evidence plus
CHECKLISTstatus/proof after task packages complete. SPECis the only coordinator-owned planning artifact before Blueprint runs.- Do not rewrite planning docs after every package-level correction. Update checklist status/proof for completed packages, and only route planning-doc rewrites when broader plan boundaries change.
- In named Scribe projects, no code may continue when direction/scope has deviated from the documented plan. Either correct execution back to plan immediately or update the plan first.
- If major reshaping or new phases are required mid-stream, open a new named Scribe project and run a fresh planning cycle instead of overwriting prior planning docs in place.
Critical Rule: create is NOT enough
manage_docs(action="create") scaffolds an empty document template. You MUST follow it with replace_section calls to write actual content.
# Step 1: Create the scaffold (empty doc)
manage_docs(
agent="lens",
action="create",
doc_name="RESEARCH_AUTH_PATTERNS",
metadata={
"doc_type": "research",
"research_goal": "Understand existing auth patterns before refactoring"
}
)
# Step 2: ALWAYS follow with replace_section for each section
manage_docs(
agent="lens",
action="replace_section",
doc_name="RESEARCH_AUTH_PATTERNS",
section="findings",
content="""## Auth Pattern Findings
JWT validation lives in `src/council_mcp/web/auth.py:142`.
Current flow: token decode → signature check → expiry NOT checked.
Grace period config key: `council.auth.token_grace_seconds` (missing from DEFAULT_CONFIG).
"""
)
manage_docs(
agent="lens",
action="replace_section",
doc_name="RESEARCH_AUTH_PATTERNS",
section="recommendations",
content="Add expiry check with configurable grace period. Add key to DEFAULT_CONFIG."
)
Built-In create Doc Types
doc_type |
Use For | Sections |
|---|---|---|
research |
Lens investigation output | findings, recommendations, confidence |
bug |
Bug reports | symptoms, root_cause, fix, verification |
security |
Security reports | findings, severity, remediation |
review |
Review or audit reports | summary, findings, verdict |
agent_card |
Persona / agent documentation | role, capabilities, constraints |
custom |
Council-specific managed docs such as a pre-research SPEC |
user-defined |
Standard Scaffold Families
These are the common generated project-doc surfaces used by Scribe tooling:
| Scaffold | Use For |
|---|---|
architecture |
Design docs |
phase_plan |
Phase plans |
checklist |
Task tracking |
progress_log |
Workstream progress trail |
doc_log |
Documentation change trail |
security_log |
Security-specific tracking |
bug_log |
Bug-specific tracking |
changelog |
Curated project outcome history |
For generic test organization, naming, markers, and placement across codebases, use /test-taxonomy.
Changelog and Version Context
Use changelogs for accepted outcomes, not raw progress-log dumps.
- Author curated entries in the project
CHANGELOG.md. - Treat
.scribe/docs/GLOBAL_CHANGELOG.mdas derived output only. - Reconcile global entries only from project entries with
entry_status: accepted. - Run
quality_checkbefore reconciliation. - Run
preview_reconciliationbeforeapply_global_changelog. - Preview and quality actions diagnose; they do not perform hidden mutation.
Required accepted-entry fields:
entry_identry_statussummaryevidence_refs
Identity and dedupe:
entry_idformat:<yyyymmdd>:<slug>- source key:
(project_slug, entry_id)
Status boundary:
entry_statusis changelog-entry state only.- Managed-doc frontmatter lifecycle
statusremains separate and must be repaired throughfrontmatter_update. - Body prose such as
Status: acceptedinside changelog entries is ambiguous; prefer explicitentry_status.
Version/context behavior is advisory:
- Scribe observes context from manual metadata first, then
pyproject.toml, then optional git fallback, thenunknown. - There is no SemVer enforcement, no auto-bump, and no hidden release management.
- Missing/unknown version context is allowed and non-blocking.
- Historical research context can warn as drifted without overriding active code as source of truth.
Escaped-newline rule:
- A project
CHANGELOG.mdmust be real multiline markdown. - Literal serialized
\nsludge in changelog content is a blockingSCF_CHANGELOG_ESCAPED_NEWLINESquality failure. - Fix it by rewriting the changelog with real newlines, not by suppressing the warning.
Editing Documents: Prefer apply_patch
apply_patch is the primary edit action. It uses context matching (not bare line numbers) so it handles document drift gracefully. Always dry_run=True first.
Unified diff mode (recommended for most edits)
# Apply a unified diff — context lines anchor the edit even if line numbers drifted
manage_docs(
agent="forge",
action="apply_patch",
doc_name="architecture",
patch="""--- before
+++ after
@@ -5,3 +5,4 @@
## Components
Current auth uses basic JWT decode.
+Added expiry validation with 15s grace period.
""",
dry_run=True # ALWAYS dry_run first, then re-run with dry_run=False
)
Structured edit mode (for targeted line/section replacement)
# Replace a specific section by anchor
manage_docs(
agent="forge",
action="apply_patch",
doc_name="architecture",
edit={"type": "replace_section", "section": "findings", "content": "Updated findings..."}
)
# Replace a block by anchor marker
manage_docs(
agent="forge",
action="apply_patch",
edit={"type": "replace_block", "anchor": "<!-- ID: constraints -->", "content": "New constraints..."},
doc_name="architecture"
)
Why apply_patch over replace_range:
- Context lines act as anchors even when line numbers shift
- Smart 3-tier matching: exact position, frontmatter offset, then full-document search
- Clear diagnostics when context doesn't match
- Handles multi-hunk patches atomically
Other Edit Actions
replace_range (when you know exact line numbers)
Line number coordinate system: By default, replace_range called via the MCP tool uses file-relative line numbers (matching what read_file returns). This means you can use line numbers directly from scan_only or line_range output.
# Line numbers from read_file work directly
manage_docs(
agent="forge",
action="replace_range",
doc_name="phase_plan",
start_line=45, # file-relative (includes frontmatter in count)
end_line=50,
content="New content for these lines"
)
# For body-relative line numbers (legacy behavior, excludes frontmatter):
manage_docs(
agent="forge",
action="replace_range",
doc_name="phase_plan",
start_line=5,
end_line=10,
content="Body-relative replacement",
metadata={"line_reference": "body"}
)
replace_text (find/replace with pattern matching)
# Literal find/replace (default)
manage_docs(
agent="forge",
action="replace_text",
doc_name="architecture",
metadata={"find": "old_term", "replace": "new_term", "replace_all": True}
)
# Regex mode
manage_docs(
agent="forge",
action="replace_text",
doc_name="architecture",
metadata={"find": r"v\d+\.\d+", "replace": "v2.3", "match_mode": "regex"}
)
# Scoped to a section
manage_docs(
agent="forge",
action="replace_text",
doc_name="architecture",
metadata={"find": "TODO", "replace": "DONE", "scope": "section:findings"}
)
append (add content to end of doc or section)
# Append to a section (inside = immediately after anchor)
manage_docs(
agent="forge",
action="append",
doc_name="architecture",
section="constraints",
content="- New constraint added",
metadata={"position": "inside"} # "before" | "inside" | "after" (default)
)
Checklist Updates
# Mark a checklist item as done (with proof)
manage_docs(
agent="forge",
action="status_update",
doc_name="checklist",
section="task_auth_fix",
metadata={"status": "done", "proof": "tests/test_auth.py::test_jwt_expiry PASSED"}
)
section may be a heading/section id or an inline item id such as <!-- id: p4-task-3 -->.
The helper should update exactly the targeted checklist item. If it appends a duplicate item, rewrites neighboring items, or cannot find an existing inline id, treat that as tool friction and fix/report it before final handoff.
Bug Reporting
Every discovered bug MUST be logged immediately in the active Scribe trail; never hide, defer, or silently absorb discovery. This immediate-visibility rule applies to every agent; it does not transfer Mantis's diagnosis/repair authority to other roles.
Tiny in-contract defects remain attached to the active work item and current Scribe trail and are corrected through the active owner/validation loop. They do not automatically require open_bug, a standalone report, or a link_fix lifecycle.
Open a durable case immediately when severity, recurrence, cross-session coordination, security significance, knowledge value, operator direction, or Atlas routing warrants it. Preserve Mantis's diagnosis/repair authority for unknown, intermittent, flaky, runtime, startup, state-sensitive, or recurrence-prone failures; this policy changes case activation and ceremony only, not tool or runtime semantics.
After the durable-case threshold is met, preserve the complete evidence, report, and fix-link lifecycle:
# Step 1: Open the durable case
open_bug(
agent="forge",
title="JWT tokens accepted after expiry",
symptoms="Authenticated requests succeed with tokens expired >24h ago",
category="logic" # logic | runtime | config | data | integration | performance
)
# Step 2: Create the bug report doc scaffold
manage_docs(
agent="forge",
action="create",
metadata={
"doc_type": "bug",
"category": "logic",
"slug": "jwt-expiry-not-checked",
"severity": "high", # critical | high | medium | low
"title": "JWT tokens accepted after expiry"
}
)
# Step 3: Write each section
manage_docs(
agent="forge",
action="replace_section",
doc_name="jwt-expiry-not-checked",
section="symptoms",
content="Authenticated requests succeed with JWT tokens expired >24 hours ago. No error returned."
)
manage_docs(
agent="forge",
action="replace_section",
doc_name="jwt-expiry-not-checked",
section="root_cause",
content="auth.py:142 — `_validate_token()` checks signature but not `exp` claim. JWT decode uses `verify_exp=False`."
)
manage_docs(
agent="forge",
action="replace_section",
doc_name="jwt-expiry-not-checked",
section="fix",
content="Set `verify_exp=True` in jwt.decode() call. Add 15s grace period via `council.auth.token_grace_seconds`."
)
# Step 4: Link the fix when resolved
link_fix(
agent="forge",
case_id="BUG-jwt-expiry-not-checked",
artifact_ref="src/council_mcp/web/auth.py:142",
landing_status="merged"
)
File Reading with read_file
RULE: ALWAYS scan before you read. Never load entire large files.
Step 1: Scan First
# Get structure without loading content — cheap and fast
read_file(
agent="forge",
path="src/council_mcp/web/auth.py",
mode="scan_only",
include_dependencies=True # shows imports and dependency graph
)
The scan returns class names, function names, and line numbers. Use these to target your reads.
Step 2: Read Only What You Need
# Read a specific range (from line numbers in the scan)
read_file(
agent="forge",
path="src/council_mcp/web/auth.py",
mode="line_range",
start_line=130,
end_line=165
)
Read Modes
| Mode | Use For | Cost |
|---|---|---|
scan_only |
Structure overview, line numbers, imports | Cheapest |
line_range |
Specific function or class | Cheap |
chunk |
Sequential chunks (chunk_index=[0,1,2]) | Medium |
page |
Paginated reading (page_number, page_size) | Medium |
search |
Pattern search within file | Medium |
full_stream |
Entire file (only for small files) | Expensive |
Cross-Repo Reading
read_file(
agent="forge",
path="/home/user/projects/scribe_mcp/src/server.py",
mode="scan_only",
include_dependencies=True,
allow_outside_repo=True # REQUIRED for paths outside current repo
)
Search Patterns
Search Codebase (Regex)
search(
agent="forge",
pattern="class.*Manager", # Regex pattern
glob="**/*.py" # File pattern filter
)
search(
agent="forge",
pattern="_get_active_council_id",
glob="src/**/*.py"
)
Search Log History
# Find recent entries about a topic
query_entries(
agent="forge",
message="JWT", # Search term
message_mode="substring" # Substring match
)
Anti-Patterns
Wrong — Creating a doc without writing content
# WRONG: create alone produces an empty document
manage_docs(agent="forge", action="create", doc_name="RESEARCH_X", metadata={...})
# Nothing was written — doc is empty
Right — Create then replace_section
manage_docs(agent="forge", action="create", doc_name="RESEARCH_X", metadata={...})
manage_docs(agent="forge", action="replace_section",
doc_name="RESEARCH_X", section="findings", content="Actual findings here...")
Wrong — Using replace_range for multi-step document edits
# WRONG: line numbers drift between calls, second edit hits wrong lines
manage_docs(action="replace_range", doc_name="arch", start_line=10, end_line=15, content="...")
manage_docs(action="replace_range", doc_name="arch", start_line=20, end_line=25, content="...")
Right — Use apply_patch with context matching
# RIGHT: context lines anchor each hunk independently
manage_docs(action="apply_patch", doc_name="arch", patch="..unified diff..", dry_run=True)
Wrong — Skipping set_project
# WRONG: logs go to wrong project or fail silently
append_entry(agent="forge", message="Did something important", status="success")
Right — Always set_project first
set_project(agent="forge", name="my_project", root="/path/to/repo")
append_entry(agent="forge", message="Did something important", status="success")
Wrong — Reading entire large files
# WRONG: loads 800 lines when you need 20
read_file(agent="forge", path="src/big_file.py", mode="full_stream")
Right — Scan then target
read_file(agent="forge", path="src/big_file.py", mode="scan_only")
# See line 142 has _validate_token()
read_file(agent="forge", path="src/big_file.py", mode="line_range", start_line=140, end_line=165)
Wrong — Not calling read_recent before work
# WRONG: starting blind, may duplicate work already done
set_project(agent="forge", name="my_project", root="/path/to/repo")
# Immediately starts coding without checking recent progress
Right — Always check recent context
set_project(agent="forge", name="my_project", root="/path/to/repo")
read_recent(agent="forge", limit=5) # Load what's already been done
# NOW start working
Full Tool Reference
This appendix enumerates every Scribe MCP tool the server registers, so an agent or host can discover the entire surface from this skill alone. The deep workflow sections above cover the core tools in detail; this table is the complete inventory. Tools are surfaced to hosts as mcp__scribe__<name> (the prefix depends on how the server is registered in your client).
Trust tiers come from each tool's contract wrapper and drive the MCP annotations a host sees:
| Tier | annotations |
Meaning |
|---|---|---|
| read-only | readOnlyHint: true |
Reads/inspects only; never mutates state |
| additive (write) | idempotentHint/append semantics |
Appends new records (logs, cases, events); does not rewrite existing state |
| stateful (write) | write, non-destructive | Mutates project/session/doc/reminder state in place |
| destructive (write) | destructiveHint: true |
Removes or resets data; use deliberately |
Install/connection is NOT in this skill. Getting Scribe installed and reachable (
pip install scribe-mcp, the one-command local-Postgres wizard, env vars) lives in the separate/scribe-onboardingskill. Everything below assumes Scribe is already connected.
Project & Context
| Tool | Tier | Purpose / When to use |
|---|---|---|
set_project |
stateful | Bind the active project context for this session. First call of every session. Sticky — call once, not per log. |
get_project |
read-only | Return the active project selection (resolving defaults). Use to confirm what context you're bound to. |
list_projects |
read-only | List projects registered for the current repo (or all repos with global_mode=True). Use to find an existing workstream. |
delete_project |
destructive | Delete or archive a project and all associated data. Deliberate cleanup only. |
authorize_repo_root |
stateful | Issue a session-bound grant authorizing a bind to an external repository root. Needed before working outside the primary repo root. |
Logging & Log Inspection
| Tool | Tier | Purpose / When to use |
|---|---|---|
append_entry |
additive | Record an audit-trail log entry (single or bulk). Log every 2-3 significant actions. The primary "record what I did" tool. |
read_recent |
read-only | Load the most recent project log entries. Second call of every session (rehydrate before working). |
query_entries |
read-only | Search the project log history by message/term. Use to find prior work on a topic. |
progress_log_projection |
read-only | Public-safe readiness/render projection of the progress or doc-update log without mutating canonical logs. |
analyze_logs |
read-only | Log-intelligence analysis over a given log file path. Inspection only. |
rotate_log |
stateful | Rotate one or more project log files with integrity guarantees. Maintenance/admin. |
Documents
| Tool | Tier | Purpose / When to use |
|---|---|---|
manage_docs |
stateful | The document-governance router: create scaffolds, replace_section, apply_patch, status_update, frontmatter_update, quality_check, topology, changelog, and more. See the deep section above. |
generate_doc_templates |
additive | Render the standard project doc templates (architecture, phase plan, checklist, logs). Overwrites blocked unless force=True; progress logs always preserved. |
Bugs, Security & Traceability
| Tool | Tier | Purpose / When to use |
|---|---|---|
open_bug |
additive | Open a durable bug case (per-day stable ID) and scaffold its report doc after the durable-case threshold is met. Every discovery is still logged immediately in the active Scribe trail. |
open_security |
additive | Open a security case (per-day stable ID) and scaffold a detailed security report doc. |
list_open_cases |
read-only | List open bug/security cases from the shared case registry (filter by type/project/repo). |
link_fix |
additive | Link a fix artifact (file.py:line) to a case with a landing status (e.g. merged). |
append_event |
additive | Append a general sentinel event to sentinel.jsonl (append_entry-compatible args). Sentinel-mode logging. |
File Reading & Search
| Tool | Tier | Purpose / When to use |
|---|---|---|
read_file |
read-only | Structured code reading. Always scan_only first, then line_range/chunk/page/search/full_stream. See the deep section above. |
edit_file |
stateful | Safe exact-string file editing. Requires a prior read_file on the path this session; dry_run=True by default — set False to commit. |
search |
read-only | Regex search across the codebase with a glob filter. |
Reminders
| Tool | Tier | Purpose / When to use |
|---|---|---|
query_reminders |
read-only | Query reminder history and currently active reminders for a project. |
configure_reminders |
stateful | Configure reminder behavior (cadence/categories) for a project. |
reset_reminders |
destructive | Reset reminder cooldowns and/or reminder history for a project. |
Diagnostics & Runtime (mostly internal)
| Tool | Tier | Purpose / When to use |
|---|---|---|
scribe_doctor |
read-only | Runtime diagnostics for the current MCP server instance (config, roots, backend health). Run when Scribe behaves unexpectedly. |
read_write_barrier_state |
read-only | Public-safe Scribe write-barrier state for the active repo. |
scribe_owned_write_barrier_acquire_release_proof |
stateful | Acquire/release proof for the Scribe-owned write barrier. Internal coordination/proof tool. |
scribe_private_context_selector_readback |
read-only | Emit public-safe selector/readback labels without runtime or target contact. Internal proof tool. |
scribe_local_postgres_readiness_roundtrip_preflight |
read-only | Public-safe local-Postgres readiness roundtrip preflight. Internal readiness check. |
health_checkis also registered but is an internal liveness probe — hosts generally do not surface it for agent use.
Quick usage for the useful-but-undocumented tools
The core workflow tools are covered in depth above. The snippets below cover the genuinely useful tools that the workflow sections don't already demonstrate.
# Confirm / discover project context
get_project(agent="forge") # what am I bound to?
list_projects(agent="forge") # existing workstreams in this repo
list_projects(agent="forge", global_mode=True) # across all repos
# Security case (parallel to open_bug)
open_security(
agent="sentinel",
title="Auth token logged in plaintext",
symptoms="session_token appears in web_ui.log at INFO",
severity="high", # critical | high | medium | low
category="data",
)
# then replace_section findings/severity/remediation, like a bug report
# See what cases are open
list_open_cases(agent="forge") # all open bug + security cases
list_open_cases(agent="forge", case_type="bug") # filter by type
# Safe file edit (read_file first, dry_run preview, then commit)
read_file(agent="forge", path="src/auth.py", mode="line_range", start_line=140, end_line=160)
edit_file(agent="forge", path="src/auth.py",
old_string="verify_exp=False", new_string="verify_exp=True",
dry_run=True) # preview; re-run with dry_run=False to commit
# Diagnose a misbehaving Scribe
scribe_doctor(agent="forge") # config, roots, backend health
# Reminders
query_reminders(agent="forge") # active reminders + history
configure_reminders(agent="forge", metadata={"stale_after_hours": 24})
Tool count: 30 registered tools (this appendix lists every one). The reference above is verified against the server's @app.tool registrations — if the surface changes, regenerate this skill from its .j2 source rather than hand-editing the generated .md.