documentation-lifecycle

name	documentation-lifecycle
description	Generate, update, and maintain per-module documentation under docs/modules/, keep docs/ARCHITECTURE.md and README.md current, and produce Mermaid diagrams for data-flow, block, and dependency views. USE FOR: documenting a package; updating architecture docs after structural changes; generating diagrams; auditing documentation freshness; first-time doc generation for the project. DO NOT USE FOR: writing implementation code; debugging runtime errors; updating AGENTS.md or .subagents/ guides (use agents-doc-lifecycle instead).
compatibility	Designed for GitHub Copilot and similar coding agents working in the leather repository.
metadata	{"argument-hint":"What doc operation? e.g. \"generate all module docs\", \"update docs/modules/session.md\", \"audit freshness\", \"regenerate ARCHITECTURE.md\", \"update README.md flags\"","user-invocable":"true"}

documentation-lifecycle

Keeps docs/modules/, docs/ARCHITECTURE.md, and README.md synchronized with the leather codebase. These docs serve contributors and AI agents navigating the project. Stale docs cause wrong decisions and wasted context.

Scope boundary: This skill does not touch AGENTS.md or .subagents/. Those are owned by the agents-doc-lifecycle skill.

---

Documentation surfaces

Surface	Path	Audience
Module docs	docs/modules/<package>.md	Contributors + AI agents
Architecture	docs/ARCHITECTURE.md	Contributors + AI agents
README	README.md	Users + contributors

---

Required context

Before generating or updating documentation, read:

• AGENTS.md — hard constraints (stdlib-only, single binary, zero external deps, error patterns, package responsibilities)
• internal/model/model.go — shared domain types (Config, Agent, Job, TokenBudget, Message, LLMResponse, LogLevel)
• internal/cli/cli.go — subcommand dispatch table and usage string
• Any .go source files in the target package (not _test.go for API surface; include for test summary)

---

Package inventory

leather has twenty-six top-level internal/ packages plus two cmd/ entrypoints:

Package	Path	Primary responsibility
agent	internal/agent/	Agent definition parsing, validation, registry
artifact	internal/artifact/	Filesystem artifact store with lineage metadata
cache	internal/cache/	File-backed response cache
cli	internal/cli/	Subcommand dispatch, serve loop, API, replay, tannery wiring
config	internal/config/	YAML + flag + env-var config loading, defaults, flag binding
curing	internal/curing/	Curing loader, router, worker, and supervisor
devtools	internal/devtools/	Event bus, causality tracing, and UI source aggregation
fileutil	internal/fileutil/	Atomic writes and small filesystem helpers
hide	internal/hide/	Hide store plus paged hide buffer for oversized content
httpx	internal/httpx/	JSON/error HTTP response helpers
ids	internal/ids/	Timestamped IDs and random tokens
jsonstore	internal/jsonstore/	JSON persistence helpers over atomic file writes
logging	internal/logging/	Structured logging wrapping log/slog; per-component level control
mcp	internal/mcp/	MCP config loading, stdio clients, and registry lifecycle
model	internal/model/	Shared domain types; no internal imports
notify	internal/notify/	Telegram and Signal notifiers plus backend construction
queue	internal/queue/	File queues and named queue manager
runner	internal/runner/	Agent runtime loop, tool orchestration, output routing
safepath	internal/safepath/	Anchor-relative safe path validation
scheduler	internal/scheduler/	Cron parsing, job queue, execution dispatch, graceful shutdown
schema	internal/schema/	Flat schema validation for config and definition files
secret	internal/secret/	Secret and environment-template resolution
session	internal/session/	Token budget tracking, LLM client interface, HTTP client, summarization
tool	internal/tool/	Skill/toolset registry and HTTP/MCP tool execution
worker	internal/worker/	Declarative background HTTP poll workers
yamlx	internal/yamlx/	Stdlib-only flat YAML parser
main	cmd/leather/	Thin entrypoint; calls cli.Run(); only place os.Exit is allowed
shell-mcp	cmd/shell-mcp/	Companion stdio MCP server for local shell tools

---

Module doc template

Each docs/modules/<package>.md follows this structure:

# <package>

> One-line purpose statement.

## Responsibility

2–4 sentences describing what this package owns and why it exists as a
separate module.

## Public API

| Symbol | Signature | Description |
|--------|-----------|-------------|
| ...    | ...       | ...         |

## Internal Design

