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:

Inspects the repo
Creates the llmdoc directory structure
Runs multi-investigator temporary scratch work with explicit coverage checks, then a follow-up gap-check pass
Generates initial MUST, overview, architecture, and reference docs
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:

Rebuilds context from llmdoc and the current working tree
Proactively reads relevant guides and reflections
Investigates impacted concepts
Writes a reflection under llmdoc/memory/reflections/
Updates stable docs
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:

Then install this plugin marketplace and plugin:

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

After installation:

Copy CLAUDE.example.md into ~/.claude/CLAUDE.md.
If you want repository-local instructions, adapt AGENTS.example.md into the project root.
Restart Claude Code so the new prompt and plugin state are loaded.

Codex CLI

Install Codex CLI first. OpenAI’s official docs currently list:

npm i -g @openai/codex
codex

Official docs:

This repository contains two separate Codex integration surfaces:

Plugin packaging for llmdoc itself:
- .codex-plugin/plugin.json
- skills/llmdoc/
- skills/llmdoc-init/
- skills/llmdoc-update/
- .agents/plugins/marketplace.json as a repo-scoped local marketplace example
Repo-local Codex workflow files for this repository:

Option 1: Use this repository directly in Codex

Use this when you want to work inside this repository and keep the plugin local to the repo checkout.

Open this repository in Codex.
Make sure .agents/plugins/marketplace.json exists.
If Codex was already running, restart it so the repo marketplace and project-scoped agents are reloaded.
In Codex, run /plugins.
Find llmdoc in the plugin list, select it to open the detail page.
Install the plugin.
Start a new thread in this repository and either:
- ask Codex to load the llmdoc skill first for normal work
- choose llmdoc-init when you want the /llmdoc:init workflow
- choose llmdoc-update when you want the /llmdoc:update workflow
- or type @ and choose the plugin or one of its bundled skills explicitly
If you want hooks, copy skills/llmdoc/templates/codex-hooks.json to .codex/hooks.json and adjust the script paths for your machine.

When you open this repository itself, Codex can also use the project-scoped agents under .codex/agents/ and the agent limits from .codex/config.toml.

Option 2: Install `llmdoc` as a personal local plugin

Use this when you want the llmdoc plugin to be available across repositories on your machine.

Copy this repository into ~/.codex/plugins/llmdoc:

mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/llmdoc ~/.codex/plugins/llmdoc

Add or update ~/.agents/plugins/marketplace.json so it points at that plugin directory with a ./-prefixed path relative to your home directory:

{
  "name": "local-personal",
  "interface": {
    "displayName": "My Local Plugins"
  },
  "plugins": [
    {
      "name": "llmdoc",
      "source": {
        "source": "local",
        "path": "./.codex/plugins/llmdoc"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Restart Codex.
In Codex, run /plugins.
Find llmdoc in the plugin list, select it to open the detail page.
Install the plugin.
Start a new thread in any repository and either:
- ask Codex to load the llmdoc skill first for normal work
- choose llmdoc-init when you want the /llmdoc:init workflow
- choose llmdoc-update when you want the /llmdoc:update workflow
- or type @ and choose the plugin or one of its bundled skills explicitly

This personal install gives you the plugin and its bundled skill across repositories. The files under .codex/agents/ and .codex/config.toml in this repository are still project-scoped and only apply when you open this repository itself.

Repo Files

The reusable skill lives at skills/llmdoc/SKILL.md.
The Codex helper entry skills live at skills/llmdoc-init/SKILL.md and skills/llmdoc-update/SKILL.md.
Detailed references live under skills/llmdoc/references/.
Codex hook templates live under skills/llmdoc/templates/.

Codex Subagents

This repository now also includes project-scoped Codex custom agents:

These follow the Codex subagent docs pattern for project-scoped standalone TOML files under .codex/agents/, so they apply when you open this repository in Codex.

The names are intentionally prefixed with llmdoc_ so they do not override Codex built-in agents like worker or explorer.

Migration Notes

This version removes the old fragmented skills and replaces them with one skill:

active skill: llmdoc
removed skills: read-doc, investigate, update-doc, doc-workflow, deep-dive, commit
removed commands: initDoc, withScout, what
removed agent: scout

If you used those before:

use /llmdoc:init instead of the old tr-prefixed init command
use /llmdoc:update instead of /update-doc
load the llmdoc skill instead of using separate read/investigate skills

update-doc

llmdoc for Claude Code and Codex

Why This Version

Public Surface

Workflow

`use`

`/llmdoc:init`

`/llmdoc:update`

llmdoc Layout

Internal Agents

Install

Claude Code

Codex CLI

Option 1: Use this repository directly in Codex

Option 2: Install `llmdoc` as a personal local plugin

Repo Files

Codex Subagents

Migration Notes

investigate

doc-workflow

read-doc

frontend-design

using-git-worktrees

llmdoc for Claude Code and Codex

Why This Version

Public Surface

Workflow

use

/llmdoc:init

/llmdoc:update

llmdoc Layout

Internal Agents

Install

Claude Code

Codex CLI

Option 1: Use this repository directly in Codex

Option 2: Install llmdoc as a personal local plugin

Repo Files

Codex Subagents

Migration Notes

`use`

`/llmdoc:init`

`/llmdoc:update`

Option 2: Install `llmdoc` as a personal local plugin