metawikiroutingcapsulesagent-docsdevelopment-frameworkUpdated 2026-07-01

Wiki Capsules And Agent Doc Packs

Operating model for turning kevin-wiki into both a readable second brain and a reusable agent framework: coherent wiki articles own meaning, generated registries own inventory, and packs compile the right context for each workflow.

Full design spec: docs/superpowers/specs/2026-06-26-wiki-capsules-agent-doc-framework.md.

Core Idea

The wiki should keep coherent pages, not a page per stray thought. The durable unit is a mental object: a concept, tool ecosystem, person with real signal, workflow, decision, or skill family. Small mirror pages and one-line registries belong in generated data or ledgers.

The governing rewrite standard is Wiki Brain Operating Model. This page focuses on capsules and generated packs; the operating model defines how the wiki should be flattened, merged, categorized, and kept readable.

The missing layer is now explicit: a brain capsule is the public interface to one coherent slice of Kevin's compiled wiki. A capsule says which source pages, skills, tools, concepts, artifacts, generated registries, proof rules, and maintenance loops belong together.

The agent-facing product starts with the capsule. Generated packs are downstream execution bundles attached to one or more capsules. Agents should be able to say "I am using the Frontend And Design System capsule" before they say "I loaded frontend.md." That makes the brain boundary visible instead of burying it inside a pack table.

Canonical source/projection contract: Generated Surface Contract. AGENT DOCS directory map: Agent Docs System Map. Canonical pack index: wiki/agent-docs/README.md. Canonical capsule index: wiki/meta/brain-capsules.md. Portable capsule manifest: agent-docs/capsules.json. Portable generated output: agent-docs/packs/. Generator/check: npm run agent-packs:refresh and npm run agent-packs:check. agent-packs:refresh runs the page-by-page corpus and consolidation audits before regenerating packs, capsules, and readable indexes.

Each generated pack now carries more than a static checklist. The generator scans current wiki markdown/frontmatter and writes a ranked Wiki Knowledge Surface, Tools And Skill Routes, SOTA / Frontier Watchlist, bundle-neighbor hints, and self-update triggers into every pack. The intended loop is: ingest/update the atomic wiki page first, then regenerate packs so new frontier knowledge flows into design.md, frontend.md, backend.md, code.md, ai-agents.md, and the other portable docs automatically.

Capsule maintenance is fed by bookmark artifact review. npm run audit:x-bookmark-artifacts builds wiki/meta/x-bookmark-artifact-audit.json, a per-bookmark queue that flags unresolved source review, visual review, local media repair, thought types, and capsule candidates. A bookmark is not fully absorbed until durable thoughts from its links, threads, replies, images, and demos have been promoted into source pages or explicitly deferred in that ledger.

For agent-facing capsules, evaluator state is part of the public brain interface. If a capsule teaches agents how to act, it must also expose how that action is checked. Agent Self-Improvement Eval Library owns the receipt-based proof surface, Red Queen Gödel Machine owns evaluator hardening, and Loopy owns the repeatable loop shape before a procedure becomes a skill or automation.

Brain Capsule Contract

Each capsule exposes:

Field Meaning
id Stable capsule identifier used by generated packs and audits.
publicPurpose The plain-language slice of Kevin's brain this capsule exposes.
loadWhen The task boundary that activates the capsule.
sourcePages Read-first wiki pages that own durable truth.
skillRoutes Executable skills agents should consider before inventing a process.
toolRoutes CLIs, MCPs, scripts, products, or services attached to the capsule.
maintenance Checks and write-back rules that keep the capsule current.
packs Generated execution bundles attached to the capsule.

Generated packs must include a ## Brain Capsule Interface section. The manifest must include capsule routes per pack so enrolled repos and other agents can load the same brain slice without reverse-engineering wiki structure.

The stronger loop runs Agent Pack Corpus Audit first. That audit reads every non-generated wiki page, assigns a candidate capsule, scores pack candidates, flags explicit-pack-block opportunities, and writes wiki/meta/agent-pack-corpus-audit.json. Generated packs consume the compact per-pack review queues from that JSON under ## Corpus Review Queue.

