diff --git a/.agents/skills/AGENTS.md b/.agents/skills/AGENTS.md index 55305db..a4fdf26 100644 --- a/.agents/skills/AGENTS.md +++ b/.agents/skills/AGENTS.md @@ -66,6 +66,7 @@ Verify your skill by loading it and checking: | ----- | ------- | | `adapt` | Analyze project and fill in AGENTS.md after installation | | `agent-work` | Create and maintain `.agents/work/` work items | +| `documentation` | Scan, create, update, verify, and promote canonical project documentation | | `feature-planning` | Turn context into plans and paste-ready handoff prompts | | `research` | Research technical topics, saving work-local or reusable findings | | `tmux` | Manage background processes using tmux windows for servers and long-running tasks | diff --git a/.agents/skills/documentation/SKILL.md b/.agents/skills/documentation/SKILL.md new file mode 100644 index 0000000..3e93380 --- /dev/null +++ b/.agents/skills/documentation/SKILL.md @@ -0,0 +1,164 @@ +--- +name: documentation +description: "Scans and maintains evidence-backed project documentation. Use for docs initialization, architecture, ADRs, runbooks, APIs, or work-item promotion. Triggers on: documentation scan, initialize docs, document architecture, update docs." +--- + +# Documentation + +Discover the repository's documentation convention, assess selected topics against repository evidence, and create or update only the canonical documents the user wants. + +## Core Rules + +1. Treat project documentation as durable human-and-agent knowledge, separate from task state in `.agents/work/`. +2. Discover an existing canonical documentation location before proposing `docs/`. +3. Run scans read-only. Show coverage and recommendations before writing unless the user already selected topics and asked for changes. +4. Create directories only when adding a useful document; never scaffold an empty taxonomy. +5. Derive technical facts from current repository evidence. Label unknown policy or intent instead of guessing. +6. Link to existing generated or canonical material instead of duplicating it. +7. Preserve the repository's existing style, structure, and documentation tooling. + +## Modes + +- **Scan**: inventory documentation, evaluate selected or all topics, and report gaps without editing. +- **Initialize**: establish a canonical documentation location after user approval. +- **Create or update**: write selected documents from verified evidence. +- **Verify**: compare existing documentation with code, tests, schemas, configuration, and infrastructure. +- **Promote**: move enduring knowledge from a work item into canonical project documentation and link both locations. + +## Workflow + +### 1. Discover Existing Documentation + +Inspect likely entrypoints before choosing a location: + +```text +README.md +CONTRIBUTING.md +SECURITY.md +docs/ +doc/ +documentation/ +architecture/ +adr/ +.github/ +package- or module-level README files +documentation-site configuration and build scripts +``` + +Also inspect links from `README.md` and `AGENTS.md`. + +- If a canonical location exists, use it. +- If documentation is intentionally distributed, preserve that arrangement. +- If competing locations make ownership ambiguous, ask which is canonical. +- If no canonical location exists, offer to initialize `docs/`; do not create it without user approval. + +### 2. Choose Scan Topics + +Use the topics requested by the user. If none are specified, scan all topics at summary depth and let the user select which findings to act on. + +| Topic | Typical contents | +| --- | --- | +| `architecture` | Current structure, views, concepts, diagrams, and architecture decisions | +| `development` | Local setup, testing, debugging, and conventions | +| `operations` | Deployment, monitoring, configuration, backup, recovery, and rollback | +| `security` | Threat model, trust boundaries, authentication, authorization, secrets, and security rules | +| `runbooks` | Actionable incident and operational procedures | +| `specifications` | Durable behavioral, protocol, state, and interface contracts | +| `api` | API contracts, authentication, errors, versioning, and examples | +| `data` | Schema ownership, migrations, consistency, retention, and classification | +| `product` | Stable domain language, roles, capabilities, workflows, and product invariants | +| `contributing` | Review, release, contribution, and required-check processes | + +These names are a proposed taxonomy, not mandatory paths. Follow established repository conventions such as a root `CONTRIBUTING.md`, generated API reference, or existing `doc/adr/` directory. + +### 3. Gather Evidence + +Use the narrowest repository evidence that can support each selected topic: + +| Evidence | Can establish | +| --- | --- | +| Source code | Implemented behavior and boundaries | +| Tests | Expected and protected behavior | +| Schemas and migrations | Structural API and data contracts | +| Configuration and infrastructure | Available mechanisms and deployed topology | +| CI workflows | Enforced checks and contribution flow | +| Existing docs and decisions | Declared intent, policy, and rationale | +| User confirmation | Product intent and organizational policy | + +Do not promote an implementation detail into policy without supporting documentation or user confirmation. Be especially conservative with security, retention, compliance, SLOs, incident response, and product intent. + +### 4. Report the Scan + +Include: + +1. Existing documentation locations and the likely canonical location. +2. Coverage per selected topic: `strong`, `partial`, `missing`, or `insufficient evidence`. +3. Evidence inspected. +4. Suggested action: keep, link, update, create, or confirm with the user. +5. A concise list of candidate documents. + +Example: + +```markdown +| Topic | Coverage | Evidence | Suggested action | +| --- | --- | --- | --- | +| Architecture | Partial | Service modules, deployment config | Add overview | +| API | Strong | OpenAPI source | Link; do not duplicate | +| Runbooks | Missing | No operational procedure found | Requires operator input | +``` + +For a scan-only request, stop here. + +### 5. Create or Update Selected Documentation + +After the user selects topics, create only documents supported by evidence. If initializing `docs/`, start with `docs/README.md` plus the selected content. Add a topic directory only when placing a real document inside it. + +Possible mature structure: + +```text +docs/ +├── architecture/ +├── development/ +├── operations/ +├── security/ +├── runbooks/ +├── specifications/ +├── api/ +├── data/ +├── product/ +└── contributing/ +``` + +Do not create this whole tree by default. + +For generated documents: + +- State current behavior separately from desired policy. +- Add source paths or a short `Sources` section when it helps future verification. +- Mark drafts and unresolved questions clearly. +- Prefer text-based diagram sources when the repository supports them; keep rendered assets beside their source. +- Keep architecture decisions short, one decision per file, with status, context, decision, rationale, consequences, and links. +- Supersede accepted decisions with a new record rather than silently rewriting their history. + +### 6. Promote Work-Item Knowledge + +When a decision or finding under `.agents/work///` becomes relevant to future unrelated work: + +1. Find the repository's canonical documentation or decision location. +2. Create or update the canonical document with the enduring result, not the work-item transcript. +3. Link from the work item to the canonical document and back when useful. +4. Avoid two competing sources of truth. +5. Update `AGENTS.md` only when agents need a concise navigation pointer or universal instruction. + +## Verification + +After writing: + +- Check local links and referenced paths. +- Run the repository's Markdown or documentation checks when available. +- Re-read claims against the evidence used to write them. +- Report anything that still requires domain-owner, security, product, or operations review. + +## Definition Of Done + +Documentation work is done when the canonical location is respected, only selected and evidence-backed documents were changed, navigation points to the new material, relevant checks pass, and unsupported claims are explicitly left as questions rather than presented as facts. diff --git a/AGENTS.md b/AGENTS.md index a4b1054..da12b2a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,7 +30,7 @@ dot-agents/ ├── install.sh # Main installation script ├── .agents/ │ ├── work/ # Work-item guidance installed into projects -│ ├── skills/ # adapt, agent-work, feature-planning, research, tmux +│ ├── skills/ # adapt, agent-work, documentation, feature-planning, research, tmux │ ├── research/ # Reusable research notes │ ├── references/ # External reference repos (gitignored) │ └── scripts/ # sync.sh @@ -46,6 +46,7 @@ dot-agents/ | --- | --- | | `Run adapt` | Analyze project and fill in `AGENTS.md` sections | | `Create a new work item for ...` | Create durable `.agents/work/` context | +| `Run a documentation scan` | Assess selected project-documentation topics before writing | | `Research ...` | Investigate and save work-local or reusable findings | | `Create/refine a plan for ...` | Produce implementation-ready tasks in the active plan file | | `Write a handoff prompt for ...` | Produce a paste-ready prompt for a new implementation thread | diff --git a/AGENTS.template.md b/AGENTS.template.md index 6a32311..45a7f55 100644 --- a/AGENTS.template.md +++ b/AGENTS.template.md @@ -47,6 +47,7 @@ project/ │ └── skills/ # Agent skills │ ├── adapt/ │ ├── agent-work/ +│ ├── documentation/ │ ├── feature-planning/ │ ├── research/ │ └── tmux/ @@ -59,6 +60,7 @@ project/ | --- | --- | | `Run adapt` | Analyze project and fill in `AGENTS.md` sections | | `Create a new work item for ...` | Create durable `.agents/work/` context | +| `Run a documentation scan` | Assess selected project-documentation topics before writing | | `Research [topic]` | Investigate and save work-local or reusable findings | | `Create a plan for ...` | Produce implementation-ready tasks in the active plan file | | `Write a handoff prompt for ...` | Produce a paste-ready prompt for a new implementation thread | diff --git a/CHANGELOG.md b/CHANGELOG.md index fc7ed30..2468c9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## [Unreleased] +### Added + +- `documentation` skill for discovering existing docs, scanning selected documentation topics, optionally initializing `docs/`, and promoting enduring work-item knowledge without creating empty scaffolding or unsupported claims. + ## [0.3.0] - 2026-06-22 ### Changed diff --git a/docs/skills.md b/docs/skills.md index b8a419a..983f3b6 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -8,6 +8,7 @@ Skills are specialized instructions that agents load for specific workflows. dot | --- | --- | --- | | [adapt](#adapt) | `Run adapt` | Analyze project, fill in `AGENTS.md` | | [agent-work](#agent-work) | `Create a work item` | Create and maintain `.agents/work/` context | +| [documentation](#documentation) | `Run a documentation scan` | Discover, assess, and maintain canonical project docs | | [feature-planning](#feature-planning) | `Create a plan`, `write a handoff prompt` | Turn context into plans and new-thread prompts | | [research](#research) | `Research [topic]` | Investigate and save work-local or reusable findings | | [tmux](#tmux) | `tmux`, `background process` | Manage background processes | @@ -40,6 +41,16 @@ Use it to create work items, list active work, place artifacts deliberately, and **Details:** [.agents/skills/agent-work/SKILL.md](../.agents/skills/agent-work/SKILL.md) +## documentation + +Discovers the repository's existing documentation convention before proposing a location. It can scan selected topics, initialize `docs/` with approval when no canonical location exists, create only needed topic directories, verify docs against repository evidence, and promote enduring work-item decisions into canonical project documentation. + +Available topics include architecture, development, operations, security, runbooks, specifications, API, data, product, and contributing. Scans are read-only by default, and unsupported policy or intent is reported for confirmation rather than invented. + +**Invoke:** `Run a documentation scan for architecture, API, and data` + +**Details:** [.agents/skills/documentation/SKILL.md](../.agents/skills/documentation/SKILL.md) + ## feature-planning Turns work-item context into implementation-ready plans and paste-ready handoff prompts. diff --git a/install.sh b/install.sh index b9dbd94..0752743 100755 --- a/install.sh +++ b/install.sh @@ -481,7 +481,7 @@ format_version_string() { } # Core skills that come from upstream -CORE_SKILLS="adapt agent-work feature-planning research tmux" +CORE_SKILLS="adapt agent-work documentation feature-planning research tmux" RETIRED_CORE_SKILLS="ralph" RETIRED_LEGACY_GUIDANCE_FILES=".agents/plans/AGENTS.md .agents/prds/AGENTS.md .agents/plans/TEMPLATE.md .agents/prds/TEMPLATE.md" diff --git a/test/fixtures/sample-archive.tar.gz b/test/fixtures/sample-archive.tar.gz index ad61b71..6cb74c4 100644 Binary files a/test/fixtures/sample-archive.tar.gz and b/test/fixtures/sample-archive.tar.gz differ diff --git a/test/integration/install.bats b/test/integration/install.bats index d7e975d..c03c279 100755 --- a/test/integration/install.bats +++ b/test/integration/install.bats @@ -60,6 +60,7 @@ teardown() { [ -f ".agents/references/.gitkeep" ] [ -f ".agents/skills/adapt/SKILL.md" ] [ -f ".agents/skills/agent-work/SKILL.md" ] + [ -f ".agents/skills/documentation/SKILL.md" ] [ -f ".agents/skills/feature-planning/SKILL.md" ] [ -f ".agents/skills/research/SKILL.md" ] [ -f ".agents/skills/tmux/SKILL.md" ] @@ -816,6 +817,7 @@ teardown() { [ -L ".claude/skills/adapt" ] [ -L ".claude/skills/agent-work" ] + [ -L ".claude/skills/documentation" ] [ -L ".claude/skills/feature-planning" ] [ -L ".claude/skills/research" ] [ -L ".claude/skills/tmux" ]