Repo Wiki Generator

Read shared/orchestrator-contract.md. Own the wiki run directory, page generation, knowledge card assembly, wiki_plan configuration, and incremental update logic.

Inputs

Require repo_root and project_id. Accept:

• output_root: default repowiki or custom path.
• language: en (default) or zh. Creates language-specific subdirectory.
• mode: generate (full), update (incremental), or plan-only (emit wiki_plan.yaml without generating content).
• wiki_plan: path to existing wiki_plan.yaml, or inline configuration.
• scope.include / scope.exclude: file filters in .gitignore syntax.
• template: architecture (default) or product_requirement.
• coverage_profile: comprehensive (default) or focused. Comprehensive evaluates every baseline topic facet; focused evaluates only explicitly included facets and planned documents.
• topic_overrides.include / topic_overrides.exclude: baseline facet IDs to force into or remove from planning. Exclusions always remain visible in the coverage ledger.
• notes: list of guidance prompts to steer generation focus.
• --resume: continue interrupted generation.

Stage Pipeline

Order	Stage	Skill/Action	Depends On	Outputs
1	recon	hi-repo-recon (deep)	inputs	module inventory, entry points
2	audit	hi-tech-build-audit (deep)	inputs	tech stack, build, CI/CD
3	facet scan	internal	recon + audit	capability signals, baseline topic coverage
4	domain evidence	applicable leaf skills	facet scan	API, data, use-case, behavior evidence
5	summary	hi-module-summary-report	recon + audit	per-module breakdown, risks
6	plan	internal	all evidence	coverage ledger, wiki tree, page list, module tree
7	pages	internal (parallel per section)	plan + evidence	content/*.md pages
8	cards	internal (parallel per module)	plan + evidence	knowledge/**/*.md cards
9	index	internal	pages + cards	navigation, metadata, manifests

Read shared/retrieval-protocol.md for evidence gathering.

Workflow

Phase 1: Evidence Gathering

1. Validate repo_root, create output_root/<lang>/ structure.
2. Load wiki_plan.yaml if present; otherwise derive defaults from repo analysis.
3. Run hi-repo-recon with deep depth and hi-tech-build-audit with deep depth. May run concurrently with isolated outputs.
4. Build a repository-wide capability signal inventory. Inspect executable and library entry points, manifests, configuration, environment files, command registrations and help text, build targets, languages, framework bootstraps, schema/migration/model declarations, graph drivers and writers, server/tool/resource registrations, query/search indexes, change detection and synchronization, routes/events, tests, CI/CD, deployment assets, contributor guidance, diagnostics, and known error paths.
5. Evaluate every baseline facet in topic-coverage-contract.md. Do not decide applicability from filenames alone; corroborate signals through registrations, imports, callers, configuration loading, executable declarations, tests, or runtime wiring.
   • In comprehensive mode, retain tests, CI, deployment, example, and contributor files in evidence scope unless the user explicitly excludes them. Record any user exclusion that prevents a facet decision as excluded_by_plan or unknown, as appropriate.
6. Run applicable evidence leaves into isolated stage directories:
   • Run hi-api-contract-discovery for verified HTTP, RPC-over-HTTP, webhook, or asynchronous message surfaces.
   • Run hi-data-model-discovery for verified persistent schemas, migrations, ORM/domain mappings, caches, or graph storage models.
   • Run hi-usecase-discovery for the key executable modules that implement user or operator outcomes.
   • Run hi-behavior-modeling for multi-step, asynchronous, stateful, retry, sync, or ingestion flows with stable anchors.
   • Use hi-command-spec-discovery only for binary/wire commands such as APDU, TLV, or opcodes; it is not a CLI analyzer. Derive CLI reference evidence directly from parser registrations, dispatch tables, help output definitions, scripts, Makefiles, task runners, and tests.
7. Collect validated leaf artifacts and direct evidence. Preserve unsupported facets as unknown or not_applicable; never create a feature merely to fill the navigation tree.
8. Run hi-module-summary-report with validated recon + audit artifacts and join its module/risk synthesis with the domain evidence.

Phase 2: Wiki Planning

9. Create topic-coverage.json using topic-coverage-contract.md and validate it with scripts/validate_topic_coverage.py. Give every baseline facet exactly one status: planned, documented, merged, not_applicable, unknown, blocked, or excluded_by_plan, with evidence and a reason. Use planned only before page generation or in plan-only mode.
10. Build the page tree from applicable facets, module inventory, and repository terminology. Use a two- or three-level hierarchy comparable to a technical handbook; group related child topics without flattening everything into module pages.
11. If wiki_plan.yaml has a documents allowlist, generate strictly per that list and mark otherwise applicable facets excluded_by_plan. Never silently claim comprehensive coverage for a strict allowlist.
12. For each planned page, assign: stable facet IDs, title, goal, parent page, navigation order, evidence sources, required content blocks, and diagram requirements. A page may satisfy multiple closely related facets, but the mapping must be explicit.
13. Build the knowledge card module tree from the module inventory. Each module gets: scope, file list, dependencies, relationships, and sub-modules.
14. If mode=plan-only, write wiki_plan.yaml and topic-coverage.json to output_root/, keep applicable page mappings at planned, validate both, and stop with succeeded or partial according to unresolved coverage.

Phase 3: Page Generation

15. For each section in the page tree, generate wiki pages following page-contract.md. Each page includes:
    • <cite> block listing source files referenced.
    • Table of Contents.
    • Introduction and scope.
    • Core content (architecture, components, data flow, patterns, extension points).
    • Mermaid diagrams where evidence supports them (architecture: graph TD, dependencies: graph LR).
    • Dependency analysis and integration points.
    • Troubleshooting guide where applicable.
    • Evidence status per claim.
