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:

Mining unextracted signal from git and .agents/ (existing)
Growing learnings via validation, synthesis, and gap detection (existing)
Compiling raw artifacts into interlinked wiki articles (NEW — the core value)
Linting the compiled wiki for contradictions, orphans, and gaps (NEW)
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:

Value	Backend	Notes
`ollama`	Ollama API	Default model: `gemma3:27b`. Set `OLLAMA_HOST` for remote (e.g., `bushido tunnel ollama`).
`claude`	Claude API	Uses `ANTHROPIC_API_KEY`. Model: `claude-sonnet-4-20250514`.
`openai`	OpenAI-compatible	Uses `OPENAI_API_KEY` + `OPENAI_BASE_URL`.
(unset)	Claude Code session	Compilation happens inline via the current session's LLM.

When AGENTOPS_COMPILE_RUNTIME is unset, the skill runs compilation prompts inline — the agent reading this SKILL.md IS the compiler. This is the default for interactive /compile invocations.

Execution Steps

Step 0: Setup

mkdir -p .agents/compiled

Determine mode from arguments:

/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)

Step 1 — Mine: Extract Signal

Run mechanical extraction. Mine scans git history, .agents/research/, and code complexity hotspots for patterns never captured as learnings.

ao mine --since 26h                    # default: all sources, last 26h
ao mine --since 7d --sources git,agents  # wider window, specific sources

Read .agents/mine/latest.json and extract: co-change clusters (files changing together), orphaned research (unreferenced .agents/research/ files), and complexity hotspots (high-CC functions with recent edits).

