Documentation Writing

Documentation Management

Create and maintain .claude/skills/project-knowledge/ from the evidence source the user named.

Outside Feature Finalization Mode, follow create-project-knowledge.md when the user starts or continues initial documentation and either its interview is still in progress or Project Knowledge is missing, still a template, or only partially filled. Apply project-knowledge-structures.md for content ownership and structure. After writing, run the manual sync and continue at Documentation Review.

When the user explicitly asks to reorganize existing Project Knowledge, apply project-knowledge-structures.md. Ordinary updates preserve the filled structure already in use.

Manual Project Documentation Sync

Project documentation source of truth is Claude-side: CLAUDE.md and .claude/**. Codex-side AGENTS.md and .codex/** are generated runtime files. No scheduled job performs this conversion. The agent that changes the Claude source runs the matching command immediately and reviews the generated result before finishing the task.

After changing a project CLAUDE.md or any project-local .claude/** file, immediately run:

~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply

If sync reports a conflict, stop and report it. Commit generated project .codex/** / AGENTS.md changes with their Claude sources, except .codex/.sync/**, which is host-local runtime state. When an approved deletion or rename produces orphaned managed outputs, verify that every reported path corresponds to that approved source change, then remove those generated leftovers with:

~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply --prune --confirm-delete

If the orphan list contains anything else, stop and report it instead of pruning unrelated output.

Nested Agent Workspaces

Some projects keep an agent workspace under a subdirectory (for example nested-workspace/.claude/**) while the repository root exposes selected skills or agents through symlinks in root .claude/**. In that case, sync both levels:

~/.claude/scripts/sync-to-codex.sh --project "$PWD/nested-workspace" --apply
~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply

Verify root .codex/agents / .codex/skills include every root-exposed agent or skill. A generated file existing only inside the nested workspace is not enough when the root runtime must invoke it. Treat .codex/.sync/** as host-local evidence: do not commit or synchronize it.

Documentation Principles

The reader should understand the project's purpose, structure, decisions, and operation without reconstructing them from code. Record durable project-specific facts: purpose and business logic; architecture, components, and their relationships; lasting agreements, decisions, and why those decisions were made; security rules and configuration names; deployment, operations, monitoring, recovery, where key code lives, and operational details an agent cannot infer from configuration alone.

Do not list functions, classes, local control flow, or implementation details that can be read from code. Treat an important non-obvious rule that applies only to a particular code path as code-owned: keep it out of Project Knowledge, and change a nearby code comment only when the user also requested source changes.

Keep generic framework, Git, Linux, SSH, Docker, journalctl, and systemctl explanations out of Project Knowledge. For operations, preserve facts such as host, user, non-default port, SSH alias, service or container name, log location, monitoring URL, environment-variable names, and emergency recovery behavior. Store an exact command only when the procedure is non-standard and cannot be recovered from project configuration.

Use source links instead of code snippets or pseudocode. Each fact has one owner file; update the existing section and cross-reference it elsewhere instead of appending a duplicate. patterns.md contains project-specific conventions, not general implementation advice.

Plans, user specs, tech specs, handoffs, and other work/ artifacts are evidence, not owners of current project state. Keep changing inventories in their authoritative registry, configuration, or runtime source; Project Knowledge records the durable rule, not current counts or members. If a Project Knowledge claim depends on a completed work artifact, correct that boundary instead of expanding the artifact.

File size alone is not a finding. Report a size-related issue only when evidence demonstrates duplication, stale content, implementation-level detail, or a structure that prevents useful selective loading.

Phase 1: Select the Evidence Source

Use the narrowest mode that matches the user's request:

1. One current change: inspect the changed lines, the files they affect, and related callers or contracts needed to understand the durable result.
2. Named commit or range: inspect exactly that commit or range plus the related files needed to interpret it.
3. Recent history: when the user asks for the last N commits, inspect those N commits and their resulting current code.
4. Full update or audit: inspect current code, all Project Knowledge, and CLAUDE.md.
5. Specific documentation edit, consistency check, or status: inspect the named section and the documentation it can contradict.
6. Feature finalization: use this mode only when the user explicitly asks to finish a feature (including /done) and provides or identifies work/{feature}/.

Do not search for user-spec.md or require it outside feature-finalization mode. A normal "update documentation" request does not archive work or create a finalization commit.

Phase 2: Establish Durable Facts

1. Read the selected evidence and current target documentation before editing.
2. Trace names, versions, service boundaries, data model, environment variables, deployment triggers, and operational facts to current sources. For full audits, also check placeholders, duplication, stale links, generic tutorial content, inconsistent terminology, and facts that no longer match the code.
3. If Project Knowledge has no writable owner in the selected non-creation mode, report that no documentation target exists. Feature finalization keeps its explicit missing-documentation behavior below rather than starting an initial project interview from feature evidence.

Phase 3: Update or Report

1. For an edit/update request, integrate facts into existing sections and update any directly contradicting references.
2. For an audit, consistency check, or status request, report evidence-backed issues without changing files unless the user also asked for fixes. Status classifications are filled, partial, template, or missing; size alone does not determine status.
3. After changing a project CLAUDE.md or project-local .claude/**, run the manual sync described above. For a nested workspace, sync the nested source first and the repository root second.

Documentation Review

1. Run no more than two review waves. After documentation edits, run wave 1 with a fresh documentation-reviewer with no model override. Give it the complete touched documents, the selected evidence boundary, related code and contracts, and the user's request. It returns its JSON result directly. Include reviewers required by other active skills in these same waves instead of starting a separate wave sequence.
2. Review findings are diagnoses, not a work queue. Check the evidence and exact correction; apply only an authorized local correction to agreed normal documentation. If the scenario is rare or unagreed, or the correction adds behavior, state, entities, contracts, dependencies, architecture, or material complexity, reject it with a short reason or ask the user before editing. user_decision_required: false does not replace this check. Surface unrelated pre-existing defects without changing them.
3. If an accepted correction changes the reviewed documentation, run wave 2 with a fresh reviewer. Stop after a clean wave or when no authorized correction changes the documentation.
4. After wave 2, do not launch another reviewer automatically. Make only remaining local corrections inside the requested documentation change, run the applicable direct checks and manual sync, and show the user any remaining findings or required decisions.

Feature Finalization Mode

1. Read user-spec.md, decisions.md when present, the implementation, and the relevant Git history. Compare the implemented result with the agreed spec.
2. If the feature is evidently incomplete, explain the concrete gap and ask whether to continue finalization.
3. Update only affected Project Knowledge through Phases 2-3 and Documentation Review. If Project Knowledge is missing, report that the documentation update was skipped and continue archival and finalization.
4. Remove active Project Knowledge and backlog links that treat work/{feature}/ as a current source; do not add current operational inventory to completed artifacts.
5. Move work/{feature}/ to work/completed/{feature}/ after documentation review.
6. Commit the Project Knowledge changes and archive move with a concise documentation commit, then report the updated files and completed-feature path.

This is the only mode that reads feature artifacts by default, archives a feature, or creates the finalization commit.

Agent Entry Point

Keep CLAUDE.md minimal: project name, one-line description, reference to the Project Knowledge skill, backlog path, and default branch. Detailed project information belongs in Project Knowledge. Template: ~/.claude/skills/project-initialization/assets/new-project/CLAUDE.md.

Self-Verification

• The requested documentation outcome matches the selected evidence and remains within scope.
• No unresolved material deviation or contradiction is hidden from the user.