Subagents and Instructions
OpenWiki uses an eve-backed indexing flow to turn a public GitHub repository into a navigable, source-grounded wiki. The subagent layer is where that flow is divided into two documentation tasks: planning an outline and drafting pages from that accepted outline. The instructions around those subagents are as important as the TypeScript entrypoints, because they define output shape, evidence rules, source citation expectations, page quality, and the boundary between model-owned writing work and deterministic product orchestration.
Sources: agent/instructions.md, agent/instructions/indexing.md, agent/subagents/outline_generator/agent.ts, agent/subagents/outline_generator/instructions.md, agent/subagents/page_generator/agent.ts, agent/subagents/page_generator/instructions.md
Purpose and Scope
This page explains the source-backed contract for OpenWiki's outline-generation and page-generation subagents. In this context, a subagent is a focused eve agent definition with a description and model configuration, while an instruction file is the policy document that tells the model how to transform repository evidence into JSON. The page is intended for developers changing indexing behavior, adjusting wiki quality rules, or debugging why a generated wiki has a particular outline or page shape.
The top-level assistant instructions establish the baseline behavior for repository-aware answers: OpenWiki treats the selected GitHub repository as the source of truth, inspects prepared repository workspaces before repository-specific answers, cites repository-relative file paths, and avoids unsupported claims. That baseline also states an important product boundary: OpenWiki currently supports public GitHub repositories only, and should not imply private-repository, user-auth, or editable-wiki flows unless those are explicitly future work. The indexing instructions then specialize that general behavior for the wiki-generation pipeline.
Sources: agent/instructions.md, agent/instructions/indexing.md
Relevant Source Files
agent/instructions.md- Defines the general OpenWiki assistant persona, repository source-of-truth rules, citation expectations, and public-repository scope.agent/instructions/indexing.md- Defines the indexing parent run, supported phases, JSON return shapes, evidence usage rules, tool limits, and outline/page quality requirements.agent/subagents/outline_generator/agent.ts- Registers the outline generator as an eve agent and assigns the OpenWiki indexing model.agent/subagents/outline_generator/instructions.md- Specifies how outline JSON should be planned, including navigation shape, docs-first information architecture, page grouping, and exclusions.agent/subagents/page_generator/agent.ts- Registers the page generator as an eve agent and assigns the OpenWiki indexing model.agent/subagents/page_generator/instructions.md- Specifies page-generation output shape, markdown-line format, citations, sectioning, prose quality, and page coverage notes.
Subagent Entry Points
Both subagents are intentionally small TypeScript modules. The outline generator calls defineAgent with a description that says it creates a multi-page, source-grounded OpenWiki outline from repository metadata, file inventory, and selected snippets. The page generator follows the same pattern, but its description narrows the job to drafting all OpenWiki pages from an accepted outline, repository summary, and relevant source snippets. Both modules use getOpenWikiIndexModel, which keeps model selection centralized rather than hard-coding it in each subagent.
Sources: agent/subagents/outline_generator/agent.ts, agent/subagents/page_generator/agent.ts
| Component | Public contract visible in source | Primary instruction file |
|---|---|---|
| Outline generator | defineAgent({ description, model: getOpenWikiIndexModel() }) for repository outline planning | agent/subagents/outline_generator/instructions.md |
| Page generator | defineAgent({ description, model: getOpenWikiIndexModel() }) for page drafting | agent/subagents/page_generator/instructions.md |
| Indexing parent run | Phase-aware JSON producer for outline-only, page-generation, or full indexing output | agent/instructions/indexing.md |
The thin TypeScript wrappers are a deliberate separation of concerns. The code exposes each subagent to eve and binds it to the configured indexing model, while the markdown instruction files carry the evolving documentation contract. That means most behavior changes, such as increasing page depth, changing navigation guidance, or tightening citation requirements, can be reviewed as instruction changes instead of being hidden inside orchestration code. Developers should still treat those instruction edits as product changes, because they directly affect generated public wiki content.
Instruction Hierarchy
The instruction hierarchy starts with agent/instructions.md, which describes OpenWiki as a source-grounded assistant for exploring public GitHub repositories and drafting wiki content. It sets the expectation that repository setup and wiki publishing are deterministic product operations, not model-selected tools. That distinction matters because the model should not invent operational steps or decide how publishing happens; it should answer or draft from evidence while the application handles repository hydration, orchestration, storage, and publication outside the prompt contract.
Sources: agent/instructions.md
The indexing parent instructions refine that contract for messages that say Task: index repository for OpenWiki. They define phases and return shapes. In outline-only, the model returns only an outline object with title, summary, concepts, navigation, and pages. In page-generation, it returns only { "pages": [...] } for requested outline pages, without repeating the outline. If no phase is specified, the instruction describes a full final JSON object. This phase split lets OpenWiki plan once, then parallelize or separately request page drafts from the accepted plan.
Sources: agent/instructions/indexing.md
The same indexing instruction file also constrains evidence and tooling. Outline-only work must use only metadata, repository map, file inventory samples, and context snippets from the invocation. Page-generation work must use the supplied outline, targeted source snippets, inventory, and map as primary evidence, and should not call tools during normal drafting. A single read-only bash command is allowed only as a last resort when required source paths are missing or contradictory. That rule keeps wiki generation reproducible and prevents broad scans, package installs, tests, dev servers, or remote fetches from entering the writing loop.
Sources: agent/instructions/indexing.md
Outline Generation Contract
The outline generator is instructed to create a human documentation plan, not a file listing. It should prefer first-party docs structure when reader-facing documentation exists, and otherwise infer conceptual sections such as architecture, package ecosystem, build system, runtime behavior, routing, caching, testing, examples, and tooling from repository evidence. This is why OpenWiki can produce docs-style navigation for large projects instead of mirroring directory names. The model is expected to group systems around reader tasks and public concepts, not around every folder or fixture.
Sources: agent/subagents/outline_generator/instructions.md
The outline instructions are especially explicit for docs-rich repositories. If an invocation includes an official docs index, that index is treated as the strongest information-architecture signal. The model should preserve major sections, split broad public-surface families into focused leaves, and keep each page grounded in repository inventory. The same file warns against turning internal planning, status, feedback, quality-run, or research documents into public wiki pages. That exclusion protects generated wikis from exposing project-management artifacts as if they were stable product documentation.
Sources: agent/subagents/outline_generator/instructions.md
Navigation shape is also part of the contract. The root page should be overview, focused subsystem pages should sit beneath meaningful section groups, and section-only parent nodes should use slug: null while leaf pages use string slugs. The instructions discourage folders that contain only one page and discourage one page per example directory, test file, fixture, or config file unless that unit is a real product boundary. The result should feel like a coherent documentation tree rather than a mechanically expanded repository index.
Sources: agent/subagents/outline_generator/instructions.md
Page Generation Contract
The page generator takes the accepted outline and writes one page per provided outline page. Its instruction file requires JSON-only output, markdownLines instead of a raw markdown string, a single # Title opening line, a relevant source files section, source-grounded prose, related pages, and coverage notes. It encourages purpose-first documentation with clear sections, tables when useful, and citations to relevant source files. It also tells the model not to write line-by-line code commentary or reduce a page to a raw file list.
Sources: agent/subagents/page_generator/instructions.md
The page quality rules define the difference between a generated note and a usable OpenWiki page. Each page should explain a system, workflow, or API surface; pages should be mode-aware, so API pages emphasize public interfaces, implementation pages emphasize runtime behavior, testing pages emphasize confidence signals, and example pages emphasize usage patterns. The instruction recommends sections such as Purpose and Scope, System-to-Code Mapping, Core Concepts, Execution Flow, API Components, Implementation Details, Testing Signals, CI/CD Signals, and Summary when source evidence supports them.
Sources: agent/subagents/page_generator/instructions.md
The page generator also carries the citation and coverage contract used by downstream rendering. Citation paths must be repository-relative and drawn from supplied evidence, with null line numbers when exact ranges are unknown. Coverage notes are the place to record limitations, not the main prose. That distinction keeps public pages useful while preserving auditability. If evidence is thin, the writer should constrain claims and say what the repository context supports rather than speculating about hidden behavior.
Sources: agent/subagents/page_generator/instructions.md
Execution Flow
In a normal indexing run, the parent indexing instructions determine which phase the model is performing. During outline planning, the outline subagent uses repository metadata, a file inventory, repository map summaries, official docs signals when supplied, and selected snippets to propose a structured documentation tree. The output is JSON, not markdown. Each page entry should be a reader-facing unit with a purpose, source paths, and a title that can later drive targeted page-generation requests.
Sources: agent/instructions/indexing.md, agent/subagents/outline_generator/instructions.md
Once an outline is accepted, page-generation requests provide a subset of outline pages plus targeted evidence for those pages. The page generator then returns exactly one page object per requested outline page. That object contains the slug, title, markdown lines, citations, related pages, and coverage notes. This staged design supports parallel page workers while preserving the information architecture selected by the outline phase. It also means a page worker should not broaden its scope beyond the requested page set or invent new outline leaves.
Sources: agent/instructions/indexing.md, agent/subagents/page_generator/instructions.md
Implementation Notes for Contributors
When changing OpenWiki's generated documentation behavior, start by deciding whether the change belongs in orchestration code, the shared indexing model configuration, the outline instructions, or the page instructions. A change to the TypeScript agent files is appropriate when the eve registration or model-binding behavior changes. A change to agent/subagents/outline_generator/instructions.md is appropriate when page selection, navigation shape, official-docs handling, or repository-size heuristics need tuning. A change to agent/subagents/page_generator/instructions.md is appropriate when page prose, sections, citations, markdown format, or coverage expectations need adjustment.
Developers should also preserve the boundary between model work and deterministic product work. The instructions repeatedly say that hydration, orchestration, parallel workers, and publishing are handled outside the model. The model owns planning and drafting; the application owns the prepared repository workspace, job lifecycle, storage, and publication. Keeping that boundary clear makes generated output easier to validate, retry, and refresh, because failures can be traced either to product orchestration or to the instruction-driven JSON contract.
For related context, read the wiki generation pipeline next to see how outline and page outputs move through indexing, publishing, and refresh behavior. Read the agent architecture page if you need the broader eve runtime view, and read source grounding and citations if you are tightening evidence rules for generated pages. Together, those pages explain how these subagents fit into OpenWiki's larger promise: living repository wikis that are planned like documentation, written from source evidence, and safe to refresh as public repositories change.