16. Apply the topic-specific content requirements from topic-coverage-contract.md. Prefer verified tables for commands, configuration keys, APIs, schemas, tools, tests, and deployment targets; include defaults and constraints only when evidenced.
17. Parallelize page generation across independent sections. Cap workers per orchestrator contract.
18. Write pages to content/<Section Name>/<Page Title>.md.

Phase 4: Knowledge Card Generation

19. For each module in the module tree, generate knowledge cards following knowledge-card-contract.md:
    • _module.yaml: scope, file list, dependencies, parent/child relationships.
    • overview.md: purpose, responsibilities, boundaries.
    • architecture_design.md: internal structure, patterns, key abstractions.
    • coding_conventions.md: naming, style, error handling, testing patterns observed.
    • tech_stack.md: languages, frameworks, libraries, tools used by this module.
    • unique_setup_and_commands.md: module-specific build/run/test commands when applicable.
20. Nest sub-module directories under their parent module.
21. Write cards to knowledge/<lang>/<Module Name>/.

Phase 5: Index Assembly and Validation

22. Build _index.yaml master index from all generated knowledge cards: module names, directory paths, file scopes, parent-child relationships, dependency graph.
23. Build navigation from the planned parent/order fields; verify every non-root page has one reachable parent and no cycles exist.
24. Build repowiki-metadata.json with generation timestamp, language, template, page count, card count, source revision, evidence coverage, per-facet status counts, and coverage profile.
25. Write Getting Started.md and Development & Contributing.md as root-level content pages.
26. Convert satisfied planned facets to documented or merged, then validate: no planned facet remains in generate or update mode; all planned pages and cards exist; every documented or merged facet maps to an existing page; every other facet has a reason; _index.yaml and topic-coverage.json parse; no orphaned references; Mermaid blocks parse; <cite> blocks reference real files; sensitive values are redacted.
27. Persist artifact-manifest.json and final status.

Incremental Update (mode=update)

1. Load existing repowiki-metadata.json and _index.yaml.
2. Detect changed files since source_revision using git diff --name-only <source_revision>..HEAD.
3. Identify affected pages (via <cite> source lists) and affected knowledge cards (via _module.yaml file scopes).
4. Re-run the capability signal scan for changed manifests, registrations, schemas, routes, command definitions, configuration, tests, deployment files, or documentation. Detect newly applicable or removed facets even when no existing page cites the changed file.
5. Re-run evidence gathering only for affected modules and facets.
6. Regenerate affected pages and cards, add pages for newly applicable facets, and retire removed topics only after recording the transition in topic-coverage.json. Preserve manually-edited content flagged by the user.
7. Rebuild navigation, _index.yaml, topic-coverage.json, and repowiki-metadata.json.
8. Keep unchanged pages/cards with their original hashes.

Configuration: wiki_plan.yaml

Accept configuration per wiki-plan-template.yaml:

version: 1
repowiki:
  template: architecture | product_requirement
  coverage:
    profile: comprehensive | focused
    include: ["<facet-id>"]
    exclude: ["<facet-id>"]
    max_depth: 3
  notes:
    - text: "<guidance prompt>"
      author: "<name>"
  documents:           # optional page allowlist (strict mode)
    - title: "<page title>"
      goal: "<generation goal>"
      parent: "<parent page title>"
      hints: "<additional hints>"
knowledgecard:
  notes:
    - text: "<guidance for card generation>"
scope:
  include: ["<glob>"]
  exclude: ["<glob>"]

When documents is non-empty, page generation is strict: only listed pages are produced. When empty, pages are derived automatically from evidence. coverage.profile=comprehensive evaluates the complete baseline taxonomy even if some facets are not applicable; focused limits evaluation to included facets and planned documents.

Failure Behavior

• Missing repo_root or unreadable repository: blocked.
• Evidence gathering partial: continue with available evidence, mark affected pages/cards as partial.
• Page generation failure: skip affected page, continue with remaining pages.
• Knowledge card failure: skip affected card, record in manifest.
• Index assembly failure: failed — pages/cards may exist but navigation is broken.

Outputs

<output_root>/
├── wiki_plan.yaml                          # generated or copied config
├── topic-coverage.json                     # baseline facet status and page mapping
├── <lang>/
│   ├── content/
│   │   ├── Getting Started.md
│   │   ├── Development & Contributing.md
│   │   ├── <Section>/
│   │   │   ├── <Section>.md                # section overview
│   │   │   └── <Page Title>.md             # individual pages
│   │   └── ...
│   └── meta/
│       └── repowiki-metadata.json
├── knowledge/
│   └── <lang>/
│       ├── _index.yaml
│       └── <Module Name>/
│           ├── _module.yaml
│           ├── overview.md
│           ├── architecture_design.md
│           ├── coding_conventions.md
│           ├── tech_stack.md
│           └── unique_setup_and_commands.md
└── artifact-manifest.json

Completion

Complete when: all planned pages exist and parse, all planned knowledge cards exist, every evaluated topic facet has an evidence-backed status and page mapping or explicit disposition, navigation is connected and acyclic, _index.yaml validates, <cite> blocks reference real source files, Mermaid diagrams parse, sensitive values are redacted, metadata reflects actual generation state, and artifact-manifest.json validates. Any unknown, blocked, missing/failed page, missing/failed card, or planned facet outside plan-only mode forces partial with an explicit list; planned in plan-only, not_applicable, and user-requested excluded_by_plan do not by themselves force partial.