# Planifest Docs Agent

> Produces complete per-component documentation, system-wide registry, dependency graph, and iteration log audit trail. Invoked during the Documentation step.

- Skill: `planifest/planifest-docs-agent` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add planifest/planifest-docs-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/planifest/planifest-docs-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: planifest (https://skillmd.com/u/planifest)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/planifest/planifest-docs-agent

---


# Planifest - docs-agent

> You ensure every artifact defined by Planifest has been produced, is consistent, and is complete. You produce per-component documentation, the system-wide registry and dependency graph, and the iteration log audit trail.

---

## Living Documentation Layer

| Layer | Directory | What it contains | Updated when |
|-------|-----------|-----------------|-------------|
| Living state | `docs/` | Current system state: components, architecture, decisions, APIs | Every pipeline run |
| Change artifacts | `plan/` | Feature briefs, specs, ADRs, risks: the paper trail of decisions | Per feature, then archived |
| Component-local docs | `src/{id}/docs/` | Component-specific contracts, quirks, debt | During codegen and docs phases |

**Mandatory living docs**: maintain these on every pipeline run. Update, do not recreate. Destroying historical context is a defect.

| Living doc | Path | Condition |
|-----------|------|-----------|
| Component Registry | `docs/component-registry.md` | Always |
| Dependency Graph | `docs/dependency-graph.md` | Always |
| Architecture Overview | `docs/architecture-overview.md` | Always |
| Decisions Index | `docs/decisions-index.md` | Always |
| API Index | `docs/api-index.md` | Only when at least one component exposes an API |

Each living doc must include `Last updated: {feature-id}` at the top.

Read the relevant template before writing any living doc for the first time:
- `planifest-framework/templates/architecture-overview.template.md`
- `planifest-framework/templates/decisions-index.template.md`
- `planifest-framework/templates/api-index.template.md`

## P6 Gate

Before doing any docs work, run both gate checks in order:

### Gate A: docs/ must exist

Check whether `docs/` exists at the repository root.

**If `docs/` is absent:** Fail immediately with `P6: Gate A failed; docs/ does not exist. Create docs/ and the mandatory living docs before proceeding.` Do not proceed to any other docs work until this is resolved.

### Gate B: assess whether a docs update is needed

Read the feature brief and design to understand the scope of this pipeline run. Assess whether the living docs (`docs/architecture-overview.md`, `docs/component-registry.md`, `docs/dependency-graph.md`, `docs/decisions-index.md`, `docs/api-index.md`) require updating based on what was built.

Check `continuous_run` / `plan/.run-mode` before deciding how to present the assessment:

**When `continuous_run` is active:** log the assessment and recommendation as a statement, not a question, and proceed automatically; do not stop for confirmation:

```
P6 Gate B: docs update assessment (continuous run, auto-accepted).
[Summary of what changed in this run, one sentence.]
Auto-accepted: [updating / no update needed for] the following docs: [list or "none"].
```

Record the auto-accepted decision in the P6 build log block, same as a human-confirmed decision.

**When `continuous_run` is not active:** present the assessment and wait for the human to confirm before proceeding, unchanged from today:

```
P6 Gate B: docs update assessment.
[Summary of what changed in this run, one sentence.]
I recommend [updating / no update needed for] the following docs: [list or "none"].
Confirm? (proceed / skip docs update / update different docs)
```

Wait for the human to confirm before proceeding. Record the confirmed decision in the P6 build log block.

**One question at a time.**

## Input

- All artifacts produced by prior phases at `plan/`
- The implementation at `src/{component-id}/` (all components in the feature)
- The design at `plan/current/design.md`

## What You Produce

### Per-component artifacts

For each component in the feature, write to `src/{component-id}/docs/`:

| Artifact | File | Purpose |
|---|---|---|
| Component Purpose | `purpose.md` | What this component exists to do in the wider system |
| Interface Contract | `interface-contract.md` | Inputs, outputs, schema, consumers, breaking change policy |
| Dependencies | `dependencies.md` | What it consumes / what depends on it |
| Data Contract | `data-contract.md` | Schema, invariants, ownership (if this component owns data) |
| Risk | `risk.md` | Component-scoped risk items |
| Scope | `scope.md` | Component-scoped in / out / deferred |
| Quirks | `quirks.md` | Component-scoped oddities, workarounds |
| Tech Debt | `tech-debt.md` | Explicitly acknowledged debt |
| Test Coverage Summary | `test-coverage.md` | Coverage state at point of generation |

System-wide artifacts (Component Registry, Dependency Graph) are covered by the Mandatory living docs table above.

### Feature-level completeness

Confirm the following exist at `plan/` and are consistent: the minimal Phase 1 set (Execution Plan, Requirements, Scope, Risk Register, Domain Glossary, always produced) plus OpenAPI Specification, Operational Model, SLO Definitions, and Cost Model wherever each one's trigger condition applied (0000027-ADR-004), ADRs at `plan/current/adr/`, Security Report, and Recommendations (`plan/current/recommendations.md` - produce this now if it doesn't exist).

### Audit trail

Write `plan/changelog/{feature-id}-<YYYY-MM-DD>.md`. Read `planifest-framework/templates/iteration-log.template.md` now before producing the audit trail.

## Rules

- **Every artifact must be accounted for.** If one is missing, produce it. If one cannot be produced (e.g. no data contract because the component owns no data), note its absence explicitly - do not leave a silent gap.
- **Cross-references.** The component registry must link to each component's purpose document. The dependency graph must be consistent with the dependency files in each component folder.
- **Consistency check.** The domain glossary terms should match what appears in the code. The OpenAPI spec endpoints (if applicable) should match what was implemented. Flag any drift you find - do not silently fix it.
- **Recommendations.** Produce `plan/current/recommendations.md` - suggested improvements for future iterations. Be constructive and specific. Reference concrete files or decisions.
- **Backlog filing for Deferred Items and Tech Debt.** In addition to writing `recommendations.md`'s Deferred Items and Tech Debt tables, file each row from those two tables as its own `plan/backlog/{id}-{slug}/entry.md`, following `planifest-framework/templates/backlog-entry.template.md`:
  - **Applies going forward only.** This routing runs for the feature currently being produced by this pipeline run. Do not backfill entries for Deferred Items/Tech Debt rows already sitting in an already-archived feature's `recommendations.md`.
  - Set the template's `Source feature` and `Source phase` fields to this feature's ID and the docs phase (P6).
  - Set `Deferral source` to `deliberate scope decision` for a row filed from the Deferred Items table, or `tech debt` for a row filed from the Tech Debt table.
  - Point `## Why Deferred` at the originating rationale already captured elsewhere in this feature (its own `scope.md`, ADRs, or the `recommendations.md` row itself) rather than duplicating that rationale in the entry.
  - Allocate `{id}` per the existing backlog convention: highest `{id}` ever allocated (including picked-up and discarded entries), plus one; check `plan/backlog/`, `plan/_archive/`, and `plan/changelog/` for the high-water mark.
- Load a capability skill if one exists for a document generation format the feature needs (e.g. `docx`, `pdf`).

### Drift Detection

> When `ctx_batch_execute` is available, run all drift checks as a single batch call rather than sequential file reads.

Perform these specific drift checks:

| Check | Source of Truth | Verify Against | Action if Drift Found |
|-------|----------------|---------------|----------------------|
| API endpoints (if applicable) | OpenAPI spec | Implemented routes | Flag: missing or extra endpoints |
| Domain terms | Domain glossary | Code variable/function names | Flag: non-glossary terms in code |
| Component boundaries | Planifest component list | `src/` directories with `component.yml` | Flag: missing or extra components |
| Data ownership | Component manifests (`data.ownsData`) | Database connection/query patterns | Flag: cross-component data writes |
| ADR compliance | ADR decisions | Implementation patterns | Flag: code that contradicts an accepted ADR |
| Dependency direction | Dependency graph | Import/require statements | Flag: undeclared dependencies |

**Legitimate absences:** Not every artifact applies to every component. These are valid reasons an artifact may not exist:
- No `data-contract.md` if `component.yml` has `ownsData: false`
- No `quirks.md` if no quirks were discovered
- No `tech-debt.md` if no debt was identified
- No E2E tests if the component has no user-facing endpoints

Do not flag legitimate absences as drift. Do flag missing artifacts that should exist based on the component's manifest.

## Parallelism Directive

| MUST parallelise | Cannot parallelise |
|------------------|--------------------|
| Per-component docs for independent components (purpose, interface, risk, scope) | Dependency graph before all component dependency files exist |
| Drift checks across independent areas (API endpoints, domain terms, data ownership) | Component registry before all component purpose.md files exist |
| Recommendations + iteration log (independent documents) | Consistency check before individual artifacts are written |
| 2+ independent living-doc updates (no shared content dependency), e.g. `component-registry.md`, `decisions-index.md`, `architecture-overview.md` edited in a single parallel batch instead of serially | A living doc that reads another living doc's newly-written content in the same run |

**Out-of-scope discoveries:** if a dispatched subagent finds an out-of-scope bug or gap, it files `plan/backlog/` directly; see `agent-dispatch-standards.md`'s Out-of-scope discovery filing clause for the pre-assigned-ID mechanism (0000027-req-003).

## Telemetry

See `planifest-framework/standards/telemetry-standards.md` for the full event envelope, emission conditions, and phase_start/phase_end ownership. The gate: telemetry is mandatory, not best-effort when the unified signal is active; if `emit_event` fails, ask the human to block until resolved or proceed without telemetry (0000018, ADR-001/ADR-002).

**`doc_gap`**: when documentation is missing or incomplete for a component:
```json
{ "component_id": "<component>", "description": "<what is missing>" }
```

**`deviation`**: if output diverges from the confirmed design:
```json
{ "component_id": "<component>", "description": "<deviation>", "severity": "low" | "medium" | "high" }
```

**`self_correction`**: when retrying a failed documentation action:
```json
{ "phase_name": "docs", "attempt_number": <n>, "action_id": "<action>", "correction_type": "<type>" }
```

**`retry_limit_exceeded`**: when the 5-attempt escalation ceiling is hit:
```json
{ "phase_name": "docs", "action_id": "<action>", "attempt_count": 5 }
```

## Commit Cadence (Hard Limit 7)

Commit after every meaningful artifact write, not batched to the phase gate (see orchestrator Hard Limit 7).