Agent Docs

A machine-global framework that turns Claude Code sessions into aligned engineering collaboration. Installed once per machine, it gives every project a shared operational stance, a session routine that reaches alignment before code gets written, persistent memory that compounds across sessions, and a work graph that carries intent between them.

Two layers, strictly separated: the framework (CLI, skills, hooks, stance, templates) lives under ~/.agent-docs and is never vendored into repos; each project commits only a lean residue — .docs-config, its own memory, its own skills. See ARCHITECTURE.md for the full model.

Install (once per machine)

npx @kraekke/agent-docs@latest

Sets up the machine-global framework under ~/.agent-docs (payload + agent-docs shim), links the shim onto your PATH (standard Homebrew bin dirs; it prints a fallback if none is writable), and syncs the framework skills and hooks to user scope (~/.claude) — merge-safe, your own skills and hooks are untouched.

Verify with agent-docs root — it prints the resolved framework root and the module graph.

How a session runs

Inside an agent-docs project, a session-entry hook primes the routine automatically (outside one it stays completely silent — non-agent-docs sessions are never biased):

1. /reorient — loads the stance (language, posture, form), queries the memory surface for the seed, reads the git delta, and resolves the session's focus against the open work graph. One integrating overview, then hands off.
2. /grill — the alignment work: curious, challenging dialogue that applies the project's taste and decisions to the live problem before and during implementation. Light when the focus is crisp, deep when the design is open.
3. /handoff — settles the frontier at close: completes what landed, reframes what continues, spawns what emerged.

What it carries

• Memory — stable project knowledge (taste, ADRs, gotchas, overviews) with ranked retrieval: stemmed matching over curated metadata, grouped by intake posture, expanding across every module in the repo family with nearest-module weighting. Plus frictionless notes, ideas, and cues for what isn't stable yet.
• The work graph — campaigns, stories, and beats as event-ledger nodes in the global home, carrying work intent across sessions and machines-of-one; sessions themselves are registered evidence rows every event references.
• Skills — the routine (/reorient, /grill, /handoff) plus capture, research, taste-refinement, and authoring instruments, delivered to user scope and shared by every project.
• The agent-docs CLI — the instrument panel behind all of it: memory query and capture, graph verbs (offer, check-in, create, link, complete), routing and git-map for orientation, and a local dashboard (agent-docs dashboard) over the whole corpus.

Onboard a project

Open Claude in the project directory and run /init-project (the thin wrapper over agent-docs project init). It scaffolds the project's residue — .docs-config, the CLI permission, the managed gitignore block, the memory skeleton — and authors the project overview. Idempotent: re-run any time to heal drift.

Update

Re-run the install with @latest — it re-packs the framework and re-syncs skills + hooks:

npx @kraekke/agent-docs@latest