archgate · rhuanbarreto · Feb 24, 2026 · Feb 24, 2026 · Feb 24, 2026
@@ -49,7 +49,7 @@ Use three exit codes with clear semantics:
 - Write errors to stderr (via `logError()`), not stdout
 - **MCP tools MUST return structured JSON guidance when prerequisites are missing** — use `noProjectResponse()` from `src/mcp/tools/no-project.ts`, which returns `{ error, message, action }` where `action` directs the AI agent to the recovery step (e.g., "Invoke the `@archgate:onboard` skill")
 - **The MCP server MUST start even when no project is found** — `startStdioServer()` and `createMcpServer()` accept `string | null` for `projectRoot`; the `mcp` command passes `findProjectRoot()` directly (which returns `null`) rather than guarding with `process.exit(1)`
-- **MCP tools that don't depend on `.archgate/` MUST fall back to `process.cwd()`** when `projectRoot` is null — e.g., `session_context` reads from `~/.claude/projects/` and uses `process.cwd()` as its path key when no project is found
+- **MCP tools that don't depend on `.archgate/` MUST fall back to `process.cwd()`** when `projectRoot` is null — e.g., `claude_code_session_context` reads from `~/.claude/projects/` and uses `process.cwd()` as its path key when no project is found
 
 ### Don't
 
@@ -135,7 +135,7 @@ async ({ adrId, staged }) => {
 };
 
 // GOOD: tool that doesn't need .archgate/ falls back to cwd
-// src/mcp/tools/session-context.ts
+// src/mcp/tools/claude-code-session-context.ts
 const encodedPath = encodeProjectPath(projectRoot ?? process.cwd());
 ```
 

@@ -59,7 +59,7 @@ Skipping steps 2 or 3 is a workflow violation. The user should NEVER have to inv
 
 ## MCP Tools Structure
 
-- MCP tools live in `src/mcp/tools/` — one file per tool (check, list-adrs, review-context, session-context)
+- MCP tools live in `src/mcp/tools/` — one file per tool (check, list-adrs, review-context, claude-code-session-context)
 - ADR CRUD moved to CLI: `archgate adr create`, `archgate adr update`, `archgate init` (no longer MCP tools)
 - `src/mcp/tools/index.ts` composes all registrations via `registerTools()` (contains real logic, not a barrel per ARCH-004)
 - `src/mcp/server.ts` imports from `./tools/index`

@@ -102,7 +102,7 @@ src/
         ├── check.ts        # check tool
         ├── list-adrs.ts    # list_adrs tool
         ├── review-context.ts   # review_context tool
-        └── session-context.ts  # session_context tool
+        └── claude-code-session-context.ts  # claude_code_session_context tool
 tests/                      # Mirrors src/ structure
 .archgate/adrs/             # Self-governance ADRs
 ```

@@ -185,12 +185,12 @@ archgate mcp
 
 Exposes four tools to MCP-compatible clients (Claude Code, Cursor, etc.):
 
-| Tool              | Description                                                       |
-| ----------------- | ----------------------------------------------------------------- |
-| `check`           | Run ADR compliance checks, optionally on staged files only        |
-| `list_adrs`       | List all ADRs with metadata                                       |
-| `review_context`  | Get changed files grouped by domain with applicable ADR briefings |
-| `session_context` | Read the current Claude Code session transcript                   |
+| Tool                          | Description                                                       |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `check`                       | Run ADR compliance checks, optionally on staged files only        |
+| `list_adrs`                   | List all ADRs with metadata                                       |
+| `review_context`              | Get changed files grouped by domain with applicable ADR briefings |
+| `claude_code_session_context` | Read the current Claude Code session transcript                   |
 
 Also exposes `adr://{id}` resources for reading individual ADRs by ID.
 

@@ -73,7 +73,7 @@ The governance loop above describes _what_ happens, but not _who drives it_. In
 - The `plugin/` directory ships with the CLI and provides Claude Code integration
 - Plugin skills (`@architect`, `@quality-manager`, `@adr-author`) define governance roles
 - A developer agent (`agents/developer.md`) orchestrates the full governance workflow
-- MCP tools (`check`, `list_adrs`, `review_context`, `session_context`) connect Claude Code to the archgate CLI
+- MCP tools (`check`, `list_adrs`, `review_context`, `claude_code_session_context`) connect Claude Code to the archgate CLI
 - The `review_context` MCP tool pre-computes domain-grouped ADR briefings for efficient AI review
 
 The critical insight: **the MCP tools and CLI commands are passive capabilities**. The _workflow_ — the ordering, gates, and roles — lives in the plugin's agent and skills. Without the plugin, the tools exist but nothing tells the AI _when_ and _how_ to use them.

@@ -90,7 +90,7 @@ The CLI has evolved from a v0.1.0 scaffolding tool to a full governance engine.
 
 - [x] **T2.1** Implement `archgate mcp` command
   - `src/mcp/server.ts` + `src/mcp/tools/` + `src/mcp/resources.ts`
-  - Tools: `check`, `list_adrs`, `review_context`, `session_context`
+  - Tools: `check`, `list_adrs`, `review_context`, `claude_code_session_context`
   - Resources: `adr://{id}` for full ADR markdown
   - Stdio transport via `startStdioServer()`
   - `src/engine/context.ts` provides shared review context logic (section extraction, file-to-ADR matching)
