llmdoc

llmdoc for Claude Code and Codex

llmdoc is a doc-driven workflow for both Claude Code and Codex.

• Core skill: llmdoc
• Claude Code commands: /llmdoc:init, /llmdoc:update
• Codex helper skills: llmdoc-init, llmdoc-update

The default setup is simple:

• CLAUDE.md and AGENTS.md only need one short rule: step one is loading the llmdoc skill
• the core skill entry is short, while detailed rationale, protocols, and templates are split under skills/llmdoc/references/
• the core skill defines proactive guide/reflection reading and proactive user discussion before non-trivial edits
• the workflow restores the good pattern of proactively asking whether to run /llmdoc:update at the end of non-trivial tasks
• helper Codex skills provide command-like entrypoints without pretending Codex has custom slash commands for this plugin
• agents and command contracts stay focused on execution instead of carrying a large amount of duplicated guidance

Why This Version

The previous design exposed too many internal steps:

• separate skills for reading docs, investigating, and doc workflow
• separate scout and investigator agents with overlapping responsibilities
• heavy line-level references instead of file-level retrieval

This refactor keeps the public interface small and moves the rest into one reusable operating skill plus small Codex helper entry skills.

Public Surface

• Core skill: llmdoc
• Claude Code commands: /llmdoc:init, /llmdoc:update
• Codex helper skills: llmdoc-init, llmdoc-update
• Claude Code plugin support: .claude-plugin/
• Codex CLI plugin support: .codex-plugin/plugin.json and .agents/plugins/marketplace.json
• Codex CLI subagents: .codex/agents/*.toml
• Codex CLI hooks: SessionStart, Stop templates included

Workflow

use

use is not a command.

It is the operating mode defined by the llmdoc skill. The recommended setup is to tell the model to load that skill first, then follow it.

/llmdoc:init

Use /llmdoc:init to create or repair the llmdoc skeleton and generate initial docs.

In Claude Code, this is a command. In Codex, use the helper skill llmdoc-init for the equivalent workflow.

The command:

1. Inspects the repo
2. Creates the llmdoc directory structure
3. Runs multi-investigator temporary scratch work with explicit coverage checks, then a follow-up gap-check pass
4. Generates initial MUST, overview, architecture, and reference docs
5. Synchronizes llmdoc/index.md

/llmdoc:update

Use /llmdoc:update after meaningful work when project knowledge should be persisted.

In Claude Code, this is a command. In Codex, use the helper skill llmdoc-update for the equivalent workflow.

The command:

1. Rebuilds context from llmdoc and the current working tree
2. Proactively reads relevant guides and reflections
3. Investigates impacted concepts
4. Writes a reflection under llmdoc/memory/reflections/
5. Updates stable docs
6. Synchronizes llmdoc/index.md

In normal use, the main assistant should proactively ask whether to run /llmdoc:update when the task produced durable knowledge or a useful reflection.

llmdoc Layout

llmdoc/
├── index.md
├── startup.md
├── must/                 # Small startup context package
├── overview/             # Project and feature identity
├── architecture/         # Retrieval maps, invariants, ownership
├── guides/               # One workflow per document
├── reference/            # Stable lookup facts and conventions
└── memory/
    ├── reflections/      # Post-task reflections
    ├── decisions/        # Durable process or design decisions
    └── doc-gaps.md       # Known documentation weaknesses

.llmdoc-tmp/
└── investigations/       # Temporary scratch investigation reports

llmdoc/index.md is the global doc map. llmdoc/startup.md is only the startup reading order. They should link to each other, but they should not repeat the same content.

Internal Agents

Agent	Purpose
investigator	Evidence gathering for chat or temporary scratch reports
worker	Executes well-defined tasks
recorder	Maintains stable llmdoc documents
reflector	Writes post-task reflections

Install

Claude Code

Install Claude Code first. Anthropic’s official docs currently list:

• npm install -g @anthropic-ai/claude-code
• or native install on macOS/Linux/WSL: curl -fsSL https://claude.ai/install.sh | bash

Official docs:

• https://docs.anthropic.com/en/docs/claude-code/quickstart
• https://docs.anthropic.com/en/docs/claude-code/setup

Then install this plugin marketplace and plugin:

/plugin marketplace add https://github.com/TokenRollAI/llmdoc
/plugin install llmdoc@llmdoc-cc-plugin

After installation: