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
• /llmdoc:update supports lightweight and heavier modes, so immediate post-task doc updates do not always require a full multi-agent pipeline
• 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 keeps tracked llmdoc/ docs consistent with the current repository. Stable docs should stay compact: either smaller than the source they describe or useful because they explain architecture, implementation intent, boundaries, and stable contracts.

The command selects the lightest mode that can keep docs correct:

• fast: default for immediate post-implementation updates when the coordinating assistant has fresh context
• analysis: one focused evidence pass for stale context, current-state research, or unclear impact
• full: separate investigation, reflection, and recording when risk or process learning justifies the extra independence

The command:

1. Rebuilds context from llmdoc and the current working tree
2. Proactively reads relevant guides and reflections
3. Chooses an update mode
4. Investigates impacted concepts only when the selected mode requires it
5. Writes a reflection under llmdoc/memory/reflections/ only when there is a workflow lesson or missing-doc signal
6. Updates stable docs and reconciles llmdoc/memory/doc-gaps.md
7. 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.