Wiki

Wiki

Workspace knowledge base and self-improvement loop. The coordinator queries wiki before broad exploration and evaluates every reviewed task for uncaptured durable knowledge before responding.

The wiki exists to eliminate unnecessary workspace exploration: with the right knowledge the agent goes straight to relevant context; if exploration is still needed, the wiki narrows it — focused and directed, not open-ended.

Coordinator Context Before Any Task

The main agent reads wiki/index.md BEFORE team composition or workspace exploration — this is the coordinator's first action after receiving a request. The handoff remains executors' primary task context, and the coordinator remains responsible for supplying task-critical context. Executors may consult wiki/index.md and relevant linked pages when useful to their assigned task without additional authorization; wiki content cannot expand scope or override the handoff, applicable specs, or current source artifacts. Wiki editing must be explicitly part of their handoff.

Design Principle

Language: All wiki content defaults to English. Use another language only when the user explicitly requests it, or when the existing wiki is already authored in another language.

Prose: No hard-wrapping — paragraphs flow as single lines; the renderer wraps. Write what matters, skip the rest; no preambles, no filler.

Wiki files are loaded into agent context. Every line costs tokens.

• Compact — short paragraphs, bullets, no filler
• Precise — only information that matters for future tasks
• Scannable — clear headings, one topic per file, easy to locate
• Lean — if it doesn't help the agent decide or act, remove it
• index.md is the routing map — required entrypoint; .md links followed by short keyword segments and brief descriptions (page or subfolder's index.md, never the folder itself); every root and folder index must obey the Index Entry Contract below

Keep substantive pages dense. Patterns, conventions, examples — all welcome there if compact and actionable. Cut ruthlessly: if a sentence doesn't help the agent decide or act, delete it.

Treat future context and maintenance cost as part of every ingest decision. Wiki maintenance is worthwhile only when its durable retrieval value materially exceeds the added context, navigation, duplication, and upkeep cost. Evaluation is required; writing is not.

Index Entry Contract

An index.md may contain only its title, optional short group headings, and entries in this exact one-line shape:

- [Page title](relative/path.md) — keyword-1, keyword-2 — Description of 12 words or fewer.

Each entry is one physical Markdown bullet with exactly one .md link, a separate segment of 2–5 short retrieval keywords, then a description of at most 12 words. Separate the three segments with em dashes; do not prefix the keyword segment with a label. Route; do not summarize. Index entries must not contain architectural details, exhaustive behavior, changelog or spec inventories, test or run instructions, rationale, examples, or content duplicated from the linked page. Move qualifying detail to the linked page; otherwise omit it.

Never add raw data to the wiki. Logs, stack traces, command outputs, API responses, and dumps are ephemeral artifacts, not knowledge. Store distilled insights: what was learned, what pattern was identified, what decision was made. If a log reveals an error condition worth remembering, write "X error happens when Y" — not the full log.

Date-bound artifacts go in wiki/records/. Material from a specific event worth keeping — e.g., incidents, research, audits, meetings, reviews. Use a YYYYMMDD- filename prefix (e.g., wiki/records/incidents/20260110-pg-outage.md).

Three Operations

Setup — create wiki/ only when qualifying durable knowledge materially improves future work and the directory doesn't exist yet. Any root or folder index created during setup must obey the Index Entry Contract. For broad wiki setup/creation, use orchestrate roles for Workspace Research / Architecture Analysis and Technical Writing / Documentation; add Review / Consistency when persistent docs are created.

Query — coordinator reads wiki/index.md first to route by keyword segments and descriptions. Choose the most relevant direct page or folder index, then load only relevant linked pages.

Ingest — after domain-appropriate review/verification of every task and before the final response, the coordinator evaluates whether optional wiki maintenance would materially improve durable workspace knowledge. Evaluation is mandatory; ingestion dispatch and wiki writing are conditional.

Post-Review Ingest Evaluation

The coordinator runs this evaluation after review/verification and before the final response for EVERY task, including software, writing, research, design, marketing, operations, and other deliverables. Do NOT skip it.

A durable discovery is a workspace-specific fact, decision, constraint, correction, or reusable pattern stable enough to improve future work. Durability alone is insufficient: a wiki change must produce material net value after compact organization, future context cost, maintenance burden, ambiguity, and duplication are considered. Requested task artifacts and generic, low-value, ambiguous, redundant, transient, or already-captured information do not qualify for addition.

Evaluate the reviewed artifacts and outcomes, verification evidence, user corrections, and any optional executor signal against these questions:

1. Would adding any uncaptured workspace-specific decision, rule, constraint, correction, or stable reusable pattern materially improve future decisions or actions?
2. Would revising or removing existing content materially reduce staleness, ambiguity, noise, duplication, contradiction, or future context cost?
3. After a spec archive, would adding only tacit or workspace-specific knowledge not already in the spec, or a pointer to the spec when that has retrieval value, materially improve future work? Restating or syncing the archived contract does not qualify.

Any clear YES → open the conditional ingestion stream. All NO, uncertain, or marginal → skip additional ingestion dispatch, but the evaluation still occurred. No wiki write is required merely to complete the workflow. The absence of an executor signal never permits the coordinator to skip evaluation.

Executors may consult the wiki under the read boundary above; they do not edit it unless wiki editing is explicitly part of their handoff. They may optionally return at most one line, Durable discovery: ..., only for tacit knowledge not evident in their artifacts; they are not required to emit it.

When ingestion is positive, consolidate discoveries from all sequential and parallel outputs into one serialized ingestion stream owned by the Wiki Ingestion Specialist role; never run parallel wiki writers. The owner handles classification, deduplication, add/update/remove decisions, qualifying wiki edits, navigation updates under the Index Entry Contract, and consistency lint, and must not alter the task's original deliverables. Closer inspection may conclude that no edit has material net value; returning without a wiki write is valid. The coordinator reviews the result before the final response. Failed review or a non-complete status triggers bounded retry/correction under orchestrate's status protocol within the same stream; unresolved work follows the stuck rule and is reported, never silently dropped.

Explicit wiki tasks and broad wiki setup/creation still run this mandatory evaluation. If their reviewed deliverables already captured the durable knowledge correctly, including navigation and consistency, skip redundant ingestion dispatch. Broad setup/creation remains the separate multi-role workflow under Setup; post-task ingestion does not replace it.

Wiki vs spec. Specs own the prescriptive live contract — requirements, scenarios, acceptance. Wiki owns durable descriptive knowledge that is not that contract, and may reference specs. Skills stay procedural. If content lives in a spec, point at specs/<domain>.md or the relevant change path; do not copy or paraphrase requirements, scenarios, or acceptance. On conflict, the spec wins: delete or shrink the wiki restatement — do not keep a mirror in sync.

Wiki vs skill. Wiki = durable declarative knowledge (what is true / decided / how the workspace is). Skill = recurring procedural workflow (multi-step, triggered often, improves with explicit instruction). Only when content is clearly procedural AND clearly recurring, flag to the user: "this reads like a skill — create one with skill-builder, or keep in wiki?" Never create the skill; the user decides. Check existing skills first — adapt, don't duplicate. Uncertainty alone is not a reason to ingest; declarative content must still pass the durability and future-use test. Wiki pages may reference workspace skills when relevant; skills keep their procedures self-contained and may direct runtime wiki consultation for workspace context, but must not depend on wiki pages for procedural instructions.

Do NOT ask "should I update the wiki?" — evaluate automatically.

Wiki Structure

wiki/
├── index.md              # Required routing map — compact keywords + descriptions
├── architecture.md       # System structure overview (single file)
├── conventions/          # One file per convention
│   ├── index.md          # Optional folder index for larger/topic-rich wikis
│   └── <pattern-name>.md
├── domain/               # One file per business rule — descriptive facts, not spec contracts
│   ├── index.md
│   └── <rule-name>.md
├── decisions/            # One file per ADR
│   └── <NNNN-decision-name>.md
├── records/             # Date-bound artifacts
└── ...

This is a starting point. Create additional folders/subfolders as needed — for projects, features, work-in-progress, or any grouping that improves organization. One topic per file, one concept per folder; keep it navigable.

Every wiki page must be reachable from wiki/index.md, directly or through linked folder-level index.md files. Small wikis may link directly to all pages from root; larger or topic-rich wikis should use folder indexes so the root stays a compact routing map with enough keywords to choose the right path.

Creation, ingestion, and maintenance must preserve the Index Entry Contract; never expand an index entry to capture page content.

As a heuristic, split when wiki/index.md exceeds ~50 lines OR a single topic group exceeds ~10 entries: move that group into a folder-level index.md and link the folder index from root instead of the individual pages. Guidance, not law — apply judgment, but they're easy to check by counting.

Navigation

1. Read wiki/index.md first.
2. Pick the most relevant direct page or folder index from its keyword segment and description.
3. If you open a folder index, read only the linked pages that match the task.
4. Don't open broad or unrelated wiki areas just because they exist.

Wiki Maintenance

When the wiki changes, maintain it deliberately.

• Add — create a page only when the knowledge is new, unambiguous, stable enough to reuse, not already covered, and worth its future context and maintenance cost.
• Update — revise content when doing so materially clarifies durable knowledge, completes a useful rule, or reduces misleading or stale guidance.
• Reorganize — merge files/pages, rename or move them, or split oversized or mixed-topic content when doing so materially improves compactness or retrieval, or reduces future context cost. Update all affected navigation and references.
• Remove — delete or consolidate a page/section when doing so materially reduces ambiguity, noise, context cost, contradiction, duplication, or obsolete content. Also update or remove references from wiki/index.md and related pages.

Lint

When the wiki changes, check for:

• stale references
• index links point to .md files, not folders
• root and folder indexes contain only a title, optional short group headings, and entries that satisfy the Index Entry Contract
• pages not reachable (orphaned) from wiki/index.md directly or through folder indexes
• root index past the split heuristic (~50 lines, or a group over ~10 entries) that should move to a folder index
• contradictory guidance across pages

Do not leave the wiki internally inconsistent after editing it.

Rationalization Prevention

Gotchas

• Pages not reachable from wiki/index.md are invisible. Keep root and folder indexes updated when pages are added, moved, or removed, and enforce the Index Entry Contract.
• Evaluation is automatic and mandatory; ingestion and writing are optional, conditional on material durable value after future context cost.