Fallback (no ao CLI): Use git log --since="7 days ago" --name-only to find recurring file groups. List .agents/research/*.md and check references in learnings.

Assign Initial Confidence. For every new learning candidate extracted, assign a confidence score based on evidence strength:

Evidence	Score	Rationale
Single session observation	0.3	Anecdotal — seen once, may not generalize
Explicit user correction or post-mortem finding	0.5	Demonstrated — user-validated signal
Pattern observed in 2+ sessions	0.6	Repeated — likely real, not coincidence
Validated across multiple sessions or projects	0.7	Strong — safe to auto-apply
Battle-tested, never contradicted	0.9	Near-certain — always apply

Also assign a scope tag: project:<name> (project-specific), language:<lang> (language convention), or global (universal pattern). Default to project:<current> unless the pattern is clearly language- or tool-universal.

Write the confidence and scope into the learning frontmatter:

---
title: "Learning title"
confidence: 0.3
scope: project:agentops
observed_in:
  - session: "YYYY-MM-DD"
    context: "Brief description of observation"
---

Step 2 — Grow: LLM-Driven Synthesis

This is the reasoning phase. Perform each sub-step using tool calls.

Flywheel Health Diagnostic: Compute σ (consistency), ρ (velocity), δ (decay) and report escape velocity status. See references/flywheel-diagnostics.md for measurement commands and remediation actions.

2a. Validate Top Learnings and Adjust Confidence

Select the 5 most recent files from .agents/learnings/. For each:

Read the learning file (including its confidence and scope frontmatter)
If it references a function or file path, use Read to verify the code still exists
Classify as: validated (matches), stale (changed), or contradicted (opposite)
Adjust confidence based on validation result:
- Validated and still accurate: +0.1 (cap at 0.9)
- Stale but partially true: no change (mark for review)
- Contradicted by current code: -0.2 (floor at 0.1, flag for removal)
- Pattern validated in a new project: +0.15
- Not referenced in 30+ days: -0.05 (time decay)
- Not referenced in 90+ days: -0.1 (time decay)

Update the learning file frontmatter with the new confidence score.

Auto-Promotion Rule: After confidence adjustment, check if the learning's confidence is > 0.7. If so, and it is not already in MEMORY.md, promote it:

Add the learning's key insight to the relevant MEMORY.md topic file
Log: "Promoted '<title>' to MEMORY.md (confidence: <score>)"
If the same pattern appears in 2+ projects with confidence >= 0.8, promote its scope from project:<name> to global

2b. Rescue Orphaned Research

For each orphaned research file from mine output: read it, summarize the key insight in 2-3 sentences, and propose as a new learning candidate with title and category.

2c. Cross-Domain Synthesis

Group mine findings by theme (e.g., "testing patterns", "CLI conventions"). For themes with 2+ findings, write a synthesized pattern candidate capturing the common principle.

2d. Gap Identification

Compare mine output topics against existing learnings. Topics with no corresponding learning are knowledge gaps. List each with: topic, evidence, suggested learning title.

Step 3 — Compile: Build the Wiki

This is the core new phase. The LLM reads all raw .agents/ artifacts and compiles them into structured, interlinked wiki articles.

3a. Inventory Source Artifacts

Scan all compilable directories:

find .agents/learnings .agents/patterns .agents/research .agents/retros \
     .agents/forge .agents/knowledge -type f -name "*.md" 2>/dev/null | sort

For each file, compute a content hash:

md5sum "$file" | cut -d' ' -f1

Compare against .agents/compiled/.hashes.json (previous compilation hashes). Files with unchanged hashes skip compilation (incremental mode).

3b. Extract Topics and Entities

Read each changed source artifact. Extract:

Topics: major themes (e.g., "testing strategy", "CI pipeline", "knowledge flywheel")
Entities: specific tools, files, patterns, people referenced
Relationships: which topics connect to which entities

Group artifacts by topic. Each topic becomes a wiki article.

3c. Compile Articles

For each topic, compile an encyclopedia-style article:

If AGENTOPS_COMPILE_RUNTIME is set, use scripts/compile.sh:

AGENTOPS_COMPILE_RUNTIME=ollama scripts/compile.sh \
  --sources .agents/ \
  --output .agents/compiled/ \
  --incremental

If running inline (no runtime set), compile directly:

For each topic group, write a wiki article to .agents/compiled/<topic-slug>.md:

---
title: "<Topic Title>"
compiled: "YYYY-MM-DD"
sources:
  - .agents/learnings/example.md
  - .agents/research/example.md
tags: [topic1, topic2]
---

# <Topic Title>

<2-3 paragraph synthesis of all source artifacts on this topic.
Not a summary — a compiled understanding that connects the dots
across multiple observations.>

## Key Insights

- <Insight 1> — from [[source-article-1]]
- <Insight 2> — from [[source-article-2]]

## Related

- [[other-topic-1]] — <why related>
- [[other-topic-2]] — <why related>

## Sources

- `source1.md` — .agents/learnings/source1.md
- `source2.md` — .agents/research/source2.md

Use [[backlinks]] (Obsidian-style wikilinks) for cross-references between articles.

3d. Build Index

Write .agents/compiled/index.md:

# Knowledge Wiki — Index

> Auto-compiled from .agents/ corpus. Last updated: YYYY-MM-DD.
> Articles: N | Sources: N | Topics: N

## By Category

### <Category 1>
- [[article-1]] — one-line summary
- [[article-2]] — one-line summary

### <Category 2>
- [[article-3]] — one-line summary

3e. Append to Log

Append to .agents/compiled/log.md:

## [YYYY-MM-DD] compile | <N> articles from <M> sources
- New: <list of new articles>
- Updated: <list of updated articles>
- Unchanged: <count> (skipped, hashes match)

3f. Save Hashes

Write .agents/compiled/.hashes.json:

{
  ".agents/learnings/example.md": "abc123...",
  ".agents/patterns/example.md": "def456..."
}

Step 4 — Lint: Wiki Health Check

Scan the compiled wiki for quality issues. This is the Karpathy "lint pass."

4a. Contradictions

Compare claims across articles. Flag pairs where one article asserts X and another asserts not-X or a conflicting recommendation.

4b. Orphan Pages

Find articles with zero inbound [[backlinks]] from other articles. These are disconnected knowledge — either missing links or low-value articles.

4c. Missing Cross-References

Find articles that discuss the same entities/topics but don't link to each other.

4d. Stale Claims

For articles referencing specific code (file paths, function names), verify the code still exists. Flag stale references.

4e. Coverage Gaps

Compare the topic list against the source artifacts. Flag source artifacts that contributed to zero wiki articles (un-compiled knowledge).

4f. Write Lint Report

Write .agents/compiled/lint-report.md:

# Wiki Lint Report — YYYY-MM-DD

## Contradictions: N
- [[article-a]] vs [[article-b]]: <description>

## Orphan Pages: N
- [[orphan-1]], [[orphan-2]]

## Missing Cross-References: N
- [[article-x]] should link to [[article-y]] (shared topic: <topic>)

## Stale Claims: N
- [[article-z]] references `path/to/deleted.go` (line N)

## Coverage Gaps: N
- .agents/learnings/uncovered.md — not compiled into any article

## Health Score: N/100

Step 5 — Defrag: Mechanical Cleanup

Run cleanup to find stale, duplicate, and oscillating artifacts.

ao defrag --prune --dedup --oscillation-sweep

Read .agents/defrag/latest.json and note: orphaned learnings (unreferenced, >30 days old), near-duplicate pairs (>80% content similarity), and oscillating goals (alternating improved/fail for 3+ cycles).

Fallback: find .agents/learnings -name "*.md" -mtime +30 for stale files. Check .agents/evolve/cycle-history.jsonl for alternating result patterns.

Normalization Defect Scan

During defrag, scan the learnings and patterns pool for structural defects that degrade flywheel quality:

# Placeholder patterns: files with only frontmatter, no content after closing ---
for f in .agents/patterns/**/*.md .agents/learnings/**/*.md; do
  [ -f "$f" ] || continue
  content_after_frontmatter=$(awk '/^---$/{n++; if(n==2) found=1; next} found{print}' "$f" | grep -c '[^ ]')
  [ "$content_after_frontmatter" -eq 0 ] && echo "PLACEHOLDER: $f"
