Compile — Knowledge Compiler

Reads raw .agents/ artifacts and compiles them into a structured, interlinked markdown wiki. Inspired by Karpathy's LLM Knowledge Bases.

What This Skill Does

The knowledge flywheel captures signal reactively (via /retro, /post-mortem, /forge). /compile closes the loop by:

1. Mining unextracted signal from git and .agents/ (existing)
2. Growing learnings via validation, synthesis, and gap detection (existing)
3. Compiling raw artifacts into interlinked wiki articles (NEW — the core value)
4. Linting the compiled wiki for contradictions, orphans, and gaps (NEW)
5. Defragging stale and duplicate artifacts (existing)

No vector DB. At personal scale (~100-400 articles), the compiled wiki fits in context windows. The wiki IS the retrieval layer.

Output: .agents/compiled/ — encyclopedia-style markdown with [[backlinks]], index.md catalog, and log.md chronological record.

Pluggable Compute Backend

Set AGENTOPS_COMPILE_RUNTIME to choose the LLM backend:

When AGENTOPS_COMPILE_RUNTIME is unset, ao compile first tries to auto-detect a local claude binary (claude-cli runtime). If that is also absent, headless compile fails fast with an explicit error naming the env var to set. Interactive /compile invocations still run compilation prompts inline — the agent reading this SKILL.md IS the compiler.

Runtime preference (override auto-detect)

To force a non-auto-detected runtime permanently (e.g. you have claude installed but prefer Ollama for privacy), set it in ~/.agentops/config.yaml:

compile:
  preferred_runtime: ollama

Precedence (high → low): --runtime flag, AGENTOPS_COMPILE_RUNTIME env, compile.preferred_runtime config, claude-binary auto-detect, empty (error).

Large-corpus batching

ao compile passes --batch-size to the headless compiler (default 25 changed files per LLM prompt). A fresh run against a 2000+ file corpus will split into batches automatically instead of sending one giant prompt.

Flags:

• --batch-size N — files per batch (default 25)
• --max-batches N — cap batches per invocation; remaining files are picked up on the next run (default 0 = unlimited)

Execution Steps

Phase-by-phase detail lives in references/phases.md. Summary of modes:

• /compile — Full cycle: Mine → Grow → Compile → Lint → Defrag
• /compile --compile-only — Skip mine/grow, just compile + lint
• /compile --lint-only — Only lint the existing compiled wiki
• /compile --defrag-only — Only run defrag/cleanup
• /compile --mine-only — Only run mine + grow (legacy behavior)

The steps are:

1. Mine — extract signal from git + .agents/research/ + complexity hotspots
2. Grow — LLM-driven validation, synthesis, gap detection; adjust learning confidence
3. Compile — inventory → topic extraction → wiki articles with [[backlinks]]
4. Lint — contradictions, orphans, missing cross-refs, stale claims
5. Defrag — prune stale, dedup near-duplicates, sweep oscillating goals, normalization scan
6. Report — write .agents/compile/YYYY-MM-DD-report.md

See references/phases.md for the full per-phase procedure, confidence-scoring table, auto-promotion rules, template shapes for article / index / log / lint-report / compile-report, and the normalization defect scan.

Scheduling / Auto-Trigger

Lightweight defrag (prune + dedup, no mining or compilation) runs automatically at session end via the compile-session-defrag.sh hook. This keeps the knowledge store clean without requiring manual /compile invocations. The hook:

• Fires on every SessionEnd event after session-end-maintenance.sh
• Skips silently if the ao CLI is not available
• Runs only ao defrag --prune --dedup (no compilation or mining)
• Has a 20-second timeout to avoid blocking session teardown

For full compilation, invoke /compile manually or schedule the headless compiler script with your host OS:

# Example: external cron entry for nightly compilation on bushido
0 3 * * * cd /path/to/repo && AGENTOPS_COMPILE_RUNTIME=ollama bash skills/compile/scripts/compile.sh --force

AgentOps exposes this flow through ao compile. If you want unattended compilation, use your host scheduler (launchd, cron, systemd, CI, etc.) to invoke ao compile --force --runtime ollama or call the lower-level bash skills/compile/scripts/compile.sh directly. If you want the broader private overnight loop, use ao overnight start instead of inventing a parallel Dream wrapper inside /compile.

Interactive Modes

These modes describe the interactive /compile skill behavior:

Headless Script Flags

For unattended runs, bash skills/compile/scripts/compile.sh supports:

Examples

User says: /compile — Full Mine → Grow → Compile → Lint → Defrag cycle.

User says: /compile --compile-only — Just compile raw artifacts into wiki.

User says: /compile --lint-only — Scan existing wiki for health issues.

User says: /compile --since 7d — Mines with a wider window (7 days).

Scheduled externally: Nightly compilation on bushido GPU via Ollama.

Pre-evolve warmup: Run /compile before /evolve for a fresh, validated knowledge base.

Troubleshooting

Reference Documents

• references/compile.feature — Executable spec: Mine→Grow→Lint→Defrag rebuild, lint-not-autofix, incremental batching, evolve warmup (soc-qk4b)

• references/phases.md — full per-phase procedure (mine → grow → compile → lint → defrag → report)

• references/confidence-scoring.md

• references/knowledge-synthesis-patterns.md

• references/flywheel-diagnostics.md