Skip to content

README.md

Latest commit

 

History

History
147 lines (106 loc) · 7.31 KB

README.md

File metadata and controls

147 lines (106 loc) · 7.31 KB

up-docs

Update documentation across three layers (repo, Outline wiki, Notion) based on what changed during a session, plus comprehensive drift analysis for infrastructure documentation.

Summary

Documentation lives in three places with different purposes: repo-local files capture project-specific details, the Outline wiki holds implementation-level reference material, and Notion maintains strategic context and organizational knowledge. Keeping all three in sync after a work session means explaining the same layering rules every time. up-docs encodes those rules into five slash commands, each of which dispatches a dedicated sub-agent on the model tier that fits its workload: Haiku for propagation (mechanical edits scoped to an explicit change list) and Sonnet for drift detection (search + infer against live state).

Principles

[P1] Right Content, Right Layer: Each documentation layer has a defined purpose and information level. Repo docs are project-specific. Outline is implementation reference ("how"). Notion is strategic context ("what and why"). Content that belongs in one layer does not get duplicated into another.

[P2] Infer, Don't Interrogate: Commands assess what changed from git diffs, recent commits, and conversation context. No pre-work questionnaires or intake forms.

[P3] Update, Don't Rewrite: Changes are targeted edits that preserve existing tone, structure, and formatting. Full-page rewrites only happen when a page is genuinely wrong throughout.

[P4] Ground Truth Wins: The live server or repository is the authority. When documentation conflicts with reality, update the documentation. Both Notion and Outline may lag slightly; that's acceptable. Factual conflicts are not.

Requirements

  • Claude Code (any recent version)
  • Outline wiki accessible via MCP (mcp-outline server configured)
  • Notion accessible via MCP (Notion MCP server configured)
  • SSH access to infrastructure hosts (for /up-docs:drift)

Installation

/plugin marketplace add L3DigitalNet/Claude-Code-Plugins
/plugin install up-docs@l3digitalnet-plugins

For local development:

claude --plugin-dir ./plugins/up-docs

How It Works

/up-docs:all Orchestration

flowchart TD
    User([User]) -->|"/up-docs:all"| Orchestrator[Orchestrator skill<br/>gather context + build<br/>session-change summary]
    Orchestrator --> Dispatch[Parallel dispatch<br/>via Agent tool]
    Dispatch --> Repo[up-docs-propagate-repo<br/>Haiku]
    Dispatch --> Wiki[up-docs-propagate-wiki<br/>Haiku]
    Dispatch --> Notion[up-docs-propagate-notion<br/>Haiku]
    Repo --> Audit[up-docs-audit-drift<br/>Sonnet]
    Wiki --> Audit
    Notion --> Audit
    Audit --> Report((Combined report:<br/>3 layer tables +<br/>drift findings))
Loading

Individual Commands

flowchart TD
    User([User]) -->|"/up-docs:repo<br/>/up-docs:wiki<br/>/up-docs:notion"| Wrapper[Thin wrapper skill<br/>builds session-change summary]
    Wrapper --> Agent[Single propagator sub-agent<br/>Haiku, isolated context]
    Agent --> Table((Single-layer<br/>summary table))
Loading

Drift Analysis

flowchart TD
    User([User]) -->|"/up-docs:drift [collection]"| Wrapper2[Thin wrapper skill<br/>builds session-change summary]
    Wrapper2 --> Auditor[up-docs-audit-drift<br/>Sonnet, read-only]
    Auditor --> P1[Phase 1: Infrastructure → Wiki]
    Auditor --> P2[Phase 2: Wiki Consistency]
    Auditor --> P3[Phase 3: Link Integrity]
    Auditor --> P4[Phase 4: Notion Relevance]
    P1 --> Findings((JSON findings +<br/>markdown table +<br/>optional escalation))
    P2 --> Findings
    P3 --> Findings
    P4 --> Findings
Loading

Usage

Run a command at a natural pausing point or end of session:

/up-docs:repo                Update repo documentation only
/up-docs:wiki                Update Outline wiki only
/up-docs:notion              Update Notion only
/up-docs:all                 Update all three layers sequentially
/up-docs:drift [collection]  Full drift analysis (infrastructure → wiki → links → Notion)

Each command produces a summary table listing every page or file examined, the action taken, and a one-line description of changes.

Project Setup

Add a documentation mapping section to your project's CLAUDE.md so the commands know where to look:

## Documentation

- Outline: "Homelab" collection
- Notion: "Infrastructure" section
- Repo docs: docs/, README.md

The mapping is intentionally loose. It points to the general area and lets Claude search for relevant content within it.

Skills

Skill Role Invoked by
all Orchestrator — builds session-change summary, dispatches propagators in parallel, then drift auditor /up-docs:all
repo Thin wrapper, dispatches up-docs-propagate-repo /up-docs:repo
wiki Thin wrapper, dispatches up-docs-propagate-wiki /up-docs:wiki
notion Thin wrapper, dispatches up-docs-propagate-notion /up-docs:notion
drift Thin wrapper, dispatches up-docs-audit-drift /up-docs:drift

Sub-agents

Agent Model Role
up-docs-propagate-repo Haiku Mechanical edits to README.md, docs/, CLAUDE.md scoped to the session-change summary
up-docs-propagate-wiki Haiku Mechanical edits to Outline pages at implementation-reference level
up-docs-propagate-notion Haiku Mechanical edits to Notion at strategic/organizational level; never writes configs or procedures
up-docs-audit-drift Sonnet Read-only drift scan across all three layers with live-state verification; never auto-fixes

Per-agent model: frontmatter overrides the caller's model tier, so propagation runs on Haiku (≈ 1/10 Opus cost) even when the orchestrator was invoked from an Opus session.

Planned Features

  • Per-layer dry-run mode that previews changes without pushing to Outline or Notion

Known Issues

  • Requires both Outline and Notion MCP servers to be configured and running. If only one external system is available, use the individual commands for the layers you have.
  • The session context inference relies on git history; in a fresh repo with no commits, the commands have less signal to work from.
  • Notion and Outline MCP servers must be accessible from the current environment. Air-gapped systems can only use /up-docs:repo.
  • /up-docs:drift requires SSH access to all documented hosts. Unreachable hosts are logged and skipped, not fatal.
  • Drift analysis is designed for Opus 4.6 with 1M context. Running on smaller context models may cause truncation on large wiki collections.
  • Claude Code version sensitivity (MCP + Haiku): Claude Code v2.1.92 had a bug where Haiku's internal title-generation probe could block session-wide MCP tool loading (anthropics/claude-code#44290, now closed). On affected versions, up-docs-propagate-wiki, up-docs-propagate-notion, and up-docs-audit-drift may show FAILED rows because their MCP tools never load. Mitigation: upgrade Claude Code past the fix, or fall back to /up-docs:repo which uses no MCP tools.

Links