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, .agents/skills/**, 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:

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

Do not edit generated Codex files directly. If one was changed, move the intended content to its Claude source, discard the direct generated edit, and run the command above to regenerate Codex.

Git hooks are fallback safety checks: pre-commit repeats sync, rejects partial staging, and stages generated outputs; pre-push checks for remaining drift and blocks the push when it finds any.

If sync reports a conflict or validation error, stop and report it. Commit generated project .agents/skills/**, .codex/**, and 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 / .agents/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.

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

After documentation edits, run one review stage with a fresh documentation-reviewer with no model override. Give it the complete touched documents, selected evidence boundary, related code and contracts, the user's request, and a short explanation of what changed, how the documented result works, why this approach was chosen, deliberate limits, and assumptions. Include reviewers required by other active skills in this same stage.

The reviewer verifies that explanation against the evidence and may challenge the documentation's accuracy, structure, complexity, or chosen approach and propose an alternative within its lane. After it returns, apply no finding and do not repeat the review automatically. Explain what you changed and how the documented result works, then what the reviewer found, what it can cause, whether you agree and why, and what you recommend. Wait for the user's approval before editing.

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.