jrenaldi79/harness-engineering/documentation

Project self-documentation

Keep instructions short: instruction file -> documentation index -> relevant document. Use the deterministic scripts for discovery and validation; update explanatory prose from the actual implementation and reviewed evidence.

Locate resources and assess the project

Resolve this loaded SKILL.md's directory as SKILL_DIR. Its scripts/ and references/ directories are self-contained siblings; do not search another plugin's cache or assume a fixed user home, shell or install location.

Read the target project's applicable instructions first. Check Node.js is 18+ and inspect the existing documentation configuration, instruction markers and hook arrangement. Choose explicit source roots and a documentation directory. Source inventories read filenames only. Do not include sensitive/private data paths or broaden an existing allowlist without reviewing its scope.

Read metadata and lifecycle rules when classifying or creating documents, migrating a catalog, or resolving validation failures.

Set up documentation only

Before the first installation, create documentation.config.json when a different generator owns tree/module blocks or a handwritten index must remain intact:

{
  "version": 1, "sourceRoots": ["src", "scripts"], "docsRoot": "docs",
  "instruction": "CLAUDE.md", "index": "docs/classified-index.md",
  "strict": false, "managedMarkers": ["docs"]
}

Use reviewed project roots. This example preserves the handwritten docs/index.md and existing tree/module generator; new projects can use the installer defaults.

Run the bundled installer from the target project with absolute, quoted paths:

node "<SKILL_DIR>/scripts/install.js" --target="<project-root>"

The default instruction file is CLAUDE.md. Select --instruction=AGENTS.md when appropriate; set --sources=src,lib,scripts and --docs=docs to reviewed roots. The installer preserves authored text and configuration, copies portable scripts to scripts/self-documentation/, and generates the configured index. It does not install package dependencies or edit Claude/Codex settings or permission files.

If an existing handwritten index conflicts, inspect it and agree on adoption before using --adopt-index. Keep existing explanatory content elsewhere before adopting an index that the generator will own. Do not use adoption to overwrite an unrelated file. Modified owned scripts require a deliberate upgrade decision.

Git hooks are optional. After explicit hook adoption is within the user's scope, run the installed hook helper; it preserves existing hooks and custom hooksPath, printing the integration command when automatic installation is unsuitable.

node scripts/self-documentation/install-hook.js

Installing this plugin or skill alone does not activate a filesystem watcher. The installed scripts work after the plugin cache is removed.

Folder notes are opt-in (--folder-notes, config folderNotes: true). Each folder that directly holds source files, below the source roots, then needs a note named like the instruction file (src/llm/CLAUDE.md). Claude Code auto-loads it when working in that folder, and its frontmatter description heads the folder's inventory group. Refresh and check fail on a missing or unclassified note, and on an orphan note with no source files left beneath its folder (a parent note over sub-folders is fine). Author notes from the code (owns, entry points, invariants, tests, gotchas) before enabling it on an existing project. Describe what exists now; plans and "coming soon" belong in docs/, because time-bound phrasing rots when the plan lands. Use exclude for folders that should not need one; it also drops their files from the inventory. Folders named private, secrets, runs, outputs, fixtures, cache(s), build(s), dist, coverage, node_modules or __pycache__ are always skipped, at any depth.

If another generator owns existing tree or module blocks, use optional config managedMarkers: ["docs"] to preserve them. Omit it for the default ownership of docs, tree and modules. All AUTO markers still must be balanced and well formed.

Maintain docs during development

When files or modules change, update the relevant handwritten documentation in the same change. Explain behavior, commands, interfaces and gotchas that changed. Do not treat a successful inventory check as proof that prose is correct.

For a new Markdown document, add all five metadata fields described in the reference. Use catalog metadata for attachments without opening their contents. Classify completed plans as history; proposals and temporary notes are not operational authority. Never infer approvals from document lifecycle metadata.

node scripts/self-documentation/generate.js
node scripts/self-documentation/generate.js --check
node scripts/self-documentation/generate.js --strict --check

Review generated changes and stage them with the intended inputs. The generator never stages files. A staged check validates exactly the Git index, so unstaged fixes cannot conceal an inconsistent commit:

node scripts/self-documentation/generate.js --staged
node scripts/self-documentation/generate.js --staged --write   # render from the index when untracked drafts exist

Catalog-to-frontmatter migration is explicit. Preview first, review the affected Markdown documents, then apply; normal refresh never rewrites authored metadata.

node scripts/self-documentation/migrate.js
node scripts/self-documentation/migrate.js --write

Verify and report

Run refresh and check after installation. When Git integration is selected, also validate a staged snapshot containing the configuration, inputs and outputs. Report created/updated files, unclassified documents, preserved-hook integration steps and any runtime limitations. Keep temporary/historical material visibly separate and read only the documents relevant to the current task.