visionlog.md

MCP server for long-term project governance. Records vision, goals, guardrails, SOPs, and architectural decisions (ADRs) — the contracts that all execution must honor.

Part of the trilogy: research.md → visionlog.md → ike.md

• research.md earns decisions with evidence
• visionlog.md records them as binding contracts
• ike.md executes within those contracts

What it enforces

• Guardrails are active or deprecated — never deleted
• ADRs are permanent once accepted — a new ADR supersedes, never overwrites
• Goals form a DAG — dependencies must be resolved before a goal is available
• Vision is sticky — it does not drift session to session

Trilogy conventions

visionlog.md follows shared conventions with ike.md and research.md. See CONVENTIONS.md for the full standard.

• Config lives at .visionlog/config.yaml (committed to git)
• Tools: project_init (new project) and project_set (register existing for session)

Install

Not yet published to npm. Install from local path.

npm install
npm run build

Add to .mcp.json:

{
  "mcpServers": {
    "visionlog": {
      "command": "/absolute/path/to/visionlog.md/dist/visionlog",
      "args": ["mcp", "start"]
    }
  }
}

Session protocol

project_set { path: "/path/to/project" }   <- returns project_id
visionlog_boot { project_id: "..." }        <- active guardrails + goal state
visionlog_guide { project_id: "..." }       <- vision + decisions + goal map

Read both visionlog_boot and visionlog_guide at the start of every session before touching any task or code.

Project structure

my-project/
  .visionlog/
    config.yaml          <- project GUID + metadata (commit this)
    vision.md            <- north star, anti-goals, success criteria
    goals/               <- GOAL-NNNN.md — DAG of milestones
    adr/                 <- ADR-NNNN.md — architectural decisions
    guardrails/          <- GUARD-NNNN.md — active constraints
    sops/                <- SOP-NNNN.md — coordination protocols

Tools

Session

Orientation (call at session start)

Vision

Goals

Decisions (ADRs)

Guardrails

SOPs