The companion loop runs Page Consolidation Audit. That audit reads the same wiki corpus and finds likely duplicate pages, foldable stubs, over-split ideas, and valid skill/tool/concept layer mirrors that need clearer routing instead of blind deletion. Generated packs consume those compact per-pack queues under ## Consolidation Review Queue.

The ecosystem coverage loop runs Ecosystem Capability Coverage before consolidation. That audit checks whether service ecosystems are merely discovered, actually routed, represented by readable wiki pages, included in packs, and backed by a verification path. This prevents Google Workspace, Firebase, and Azure from becoming the only well-promoted ecosystems just because they had earlier skill families.

Page Layers

Layer Owns Example
Canonical synthesis page Readable generalized article with thesis, when to use it, decision matrix, core model, tool/skill routing, failure modes, evidence, and related pages Browser Automation and QA, Agent Search and Retrieval, Local Web Verification
Tool page Product facts, tradeoffs, interfaces, auth/setup surfaces, alternatives, and freshness notes browser-use, agent-browser, playwright, qmd, sentry, clickhouse, tanstack
Skill registry row Executable procedure inventory: slug, namespace, source path, family route, and short description Skill Registry generated from skills/**/SKILL.md
Skill family page Readable synthesis for a skill cluster: when to route there, owners, failure modes, cleanup rules, and notable procedures Agent Engineering Skills, Frontend and Design Skills, Browser Testing Skills
Source/ingest page Evidence logs, raw captures, timeline material, and registry snapshots Raw registry harvests, tweets, docs captures
Generated pack Downstream portable agent context bundle agent-docs/packs/*.md

Packs should prefer canonical synthesis pages first, then relevant tool pages, skill-family pages, generated registry rows, live review queues, and source refresh notes. Packs should not pull every small related page with equal weight.

Current canonical cluster pages: Identity, Session, and Routing, Browser Automation and QA, Local Web Verification, Agent Search and Retrieval, Skills, Tools, and Capability Discovery, Google Workspace Skills, Firebase Skills, Azure Skills, Frontend, Design, Motion, and Accessibility, Agent Harness, Runtime, Memory, and Evals, Agent Self-Improvement Eval Library, Loopy, and the generated Skill Registry.

Pack Family Examples
Startup / routing identity.md, session.md, routing.md, workflow-index.md
Engineering code.md, architecture.md, typescript.md, testing.md, debugging.md, doctors.md, review-qa.md, security.md, git-process.md, process-hygiene.md
Frontend / design frontend.md, react.md, nextjs.md, design.md, design-systems.md, motion.md, accessibility.md, performance.md, browser-qa.md, web3d.md, mobile.md
Backend / infra backend.md, databases.md, auth.md, infra.md, cloud.md, observability.md, payments.md, data.md, ops.md, service-cli.md, google-workspace.md
AI / agents ai-agents.md, agent-harnesses.md, skills.md, mcp-tools.md, memory.md, evals.md, sandboxes.md, model-routing.md, automations.md
Wiki / research / docs wiki-ops.md, capture-ingest.md, research.md, learning.md, docs-writing.md, diagrams.md
Product / career / communication product.md, content.md, writing.md, seo.md, career.md, portfolio.md, people.md, principles.md, narrative.md
Specialty media-generation.md, documents-presentations.md, game-dev.md, hardware-graphics.md, events-travel.md

Why This Beats A Giant Manual

A single giant hand-written design.md would be convenient for one agent session and stale a week later. Capsules keep the source modular. Generated packs give agents one file to read.

This matches three existing principles:

Page Identity Rule

Stable page identity must be separate from file path before any bulk move.

Field Purpose
id Immutable concept slug used by wikilinks and backlinks.
path_slug Physical route/URL derived from file path.
capsule Domain cluster.
redirect_from Old flat slugs or old paths that should resolve after moves.

Agents should keep writing [[next-js]], [[gws-drive]], and [[opencode]]. The wiki resolver should map those ids to current nested file paths.

First Capsules

Capsule Why
agent-harnesses OpenCode, OpenClaw, Hermes, Claude Code, Codex, Cursor, AI SDK Harness, and portability rules belong together.
google-workspace gws-* skills and Google Workspace CLI are one operational service family.
gstack GStack review/QA/design review should be grouped while preserving Kevin's no-sus/autoreview priority.
firebase Firebase service skills are one backend/mobile platform family.
taste Taste skills, design style pages, imagegen, Stitch, and anti-slop rules are one design decision layer.
nextjs Next.js tool facts, best-practices skill, Cache Components, upgrade, and instant navigation workflow belong together.

Implementation Order

  1. Add identity registry support: stable id, recursive paths, redirects, and duplicate checks.
  2. Add capsule manifests and routers without moving files.
  3. Run npm run ecosystem-coverage:audit and promote tier-1 service ecosystems before merging pages.
  4. Replace one-page-per-skill validation with generated skill registry validation.
  5. Compact low-signal skill/person/entity mirrors into family pages, ledgers, or real concept/tool pages.
  6. Generate the default coding bundle and web-app bundle from canonical pages and registries.
  7. Expand lane by lane until every pack in wiki/agent-docs/README.md exists.
  8. Extend agent-docs so enrolled repos can import pack presets.

Guardrails

  • Do not move executable skill directories until all harnesses support nested skill discovery.
  • Do not break [[slug]] wikilinks.
  • Do not bulk move pages until redirects, backlinks, qmd, UI, and skills:check are path-aware.
  • Do not recreate hand-written root wiki/skills/<slug>.md mirrors; use Skill Registry, family pages, and generated namespace source pages under wiki/skills/{engineering,productivity,personal,misc,in-progress,deprecated}/.
  • Do not delete ideas during compaction; move them into a section, table row, alias, timeline, ledger, or redirect.
  • Known retired slugs resolve through npm run wiki:resolve -- <slug-or-title>; qmd search remains the discovery path, not the exact identity resolver.
  • Do not let generated packs summarize arbitrary markdown. Use explicit agent-pack:<pack> source blocks or capsule summaries.
  • Do not replace routers with packs. Routers choose; packs instruct.
  • Do not hand-edit wiki/agent-docs/README.md; it is the generated readable pack index.
  • Do not edit generated pack files by hand; edit scripts/generate-agent-packs.ts and run npm run agent-packs:refresh.
  • Do not edit wiki/meta/brain-capsules.md or agent-docs/capsules.json by hand; edit scripts/generate-agent-packs.ts and rerun the generator.
  • Do not treat bookmark coverage as artifact review. Run npm run audit:x-bookmark-artifacts and drain the relevant per-bookmark queue.
  • Do not treat ## Corpus Review Queue items as already-promoted truth. They are inspection queues; promote by updating the source page, pack definition, or explicit source block.
  • Do not treat ## Consolidation Review Queue items as delete instructions. Read both pages, preserve timelines and citations, and keep valid layer mirrors separate with better routing.

Timeline

Related Pages

Wiki Brain Operating ModelGenerated Surface ContractAgent Docs System MapBrain CapsulesAgent-Docs MeshCapability Routing MapCross-Agent Harness PortabilityActive Stack (What to Actually Use)Skill ResolverMatt Pocock's Skills (Skills for Real Engineers)Agent Operations HubX Bookmark Artifact AuditAgent Self-Improvement Eval LibraryLoopyRed Queen Gödel Machine

20 pages link here

Agent Docs FilingFiling Decision TreeAgent Docs System MapAgent DocsAgent Harness CapsulesConceptsAgent Harness, Runtime, Memory, and EvalsConceptsAgent Pack Corpus AuditMetaAgent Skill BundlesConceptsBrain CapsulesMetaBrowser Automation and QAConceptsCross-Agent Harness PortabilityMetaEcosystem Capability CoverageMetaGenerated Surface ContractMetaIdentity, Session, and RoutingConceptsLLM Wiki Agent HarnessArchitectureOpenCodeToolsPage Consolidation AuditMetaRetired Skill Article LedgerMetaSkills, Tools, and Capability DiscoveryConceptsWiki Brain Operating ModelMetaWiki Redirect IndexMetaX Bookmark Artifact AuditMeta