Key data structures, algorithms, concurrency model, or non-obvious design
choices. What a contributor needs to modify the package safely.

## Dependencies

Which internal packages this module imports and why.

## Data Flow

Mermaid diagram showing how data enters, transforms, and exits this module.

## Test Surface

Summary of test files, what they cover, notable helpers (e.g. MockLLM).

## Related Docs

Links to ARCHITECTURE.md sections or other module docs that interact with
this package.

---

Operations

1) Generate module doc

Create a new docs/modules/<package>.md for a package that has none.

1. Read all .go source files in the target package.
2. Extract exported symbols (types, functions, constants) and their doc comments.
3. Extract import blocks to build the internal dependency list.
4. Search callers (grep_search for the package name in other packages) to understand what calls into this package.
5. Write the doc using the template above.
6. Generate a Mermaid flowchart LR for the data-flow section.
7. If the package introduces structure not yet in docs/ARCHITECTURE.md, update it.

2) Update module doc

Refresh an existing docs/modules/<package>.md after code changes.

1. Re-read source to detect new/removed/changed exports.
2. Diff against the existing doc; apply minimal targeted updates.
3. Regenerate diagrams only if data flow or dependencies changed.

3) Generate or update ARCHITECTURE.md

Trigger: New internal/ package added or removed; import edges change; CLI subcommands added; domain types added to model.

1. Read all internal/*/ package directories (exported symbols + imports).
2. Read cmd/leather/main.go and internal/cli/cli.go for subcommands.
3. Read internal/model/model.go for domain types.
4. Write or update docs/ARCHITECTURE.md with:
   • Project overview paragraph
   • Package layout table (package → path → responsibility)
   • Dependency direction rule (direction diagram: model has no internal deps; everything imports model; cli sits at the top)
   • Mermaid graph TD dependency diagram
   • CLI subcommand table
   • Key domain types table
   • Design decisions section (stdlib-only, single binary, fail-closed, etc.)

4) Generate or update README.md

Trigger: New subcommand; flag changes; feature additions; folder layout changes; first-time creation.

README sections (in order):

1. What it is — one paragraph, target environment, key capabilities
2. Install — go install + build from source
3. Quick start — minimal working example
4. Subcommands — table: name | description
5. Configuration — YAML + flag + env-var reference table (all flags)
6. Agent definition format — *.agent.md + *.lifecycle.yaml examples
7. Token budget defaults — table from AGENTS.md
8. Folder layout — cmd/, internal/, Makefile targets
9. Development — make targets table, test strategy note

When updating:

1. Read internal/cli/cli.go → subcommand list
2. Read internal/config/config.go → all fs.Bool/String/Int/Float64/Duration calls → flag name, env var, default, description
3. Apply minimal edits; preserve existing prose style.

5) Audit documentation freshness

1. List all internal/ packages; flag any without docs/modules/<pkg>.md.
2. Compare docs/ARCHITECTURE.md package list against actual directories.
3. Compare README.md subcommand list against internal/cli/cli.go dispatch.
4. Compare README.md flag list against BindFlags in internal/config/config.go.
5. Report drift items; wait for user confirmation before updating.

6) Generate all docs (first-time)

Run this sequence when docs/ does not yet exist:

1. Read AGENTS.md, internal/model/model.go, internal/cli/cli.go, internal/config/config.go.
2. Read each internal/<pkg>/ package source.
3. Generate docs/ARCHITECTURE.md.
4. Generate README.md.
5. Generate docs/modules/<pkg>.md for every package in the inventory.

---

Diagram conventions

• graph TD (top-down) for the package dependency diagram.
• flowchart LR (left-right) for pipeline and data-flow diagrams.
• sequenceDiagram for LLM request/response flows.
• Node labels: short package or function names, not full paths.
• Embed diagrams directly in the relevant markdown inside fenced mermaid blocks.
• leather dependency direction: model ← everything; cli → all others; cmd/leather → cli only.

---

Guardrails

• Do not fabricate API surfaces; always read source before documenting.
• Do not add doc comments to .go source files; this skill produces standalone docs only.
• Keep module docs factual and concise; no marketing language.
• When updating README or ARCHITECTURE, make minimal targeted edits rather than wholesale rewrites.
• Respect the hard constraints from AGENTS.md: stdlib-only, zero external deps, os.Exit only in main.go, no init() functions.
• Never document internal implementation details that are subject to change as if they were stable API.