done

# Stacked frontmatter: multiple --- delimiter pairs (>2 occurrences of ^---$)
grep -rl '^---$' .agents/learnings/ .agents/patterns/ 2>/dev/null | while read f; do
  count=$(grep -c '^---$' "$f")
  [ "$count" -gt 2 ] && echo "STACKED_FRONTMATTER: $f ($count delimiters)"
done

# Bundled multi-learning files: more than one ## Learning heading
grep -rl '^## Learning' .agents/learnings/ 2>/dev/null | while read f; do
  count=$(grep -c '^## Learning' "$f")
  [ "$count" -gt 1 ] && echo "BUNDLED: $f ($count learnings in one file)"
done

# Duplicated headings within a file
for f in .agents/learnings/**/*.md .agents/patterns/**/*.md; do
  [ -f "$f" ] || continue
  dupes=$(grep '^## ' "$f" | sort | uniq -d)
  [ -n "$dupes" ] && echo "DUPLICATE_HEADING: $f — $dupes"
done

Report normalization defects in the defrag output. If any are found, list them with severity:

PLACEHOLDER → HIGH (empty knowledge pollutes retrieval)
STACKED_FRONTMATTER → MEDIUM (parsing errors, possible data loss)
BUNDLED → HIGH (breaks per-learning citation tracking)
DUPLICATE_HEADING → LOW (cosmetic, may confuse extraction)

Step 6 — Report

mkdir -p .agents/compile

Write .agents/compile/YYYY-MM-DD-report.md:

# Compile Report — YYYY-MM-DD

## Compilation Summary
- Articles compiled: N (new: N, updated: N, unchanged: N)
- Source artifacts processed: N
- Topics identified: N
- Backlinks created: N

## Lint Summary
- Health score: N/100
- Contradictions: N | Orphans: N | Stale claims: N | Gaps: N

## New Learnings Proposed
- [title]: [summary] (source: [research file or synthesis])

## Validations
- Validated: N | Stale: N (list files) | Contradicted: N (list with explanation)

## Knowledge Gaps
- [topic]: [evidence] → suggested learning: "[title]"

## Defrag Summary
- Orphaned: N | Duplicates: N | Oscillating goals: N

## Recommendations
1. [Actionable next step]

If bd is available, create issues for knowledge gaps:

bd add "[Knowledge Gap] <topic>" --label knowledge --label compile

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 via cron:

# Schedule nightly compilation on bushido (Ollama backend)
ao schedule create --name "nightly-compile" \
  --cron "0 3 * * *" \
  --command "AGENTOPS_COMPILE_RUNTIME=ollama ao compile --compile-only"

Flags

Flag	Default	Description
`--compile-only`	off	Skip mine/grow, just compile + lint
`--lint-only`	off	Only run lint pass on existing wiki
`--defrag-only`	off	Only run defrag/cleanup
`--mine-only`	off	Only run mine + grow (legacy behavior)
`--full`	on	Full cycle: mine → grow → compile → lint → defrag
`--since`	`26h`	Time window for mine phase
`--incremental`	on	Skip unchanged source files (hash-based)
`--force`	off	Recompile all articles regardless of hashes

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: Nightly compilation on bushido GPU via Ollama.

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

Troubleshooting

Problem	Cause	Solution
`ao mine` not found	ao CLI not in PATH	Use manual fallback in Step 1
No orphaned research	All research already referenced	Skip 2b, proceed to synthesis
Empty mine output	No recent activity	Widen `--since` window
Oscillation sweep empty	No oscillating goals	Healthy state — no action needed
Ollama connection refused	Tunnel not running or wrong host	Run `bushido tunnel ollama` or check `OLLAMA_HOST`
Compilation too slow	Large corpus on small model	Use `--incremental` or switch to larger model
Hash file missing	First compilation	Normal — full compile runs, hashes saved after

compile