Build code wiki

Build Code Wiki

Create or refresh the repository's Code Wiki without requiring a standalone application. Keep semantic analysis in the agent and delegate discovery, hashing, header edits, index writing, and validation to the bundled scripts.

Respect the requested write scope

Treat an explicit path restriction from the caller as a hard boundary. Do not ask to widen it merely because a complete Code Wiki would normally require repository-level artifacts.

Use scoped header-only mode when the caller says to modify only a directory or set of files, or otherwise forbids writes outside that scope:

1. Document every eligible source file beneath the requested path, except generated, binary, minified, oversized, or unsupported files.
2. Add or replace only Code Wiki blocks in those files. Do not create or change .code-wiki/, repository configuration, or files outside the requested scope.
3. Do not refuse the task because a complete wiki.json cannot be produced within the boundary. A useful, accurate set of source headers is the required deliverable in this mode.
4. Enumerate eligible files under the allowed path, then work in small batches. Before adding each header, read the complete current source of that file. Never infer a header from the path, its imports, its directory, exported names, or a generic category such as API, model, task, utility, or prompt. A header formed by inserting a filename into a template is a defect, not documentation.
5. For every non-empty file, identify the specific business subject, primary operation or state, two or more concrete behaviors or decisions, and an observable result, state change, external interaction, or failure case where present. Use this evidence to draft the header. Read nearby code only when the file alone cannot establish its role. Do not read excluded or binary content.
6. Apply the category guidance without reducing the header to a category label: HTTP files must say which domain actions or data they expose and what they actually protect or orchestrate; persistence files must name their domain state and meaningful lifecycle or calculated behavior; background files must say what event or work is performed and what state or communication it affects; integration files must identify the external system and the translation or reconciliation performed; prompt files must identify the decision or report they elicit and the input context or output shape they establish; utility files must name the concrete transformations they centralize. Do not use exact function, class, route, field, or provider-client names.
7. Use source-specific language. A summary must contain concrete domain nouns and an action that come from the code, rather than a filename stem. Each non-empty description must mention at least two independently verifiable file-specific facts. For long files, each of the five required description lines must describe a separate behavior shown in that file. Do not add generic claims merely to reach five lines.
8. Avoid boilerplate and filename-derived phrasing. Do not use prose in the pattern "<technical category> for <filename>", "<filename> operations", "the <filename> logic", "the module owns", "returns a domain-specific result", "preserves explicit failure behavior", "checks ownership", or "coordinates database records". Do not use the filename, a filename-derived phrase, or a list of symbols as a substitute for the file's purpose.
9. If an existing Code Wiki block is malformed, leave that file untouched and report it. Otherwise preserve every non-Code-Wiki byte.
10. Audit all drafted headers before finishing. Compare every non-empty header with its siblings and rewrite it if a repeated substantive sentence or generic category label remains. Package initializers may share concise wording only when their full contents truly contain no import-time behavior.
11. If the scope is broad, document the most complex and central files first, then complete the remaining eligible files with accurate concise headers. Do not abandon the task or remove all drafted headers because further refinement would be valuable. Leave the best supported, non-generic documentation you can produce within the requested scope.
12. Report the modified, skipped index-only, unchanged, and failed files. Do not claim that a repository-level index was generated or validated.

Use the full workflow below only when the caller permits the repository-level .code-wiki/ artifacts and does not impose a narrower write scope.

Full-repository workflow

