Documentation

How to adopt Anchor.

One journey from install to first successful coordination. The Anchor website is everything you need to adopt and use Anchor. Portfolio and case-study pages are the design story — not required for adoption.

Getting Started

Install. Initialize. Then connect.

Follow these steps in order. After init, your AI host is not connected yet — that is the next step, not magic pickup of .anchor/config.json.

.anchor/config.json declares what your project coordinates. The Anchor runtime uses that declaration once your AI host is configured to invoke its capabilities.

1. 01

   Install Anchor

   npm install -g @jon4ohio/anchor-runtime

   Verify with anchor help (there is no --help flag).

2. 02

   Initialize your project

   cd your-project
   anchor init

   Creates .anchor/config.json and declares capability use. It does not activate your coding agent.

   CLI next step points here: Connect your AI host.

3. 03

   Connect your AI host

   Configure Cursor, Claude Code, or another MCP host so it exposes the Anchor runtime’s tools.

   Jump to Connect Your AI Host below.

4. 04

   Verify your connection

   Ask: “Orient yourself to this project.” Confirms plumbing — not product value yet.

5. 05

   Complete your first coordination

   Record a durable ADR (or another shipped capability). That is why you installed Anchor.

Ship gate: if a human cannot follow this path on a clean machine, the guide is not ready.

Never document a prompt the MCP cannot fulfill.

Connect

Connect your AI host.

anchor init does not activate your coding agent. Connecting the host exposes the runtime’s MCP tools so the agent can fulfill responsibilities during conversation.

Day-to-day use is through your AI host and these tools — not by hand-running the CLI.

1. 01

   Cursor

   npm install -g @jon4ohio/anchor-runtime
   node -e "console.log(require('path').join(require('child_process').execSync('npm root -g',{encoding:'utf8'}).trim(),'@jon4ohio/anchor-runtime/bin/mcp.js'))"

   {
     "mcpServers": {
       "anchor": {
         "command": "node",
         "args": ["/absolute/path/to/node_modules/@jon4ohio/anchor-runtime/bin/mcp.js"]
       }
     }
   }

   Put the absolute path from the node command into ~/.cursor/mcp.json (or project MCP settings). Restart Cursor / reload MCP if tools do not appear.

2. 02

   Claude Code

   Point Claude Code’s MCP configuration at the same bin/mcp.js using an absolute path from npm root -g. Restart the session so the anchor MCP tools are available.

   Use Claude’s current MCP docs with the same mcpServers JSON shape as Cursor.

3. 03

   Other MCP hosts

   {
     "mcpServers": {
       "anchor": {
         "command": "node",
         "args": ["/absolute/path/to/@jon4ohio/anchor-runtime/bin/mcp.js"]
       }
     }
   }

   Resolve the absolute path with npm root -g (global) or your project’s node_modules (local).

• orient_project → orientation
• generate_handoff → continuity
• record_adr → decision
• run_review → review
• fulfill → any identity (orientation, decision, …)

Verify

Verify your connection.

This step answers one question: Did I configure the AI host correctly?

It does not demonstrate why you installed Anchor — that is Complete Your First Coordination.

1. 01

   Ask your coding agent

   Orient yourself to this project.

   Expected: the agent invokes orient_project (or fulfill with orientation) and works from the orientation methodology — summarizing where durable truths live, or producing Project Entry guidance on a fresh project.

   If the agent cannot see Anchor tools, or invents orientation without the MCP methodology, return to Connect.

First coordination

Complete your first coordination.

This step answers: Why did I install Anchor?

You already proved the plumbing. Here you produce a durable coordination artifact — the product payoff.

1. 01

   Record your first architectural decision

   Ask: Record an ADR explaining a real decision we just made (or a small sample decision for this project).

   Expected: the agent invokes record_adr (or fulfill with decision) and writes ADR-NNN-….md under docs/decisions/ with Context, Decision, alternatives, and Consequences.

2. 02

   Other shipped capabilities

   Generate a handoff for today’s work → generate_handoff → ai/handoff.md updated.

   Review the current implementation → run_review → pass/fail findings reported.

On a clean machine, a human must finish Getting Started → Connect → Verify → this section with every documented prompt fulfilling via MCP.

Concepts

Responsibilities before files.

Knowledge has responsibilities. Contracts formalize those responsibilities. Artifacts implement contracts — they are not the interface.

Seven contracts each own one kind of truth: Entry (orientation), Spec (scope), ADR (decisions), Skill (transferable expertise), Playbook (execution order), Review (quality gates), and Handoff (continuity).

The Capability API exposes engineering responsibilities as stable identities (orientation@1, continuity@1, decision@1, review@1). Clients depend on what to fulfill, not on a directory layout.

• One owner per truth — do not duplicate durable facts across files.
• Reference, don’t restate — link to the contract that owns a truth.
• Promote only after repetition — don’t invent contracts from a single conversation.

Architecture

Stable rationale, not a file tree.

Public architecture is presented by concept — responsibility-first design, product vs framework layers, and capability-as-API — not by ADR number as navigation.

Responsibility-first teaching means adopters discover existing ownership before introducing new structure. Overlay adoption keeps your ADRs and AI context files where they are.

A thin local runtime delivers methodology as versioned knowledge snapshots. The host AI provides inference; project state remains in the adopter’s repository.

Underlying records (ADRs, position papers) support these concepts. They are implementation artifacts for the architecture surface, not the primary way users browse How.

Reference

Runtime commands and behavior.

Once you have begun engineering, these commands describe runtime capabilities. The runtime prepares a workspace and can fulfill declared engineering responsibilities. It does not host inference, own project state, or decide when work should happen.

• anchor help — list commands (no --help flag).
• anchor init — declare capability use (.anchor/config.json); prints next step to Connect.
• anchor list — list capability identities.
• anchor fulfill <identity> — print methodology for a capability (e.g. orientation, decision).
• anchor verify <identity> — check declared outputs.
• MCP aliases: orient_project, generate_handoff, record_adr, run_review, fulfill.

Maturity

Evidence Window open.

Independent adoption evidence is still pending. Maintainer dogfooding and a controlled portfolio experiment support capability claims under labeled conditions — not broad market validation.

The Capability API remains Proposed upstream until acceptance gates clear in real adoption. This Documentation surface is the public How; the implementation workspace is optional for adoption.

Onboarding messaging that separates init from host connection does not by itself close cross-host architecture acceptance (ADR-007).

Product and runtime release notes for users live at /docs/releases — that page is the public source of truth.