From b2de0970a1411fe229a3fba882593abc9844fbb5 Mon Sep 17 00:00:00 2001 From: geobelsky Date: Tue, 7 Apr 2026 15:32:04 +0000 Subject: [PATCH] docs: update architecture, README, and diagrams for v0.2.0 - README: add backlog tools (axme_backlog, axme_backlog_add, axme_backlog_update), update storage layout (backlog/, active-sessions/, per-session handoff), add audit-kb and stats CLI commands - ARCHITECTURE.md: add sections for #!axme gate protocol, backlog module, open questions, context pagination, test suite (413 tests/88 suites), repo mode vs workspace mode (D-116), update tool count to 19, update storage layout with backlog/ and open-questions.md - Diagrams: add backlog storage node to overview, architecture, and dot diagrams Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 9 ++- docs/ARCHITECTURE.md | 78 ++++++++++++++++++++++-- docs/diagrams/axme-code-architecture.dot | 3 +- docs/diagrams/axme-code-architecture.mmd | 5 +- docs/diagrams/axme-code-overview.mmd | 3 +- 5 files changed, 88 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index cdc4b19..68617a3 100644 --- a/README.md +++ b/README.md @@ -101,9 +101,11 @@ All data lives in `.axme-code/` in your project root (or workspace root for mult patterns/ # Validated successful approaches safety/ rules.yaml # git + bash + filesystem guardrails + backlog/ # B-001-slug.md ... persistent cross-session task tracking sessions/ # Per-session meta.json (tracking, agentClosed flag) + active-sessions/ # Claude session -> AXME session mapping plans/ - handoff.md # Session handoff (Source: agent or auditor) + handoff-.md # Per-session handoff (last 5 kept) worklog.jsonl # Structured event log worklog.md # Narrative session summaries config.yaml # Model settings, presets @@ -153,6 +155,9 @@ A detached process that reads the session transcript and catches anything the ag | `axme_save_memory` | Save feedback or pattern memory | | `axme_safety` | Show current safety rules | | `axme_update_safety` | Add a new safety rule | +| `axme_backlog` | List or read backlog items (persistent cross-session task tracking) | +| `axme_backlog_add` | Add a new backlog item | +| `axme_backlog_update` | Update backlog item status, priority, or notes | | `axme_status` | Project status (sessions, decisions count, last activity) | | `axme_worklog` | Recent worklog events | | `axme_workspace` | List all repos in workspace | @@ -171,6 +176,8 @@ A detached process that reads the session transcript and catches anything the ag axme-code setup [path] # Initialize project/workspace KB with LLM scan axme-code serve # Start MCP server (called by Claude Code automatically) axme-code status [path] # Show project status (sessions, decisions, memories) +axme-code stats [path] # Worklog statistics (sessions, costs, safety blocks) +axme-code audit-kb [path] # KB audit: dedup, conflicts, compaction axme-code hook pre-tool-use # PreToolUse hook handler (called by Claude Code) axme-code hook post-tool-use # PostToolUse hook handler (called by Claude Code) axme-code hook session-end # SessionEnd hook handler (called by Claude Code) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 92c6d13..84a1581 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,4 +1,4 @@ -1# AXME Code - Architecture +# AXME Code - Architecture ## Overview @@ -9,7 +9,7 @@ AXME Code is an MCP server plugin for Claude Code. Its purpose is to **accumulat ``` +---------------------------------------------+ | MCP Server (persistent, stdio) | <- lives as long as VS Code window is open -| 11 tools: axme_context, axme_decisions, | +| 19 tools: axme_context, axme_decisions, | | axme_save_memory, axme_oracle, ... | +---------------------------------------------+ | Hooks (pre-tool-use, post-tool-use, | <- fire on EVERY Claude Code tool call, @@ -36,6 +36,9 @@ Launches as a stdio process when VS Code opens. Lives for the entire window life | `axme_save_memory` | Agent saves feedback/pattern (mistakes, approaches) | | `axme_safety` | Current safety rules (git, bash, filesystem) | | `axme_update_safety` | Add a new safety rule | +| `axme_backlog` | List or read backlog items (persistent cross-session task tracking) | +| `axme_backlog_add` | Add a new backlog item with priority and tags | +| `axme_backlog_update` | Update backlog item status, priority, or append notes | | `axme_status` | Project status (sessions, decisions count, etc.) | | `axme_worklog` | Event log (session starts, audit results) | | `axme_workspace` | List all repos in workspace | @@ -243,26 +246,89 @@ The agent has full conversation context and produces higher-quality extractions --- +## Git Commit/Push Gate (`#!axme` protocol) + +Every `git commit` and `git push` command must end with a metadata suffix: + +``` +git commit -m "fix bug" #!axme pr=42 repo=AxmeAI/axme-code +git push origin feat/foo #!axme pr=none repo=AxmeAI/axme-code +``` + +The `pre-tool-use` hook: +1. Checks for the `#!axme` suffix — blocks the command if missing (returns format instruction) +2. Parses `pr=` and verifies via `gh pr view` that the PR is not already merged +3. If the PR is merged, blocks the command (prevents committing to stale branches) + +This replaces all prior cwd/branch detection. The agent explicitly provides repo and PR number, eliminating cwd bugs, network inference, and fail-open errors. + +--- + +## Backlog (persistent cross-session task tracking) + +Each repo has its own backlog in `.axme-code/backlog/`. Items persist across sessions (unlike TODOs which are session-scoped). + +Tools: `axme_backlog` (list/read), `axme_backlog_add` (create), `axme_backlog_update` (status/priority/notes). + +Items have: ID (B-001..B-NNN), title, status (open/in-progress/done/blocked), priority (high/medium/low), tags, notes, timestamps. + +--- + +## Open Questions (inter-session protocol) + +The auditor may find ambiguities during transcript analysis. Instead of guessing, it records a question in `.axme-code/open-questions.md`. The next session's `axme_context` surfaces these questions to the agent, which presents them to the user. + +Lifecycle: `[open]` → `[answered]` (user responds via `axme_answer_question`) → `[applied]` (action taken) → `[archived]`. + +Tools: `axme_ask_question`, `axme_list_open_questions`, `axme_answer_question`. + +--- + +## Context Pagination + +`axme_context` returns a compact overview (~10-15K chars): storage root header, safety rules, handoff, backlog summary, open questions, and instructions to call three tools in parallel: + +1. `axme_oracle` — stack, structure, patterns, glossary +2. `axme_decisions` — all decisions with enforce levels +3. `axme_memories` — feedback and patterns + +Each sub-call returns ~15-25K chars (fits tool output limits). The server tracks which context paths were already delivered in the session and avoids duplicating workspace-level data when repo-level calls follow. + +--- + +## Test Suite + +413 tests across 88 suites. Run with Node.js built-in test runner: + +```bash +npm test # node --test --experimental-strip-types test/*.test.ts +``` + +Coverage includes: storage engine, sessions, safety hooks, decisions, memory, oracle detection, transcript parser, workspace merge, plans, worklog, backlog, questions, config, presets. + +--- + ## Storage Layout ``` .axme-code/ |-- oracle/ # stack.md, structure.md, patterns.md, glossary.md -|-- decisions/ # D-001-*.md ... D-075-*.md (YAML frontmatter) +|-- decisions/ # D-001-*.md ... D-NNN-*.md (YAML frontmatter) |-- memory/ | |-- feedback/ # Mistakes and corrections | +-- patterns/ # Successful approaches |-- safety/ | +-- rules.yaml # git + bash + filesystem rules +|-- backlog/ # B-001-*.md ... persistent cross-session task tracking |-- sessions/ # Per-session meta.json |-- active-sessions/ # Claude session -> AXME session mapping |-- audited-offsets/ # Resume byte offsets per transcript |-- audit-logs/ # Per-audit telemetry JSON |-- audit-worker-logs/ # Worker stderr output |-- plans/ -| |-- handoff.md # What to pass to next session (Source: agent or auditor) -| |-- handoff-.md # Versioned handoff per session (last 5 kept) +| |-- handoff-.md # Per-session handoff (last 5 kept, Source: agent or auditor) | +-- -.md # Active plans with steps +|-- open-questions.md # Inter-session questions (auditor -> user -> agent) |-- worklog.jsonl # Append-only structured event log |-- worklog.md # Narrative session summaries (written by finalize_close + auditor) +-- config.yaml # Model settings, presets, review config @@ -270,6 +336,8 @@ The agent has full conversation context and produces higher-quality extractions Each repo in a workspace has its own `.axme-code/` with separate decisions, oracle, and safety rules. The workspace-level `.axme-code/` stores cross-repo items and sessions. +**Repo mode vs workspace mode**: When the MCP server cwd has `.git/` (is a git repo), it operates in repo mode — no parent workspace auto-detection, all storage goes to repo `.axme-code/`. Workspace mode only activates when cwd IS the workspace root (no `.git/`, has workspace markers). + --- ## Two-Level Storage: Workspace vs Repo diff --git a/docs/diagrams/axme-code-architecture.dot b/docs/diagrams/axme-code-architecture.dot index 4156ec6..617e44e 100644 --- a/docs/diagrams/axme-code-architecture.dot +++ b/docs/diagrams/axme-code-architecture.dot @@ -58,8 +58,9 @@ digraph axme_code_architecture { Decisions [label="decisions/\nD-001..D-NNN", fillcolor="#bbf"]; Memory [label="memory/\nfeedback/ + patterns/", fillcolor="#bbf"]; Safety [label="safety/\nrules.yaml", fillcolor="#bbf"]; + Backlog [label="backlog/\nB-001..B-NNN", fillcolor="#bbf"]; Sessions [label="sessions/\nmeta.json", fillcolor="#bbf"]; - Plans [label="plans/\nhandoff.md", fillcolor="#bbf"]; + Plans [label="plans/\nhandoff-id.md", fillcolor="#bbf"]; Worklog [label="worklog.jsonl\nworklog.md", fillcolor="#bbf"]; } diff --git a/docs/diagrams/axme-code-architecture.mmd b/docs/diagrams/axme-code-architecture.mmd index 567daa0..7fe9f99 100644 --- a/docs/diagrams/axme-code-architecture.mmd +++ b/docs/diagrams/axme-code-architecture.mmd @@ -26,7 +26,8 @@ graph TD Dec["decisions/\nD-001 .. D-NNN\nadd / supersede / revoke"] Mem["memory/\nfeedback/ + patterns/"] Safe["safety/\nrules.yaml\ngit + bash + fs"] - Hand["plans/\nhandoff.md\nSource: agent"] + Backlog["backlog/\nB-001 .. B-NNN\ncross-session tasks"] + Hand["plans/\nhandoff-id.md\nSource: agent"] WLog["worklog.jsonl\nworklog.md"] Sess["sessions/\nmeta.json\nagentClosed flag"] end @@ -65,7 +66,7 @@ graph TD classDef mcp fill:#e0ffd0,stroke:#4a4,stroke-width:1px,color:#000 class Pre,Post hook - class Oracle,Dec,Mem,Safe,Hand,WLog,Sess store + class Oracle,Dec,Mem,Safe,Backlog,Hand,WLog,Sess store class Agent agent class Full,Verify audit class Context,Save,Begin,Finalize,SessMgr mcp diff --git a/docs/diagrams/axme-code-overview.mmd b/docs/diagrams/axme-code-overview.mmd index e597730..e920b8a 100644 --- a/docs/diagrams/axme-code-overview.mmd +++ b/docs/diagrams/axme-code-overview.mmd @@ -14,6 +14,7 @@ graph LR D["Decisions\nrules, policies\nenforce levels"] M["Memory\nfeedback\npatterns"] S["Safety Rules\ngit, bash, fs"] + BL["Backlog\ncross-session tasks"] HO["Handoff\nsession state\nnext steps"] W["Worklog\nsession history"] end @@ -33,4 +34,4 @@ graph LR class A agent class MCP,H,AU axme - class O,D,M,S,HO,W kb + class O,D,M,S,BL,HO,W kb