1. Resolve the target repository with git rev-parse --show-toplevel.
2. Create temporary inventory and plan files outside the repository.
3. Run python3 scripts/inventory.py --root <absolute-root> --output <inventory-file> from this skill directory.
4. Read header-rules.md before drafting any managed header.
5. Read wiki.schema.json before drafting the generation plan.
6. Read only files classified as added, changed, moved, missing-header, or malformed-header. Never read binary or index-only contents for summarization.
7. Reuse existing summaries and parsed header fields byte-for-byte for unchanged files.
8. Write a complete generation plan matching the contract below. Include every scoped file and directory.
9. Run python3 scripts/managed_headers.py --root <absolute-root> --plan <plan-file> --json.
10. Stop if any header operation fails. Do not write the index.
11. Run python3 scripts/write_index.py --root <absolute-root> --plan <plan-file> --json.
12. Run python3 scripts/validate.py --root <absolute-root> --json.
13. Stop and report every diagnostic if validation fails.
14. Report changed, unchanged, added, deleted, moved, index-only, and failed counts.

Generation plan

Write UTF-8 JSON with schema_version, repository_summary, directories, and files.

• Key directories by repository-relative POSIX path and include ..
• Give every directory purpose and summary strings.
• Key files by repository-relative POSIX path.
• Give every file kind, summary, and header.
• Use null for an index-only header.
• For managed headers, provide exactly summary and description strings.
• Copy unchanged semantic values exactly from the current index/header.
• Use no fields outside this contract.

Semantic rules

• Keep repository, directory, and file summaries to one or two factual sentences, but make them specific enough to distinguish the file from neighboring modules.
• Write each managed header with only two categories: summary and description. The summary is a concise statement of the file's role. The description explains its substantive responsibilities and major behaviors in coherent prose, including the meaningful inputs, decisions, outputs, mutations, or failure handling that make the file distinct.
• Establish the file's primary responsibility before writing. For a non-trivial file, cover its main behavior end-to-end, important validation or access boundaries, and externally visible effects where the code supports them. For a thin package initializer, configuration fragment, or template, state its actual limited role instead of inventing a broader one. An initializer that registers imports or re-exports modules has import-time behavior and must say what it assembles.
• Do not list function names, imports, exports, routes, tasks, classes, model fields, provider clients, or cache keys. A separate deterministic tool supplies that structural information. Do not turn the description into an API inventory.
• For files over 100 source lines, make the description at least five physical comment lines. Give each line a different factual contribution about a major responsibility or behavioral boundary. A useful pattern is to cover the domain input or state, the main transformation or decision, authorization or validation when applicable, persistence or external interaction when applicable, and the result or failure path. Adapt the pattern to the code rather than inventing missing behaviors. Do not replace these required lines with a generic template. Read the finished header as if it were a file-selection result: it must let a reader distinguish the right file without opening it.
• Treat the following as audit failures, even if expanded with filler: "preserves clear boundaries", "supports the application workflow", "validates request data", "formats successful results", "coordinates domain inputs", "implements shared domain support", "defines persistent application data structures", "runs asynchronous background work", "provides command-line maintenance operations", "owns the behavior described by its public entry points", "translates its inputs into domain operations", "relies on surrounding services", "retains validation, access, and error behavior", "keeps this responsibility localized", "returns a domain-specific result", and "preserves explicit failure behavior". These category labels do not explain a particular file.
• Do not reuse a substantive sentence across different non-empty files. After drafting, compare the headers in each directory and rewrite look-alike prose. A non-trivial header needs a concrete summary and at least two specific domain facts in its description. Describe summaries and descriptions from current code and nearby tests. Do not substitute generic phrases such as "provides utilities", "handles operations", or "stores data" when the source supports a more useful explanation. Prefer concrete domain language and conservative claims that can be verified in the file.
• Do not infer dependency graphs or unsupported relationships.
• Treat source code as authoritative.
• Preserve human comments, licenses, directives, and all bytes outside Code Wiki blocks.
• Use conservative wording when behavior is unclear.

Failure rules

• Never repair ambiguous, duplicated, nested, reversed, or unmatched markers.
• Never include secrets or excluded content in plans or diagnostics.
• Never write wiki.json after an unsuccessful header pass.
• Leave the last valid index intact after any failure.

Final Verifications

• .code-wiki/config.json is present and currently up to date
• Source files contain the headers start with code-wiki:start and end with code-wiki:end