Manage Project Docs
Treat documentation as durable project state, workflows as state transitions,
and executable checks as invariant proofs. Optimize for the repository owner
and future agents returning without conversational memory, not a public
audience unless the project is public.
Preserve authorization
- Read and obey the repository's existing agent instructions first.
- Treat discussion, exploration, critique, resume, and audit requests as
read-only unless the user explicitly requests changes.
- Treat a direct bounded change request as implementation authorization for
that change.
- Require an explicitly accepted spec before starting a new project or a
substantial, ambiguous, or cross-cutting feature.
- Never promote a draft spec to accepted on the user's behalf.
- Never change a normative contract merely to make implementation and prose
agree. Surface the conflict and request a decision.
Select one operation
| User need |
Operation |
Read |
| Start or retrofit a documentation system |
Bootstrap |
references/bootstrap.md |
| Return after lost context or prove the happy path |
Resume |
references/resume.md |
| Shape a material implementation slice |
Plan |
references/plan.md |
| Reconcile a completed implementation slice |
Close |
references/close.md |
| Compare documentation claims with live evidence |
Audit |
references/audit.md |
| Turn a recurring failure into a reusable guardrail |
Promote |
references/promote.md |
Read references/document-model.md when choosing
documents, assigning authority, resolving apparent contradictions, or deciding
which bundled templates to use. Do not load every workflow reference by
default.
Run the common preflight
- Locate the repository root and read its instruction files.
- Inspect version-control status without changing it.
- Inventory documentation by content and apparent purpose; do not infer a
document's authority from its filename.
- Identify the requested operation and whether it authorizes writes.
- Separate confirmed facts from proposals and unresolved questions.
- State the intended reads or changes before broad exploration.
Use the bundled resources
- Copy from
assets/templates/ only during an authorized bootstrap or
documentation change. Resolve every template marker; never overwrite an
existing document blindly.
- Run
scripts/check_docset.py REPO to check the universal core: required
front-door documents, unresolved placeholders, local Markdown links, spec
statuses, status freshness, and close-residue warnings. Use --help for
optional requirements and strong-claim review.
- Keep project-specific semantic proofs in the project itself. A generic
checker cannot prove wire behavior, privacy guarantees, state transitions,
schemas, or cross-repository conformance.
Maintain the continuity boundary
Keep these categories distinct:
- durable intent;
- current operational truth;
- normative invariants;
- historical decisions;
- proposed or accepted work;
- generated reference material.
When one fact appears in multiple categories or system layers, identify every
representation affected by a change and reconcile them together. Prefer an
honest unknown, historical, or proposed label over invented precision.
Finish visibly
Report:
- the operation performed;
- documents or claims inspected or changed;
- executable checks run and their results;
- unresolved contradictions, unknowns, or stale claims;
- the next authorized transition, if one exists.
Do not call the repository continuous merely because documents exist. Confirm
that the owner can find the current state, reach one successful use, and
identify what may happen next without reading a defense of the last session.
1---2name: manage-project-docs3description: Maintain repository documentation as a continuity protocol tied to code, tests, contracts, and operational truth. Use when Codex needs to bootstrap or retrofit project docs, resume work in a dormant or unfamiliar repository, draft an implementation spec, reconcile documentation before closing a material change, audit documentation against a live codebase, or promote a recurring failure into a reusable workflow or check.4metadata:5 source: https://skillmd.com/skills/resonatingloop/manage-project-docs6---78# Manage Project Docs910Treat documentation as durable project state, workflows as state transitions,11and executable checks as invariant proofs. Optimize for the repository owner12and future agents returning without conversational memory, not a public13audience unless the project is public.1415## Preserve authorization1617- Read and obey the repository's existing agent instructions first.18- Treat discussion, exploration, critique, resume, and audit requests as19 read-only unless the user explicitly requests changes.20- Treat a direct bounded change request as implementation authorization for21 that change.22- Require an explicitly accepted spec before starting a new project or a23 substantial, ambiguous, or cross-cutting feature.24- Never promote a draft spec to accepted on the user's behalf.25- Never change a normative contract merely to make implementation and prose26 agree. Surface the conflict and request a decision.2728## Select one operation2930| User need | Operation | Read |31|---|---|---|32| Start or retrofit a documentation system | Bootstrap | [references/bootstrap.md](references/bootstrap.md) |33| Return after lost context or prove the happy path | Resume | [references/resume.md](references/resume.md) |34| Shape a material implementation slice | Plan | [references/plan.md](references/plan.md) |35| Reconcile a completed implementation slice | Close | [references/close.md](references/close.md) |36| Compare documentation claims with live evidence | Audit | [references/audit.md](references/audit.md) |37| Turn a recurring failure into a reusable guardrail | Promote | [references/promote.md](references/promote.md) |3839Read [references/document-model.md](references/document-model.md) when choosing40documents, assigning authority, resolving apparent contradictions, or deciding41which bundled templates to use. Do not load every workflow reference by42default.4344## Run the common preflight45461. Locate the repository root and read its instruction files.472. Inspect version-control status without changing it.483. Inventory documentation by content and apparent purpose; do not infer a49 document's authority from its filename.504. Identify the requested operation and whether it authorizes writes.515. Separate confirmed facts from proposals and unresolved questions.526. State the intended reads or changes before broad exploration.5354## Use the bundled resources5556- Copy from `assets/templates/` only during an authorized bootstrap or57 documentation change. Resolve every template marker; never overwrite an58 existing document blindly.59- Run `scripts/check_docset.py REPO` to check the universal core: required60 front-door documents, unresolved placeholders, local Markdown links, spec61 statuses, status freshness, and close-residue warnings. Use `--help` for62 optional requirements and strong-claim review.63- Keep project-specific semantic proofs in the project itself. A generic64 checker cannot prove wire behavior, privacy guarantees, state transitions,65 schemas, or cross-repository conformance.6667## Maintain the continuity boundary6869Keep these categories distinct:7071- durable intent;72- current operational truth;73- normative invariants;74- historical decisions;75- proposed or accepted work;76- generated reference material.7778When one fact appears in multiple categories or system layers, identify every79representation affected by a change and reconcile them together. Prefer an80honest `unknown`, `historical`, or `proposed` label over invented precision.8182## Finish visibly8384Report:8586- the operation performed;87- documents or claims inspected or changed;88- executable checks run and their results;89- unresolved contradictions, unknowns, or stale claims;90- the next authorized transition, if one exists.9192Do not call the repository continuous merely because documents exist. Confirm93that the owner can find the current state, reach one successful use, and94identify what may happen next without reading a defense of the last session.