@@ -134,7 +134,7 @@ The CLI has evolved from a v0.1.0 scaffolding tool to a full governance engine.
 
 - [x] **T2.5.4** Rich review context via MCP
   - `review_context` MCP tool — pre-computes domain-grouped ADR briefings (Decision + Do's/Don'ts only)
-  - `session_context` MCP tool — extracts Claude Code session transcripts for context recovery
+  - `claude_code_session_context` MCP tool — extracts Claude Code session transcripts for context recovery
   - `src/engine/context.ts` — shared context building logic (section extraction, file-to-ADR matching)
 
 - [x] **T2.5.5** Shared helper modules
@@ -205,7 +205,7 @@ Phase 1 (Check Engine) ✅
   T1.7 Self-dogfood ✅
 
 Phase 2 (AI Integration) ✅ PIVOTED
-  T2.1 MCP server (check, list_adrs, review_context, session_context) ✅
+  T2.1 MCP server (check, list_adrs, review_context, claude_code_session_context) ✅
   T2.2 Review ── PIVOTED to plugin @architect skill
   T2.3 Capture ── PIVOTED to plugin @quality-manager skill
   T2.4 Skill generation ── REMOVED (replaced by review_context MCP tool)

@@ -24,7 +24,7 @@ The CLI is developed using its own governance model. The ADR format, check engin
 
 | Choice               | Technology                       | Rationale                                                                                                                                                                                              |
 | -------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Integration Protocol | **MCP (Model Context Protocol)** | The `archgate mcp` server exposes tools (check, list_adrs, review_context, session_context) and resources (adr://{id}) to any MCP-compatible client. Uses `@modelcontextprotocol/sdk`.                 |
+| Integration Protocol | **MCP (Model Context Protocol)** | The `archgate mcp` server exposes tools (check, list_adrs, review_context, claude_code_session_context) and resources (adr://{id}) to any MCP-compatible client. Uses `@modelcontextprotocol/sdk`.     |
 | AI Features          | **Claude Code Plugin**           | Role-based skills (architect, quality-manager, adr-author) and developer agent delivered as a Claude Code plugin (`plugin/`). Claude Code handles all AI interactions — no direct Anthropic API calls. |
 | Multi-LLM (future)   | **MCP-based**                    | Any MCP-compatible AI client can use archgate MCP tools. Not locked to a single provider.                                                                                                              |
 
@@ -108,7 +108,7 @@ archgate/cli/
 │   │       ├── check.ts
 │   │       ├── list-adrs.ts
 │   │       ├── review-context.ts
-│   │       └── session-context.ts
+│   │       └── claude-code-session-context.ts
 │   ├── formats/                 # Zod schemas + parsers (single source of truth)
 │   │   ├── adr.ts               # ADR frontmatter schema, parsing, validation
 │   │   └── rules.ts             # Rule file schema + defineRules()
@@ -264,12 +264,12 @@ archgate check
 
 ### Tools
 
-| Tool              | Description                                                                    | Input                   |
-| ----------------- | ------------------------------------------------------------------------------ | ----------------------- |
-| `check`           | Run ADR compliance checks                                                      | `adrId?`, `staged?`     |
-| `list_adrs`       | List all active ADRs with metadata                                             | `domain?`               |
-| `review_context`  | Pre-compute review context: changed files grouped by domain with ADR briefings | `staged?`, `runChecks?` |
-| `session_context` | Read Claude Code session transcript for context recovery                       | `maxEntries?`           |
+| Tool                          | Description                                                                    | Input                   |
+| ----------------------------- | ------------------------------------------------------------------------------ | ----------------------- |
+| `check`                       | Run ADR compliance checks                                                      | `adrId?`, `staged?`     |
+| `list_adrs`                   | List all active ADRs with metadata                                             | `domain?`               |
+| `review_context`              | Pre-compute review context: changed files grouped by domain with ADR briefings | `staged?`, `runChecks?` |
+| `claude_code_session_context` | Read Claude Code session transcript for context recovery                       | `maxEntries?`           |
 
 ### Resources
 
@@ -305,7 +305,7 @@ The developer agent is the entry point. It enforces a strict workflow:
 4. **VALIDATE** — Runs `check` MCP tool + invokes `@architect` skill for structural compliance
 5. **CAPTURE** — Invokes `@quality-manager` skill to capture learnings and propose new ADRs
 
-The MCP tools (`check`, `list_adrs`, `review_context`, `session_context`) provide the data layer. The skills provide the judgment layer. The agent provides the orchestration layer.
+The MCP tools (`check`, `list_adrs`, `review_context`, `claude_code_session_context`) provide the data layer. The skills provide the judgment layer. The agent provides the orchestration layer.
 
 ---
 
@@ -391,6 +391,6 @@ All migration steps have been executed:
 - [x] Added: `src/engine/context.ts` (review context building for AI tools)
 - [x] Added: `src/helpers/adr-writer.ts`, `claude-settings.ts`, `init-project.ts` (shared logic)
 - [x] Added: `src/commands/adr/update.ts` (complete ADR lifecycle)
-- [x] Added: `src/mcp/tools/` directory with `review-context.ts`, `session-context.ts` (rich AI context)
+- [x] Added: `src/mcp/tools/` directory with `review-context.ts`, `claude-code-session-context.ts` (rich AI context)
 - [x] Added: `.archgate/` self-governance directory with 6 ADRs + rules
 - [x] Added: `tests/` with comprehensive test coverage (30+ test files)