llm-docs

Task memory for AI coding agents.

llm-docs keeps the working memory of a software task in your repo, outside the chat window. Start from a Jira issue, a GitHub issue, a Linear ticket, a markdown spec, an incident note, or a plain local task. The result is the same: a durable task bundle that your coding agent can read, update, checkpoint, and publish back into project documentation.

It is built for developers who use Claude Code, Codex, Cursor, or similar agents on real implementation work where context matters.

Why it exists

Coding agents are useful, but a chat thread is a weak place to keep the truth of a task.

A real task usually has:

• source material: ticket text, acceptance criteria, comments, links, or a short local brief;
• implementation context: plans, decisions, changed files, tradeoffs, and validation gaps;
• verification: tests, build output, screenshots, logs, or manual checks;
• handoff state: what is done, what is risky, what should happen next;
• team value: the final implementation story should be reusable later, not lost in one agent session.

llm-docs turns that state into a local task bundle. The bundle lives next to your code, can follow a worktree, and can be published into shared project docs when the task is done.

Jira is supported, not required

Jira is one of the main use cases because many teams already plan work there. If your team uses Jira, llm-docs can pull an issue into a task bundle and keep the implementation context tied to that issue.

But Jira is not required. You can use the same task bundle workflow for:

• GitHub issues or Linear tickets;
• markdown specs and design notes;
• refactors and cleanup tasks;
• incidents and debugging sessions;
• research tasks;
• personal local todos that still need durable context.

The core idea is not "Jira documentation". The core idea is "one work item, one structured task memory".

How it works

Work item
  -> task bundle
  -> agent implementation
  -> checkpoints
  -> actualization against code and git
  -> publish, handoff, or Jira-ready summary

A typical flow:

1. Create a task bundle from Jira, another issue tracker, a prompt, or a local task brief.
2. Let the coding agent work with the bundle through MCP tools, host skills, and hooks.
3. Save compact checkpoints as the implementation changes.
4. Actualize the bundle before handoff so the docs match the current code and git state.
5. Publish the finished task docs into the main worktree if the context should become shared team knowledge.

What llm-docs gives you

• Task bundles: one local folder per task with source text, current context, changelog, structured state, and artifacts.
• Durable context: the next agent can reload the task without reading the whole chat history.
• Checkpoints: compact progress notes with decisions, touched files, verification, risks, and next steps.
• Actualization: a separate step that syncs task docs with code and git facts before handoff.
• Worktree-friendly flow: task context can live in an isolated feature worktree and later be published into main project docs.
• Agent integrations: MCP tools and generated host skills for Claude Code, Codex, and Cursor.
• Jira helpers: optional auth, issue pull, and task bundle creation for teams that work from Jira.

Use with Jira

llm-docs jira auth login
llm-docs jira doctor
llm-docs task from-jira ABC-123 --use

This creates or refreshes a task bundle from the Jira issue and marks it as the current task. From there, the agent can load the bundle, work through the task, save checkpoints, and prepare a concise Jira-ready implementation summary.

Use without Jira

For non-Jira work, use the MCP tool exposed to your configured agent: llmdocs.create_task_bundle.

Example prompt for the agent:

Create an llm-docs task bundle for this work.

Title: Refactor checkout validation
Source type: prompt
Brief: The checkout validation is duplicated across the form and submit handler.
Done criteria:
- validation rules live in one place
- current UI behavior stays unchanged
- focused tests cover the shared rules

The bundle can be created from a prompt, imported note, external doc, or issue reference. After that, the workflow is the same as with Jira: checkpoint, actualize, verify, and publish or hand off.

Worktrees and shared docs

llm-docs fits the workflow where each substantial task gets its own git worktree.

llm-docs worktree create ABC-123
llm-docs worktree seed

worktree create checks out the tracked project state first, then seeds two extra layers from the main worktree:

• curated llm-docs context from the selected seed profile;
• ignored local project files such as .env or node_modules, while leaving local agent runtime state out.

Use the task worktree for implementation. Keep the active task bundle there while the work is moving. When the task is ready, publish the task docs back into the main worktree:

llm-docs task publish ABC-123 --dry-run
llm-docs task publish ABC-123

That gives the team a durable implementation history in the main repo, without copying notes by hand.

Install from source

An npm package is not published yet. For now, run the CLI from a checked-out repository:

node --version # use Node 20.19+ for the current dev toolchain
git clone https://github.com/pishikin/llm-docs.git
cd llm-docs
npm install
npm run build

In a project where you want to use llm-docs, run setup with the built CLI:

node /path/to/llm-docs/dist/index.js setup --hosts claude,codex --enable-git-hooks
node /path/to/llm-docs/dist/index.js doctor

Setup creates the workspace, local launcher, host packs, MCP config, skills, and optional git hooks. Root agent files stay thin. Task-specific state belongs in task bundles.

The examples above use llm-docs for readability. When running from source, replace it with node /path/to/llm-docs/dist/index.js before setup, or with the generated node .claude/bin/llm-docs.mjs inside a configured workspace.

Everyday commands

Check which task is active:

llm-docs task active --trace

Save implementation context:

llm-docs task checkpoint ABC-123 \
  --summary "Implemented shared checkout validation rules." \
  --file "src/checkout/validation.ts" \
  --verification "npm test -- checkout"

Check bundle handoff quality:

llm-docs task quality ABC-123
llm-docs task quality ABC-123 --json

Check workspace health:

llm-docs doctor --strict
llm-docs context status

Storage model

The default layout keeps active task memory separate from shared project docs:

.claude/
  docs/
    README.md
    tasks/
      ABC-123/
        summary.md
        context.md
        changelog.md
        publish.manifest.json
  .llm-docs/
    tasks/
      ABC-123/
        task.meta.yaml
        raw.md
        task.md
        context.md
        changelog.md
        state.json
        artifacts/
          index.json
        docs/
  skills/
.agents/
  skills/
.codex/
  config.toml
  hooks.json
.mcp.json

Human-readable task docs such as context.md, task.md, and changelog.md are meant for developers and host agents. Structured files such as state.json, task.meta.yaml, registries, and artifact indexes are owned by llm-docs and should be updated through the CLI or MCP tools.

Agent integration

llm-docs uses three integration surfaces:

• MCP for deterministic task reads and mutations.
• Skills for workflows such as create, checkpoint, actualize, publish, close, and handoff.
• Hooks for small lifecycle nudges at session start, prompt submit, stop, commit, merge, and push boundaries.

On protected branches such as main, hooks stay passive unless a task is explicitly selected. In task worktrees, hooks can surface stale context warnings and checkpoint guidance without turning every prompt into a workflow detour.

Checkpoint and actualization are intentionally separate:

• A checkpoint saves compact working memory: current goal, completed work, decisions, touched files, verification, risks, and next steps.
• Actualization syncs task docs with code and git facts: source-of-truth paths, phase/status, last actualized commit, and staleness state.

More docs

• docs/default-task-bundle-quality.md explains what a useful task bundle should contain.
• docs/long-task-quality.md covers long-running, UI-heavy, research-heavy, and incident/debug tasks.
• CONTRIBUTING.md covers local development and verification.

Development

Main verification commands:

npm run lint
npm run typecheck
npm run test:unit
npm run test:integration
npm run test:e2e
npm run build

Full project verification:

npm run verify

License

MIT