Add project documentation skill

.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 |

.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/<category>/<slug>/` 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.

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 |

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 |

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

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.

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"
 

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" ]