Help us improve
Share bugs, ideas, or general feedback.
From agentops
Monitors knowledge flywheel health by measuring knowledge pool sizes, recent activity, artifact staleness, and cache hit rates across learnings, patterns, research, and retros.
npx claudepluginhub boshu2/agentops --plugin agentopsHow this skill is triggered — by the user, by Claude, or both
Slash command
/agentops:flywheelhaikuThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Monitor the knowledge flywheel health.
Shows knowledge base health metrics: file counts, backlog depth, audit status, codemap dates, tag stats, and coverage gaps. Invoke with /stats.
Proposes research-backed changes to knowledge systems by analyzing health reports, friction patterns, and derivation history. Requires approval before implementation.
Displays a work status dashboard for AgentOps workflow, showing current tasks, recent activity, git state, and inbox. Use /status to get a single-screen overview.
Share bugs, ideas, or general feedback.
Monitor the knowledge flywheel health.
Sessions → Transcripts → Forge → Pool → Promote → Knowledge
↑ │
└───────────────────────────────────────────────┘
Future sessions find it
Velocity = rate of knowledge flowing through. Friction = bottlenecks slowing the flywheel.
Given /flywheel:
# Count top-level artifact files (avoid counting directories)
LEARNINGS=$(find .agents/learnings -maxdepth 1 -type f 2>/dev/null | wc -l)
PATTERNS=$(find .agents/patterns -maxdepth 1 -type f 2>/dev/null | wc -l)
RESEARCH=$(find .agents/research -maxdepth 1 -type f 2>/dev/null | wc -l)
RETROS=$(find .agents/retros -maxdepth 1 -type f 2>/dev/null | wc -l)
echo "Learnings: $LEARNINGS"
echo "Patterns: $PATTERNS"
echo "Research: $RESEARCH"
echo "Retros: $RETROS"
# Recent learnings (last 7 days)
find .agents/learnings -maxdepth 1 -type f -mtime -7 2>/dev/null | wc -l
# Recent research
find .agents/research -maxdepth 1 -type f -mtime -7 2>/dev/null | wc -l
# Old artifacts (> 30 days without modification)
find .agents/ -name "*.md" -mtime +30 2>/dev/null | wc -l
if command -v ao &>/dev/null; then
# Get citation report (cache metrics)
CITE_REPORT=$(ao metrics cite-report --json --days 30 2>/dev/null)
if [ -n "$CITE_REPORT" ]; then
HIT_RATE=$(echo "$CITE_REPORT" | jq -r '.hit_rate // "unknown"')
UNCITED=$(echo "$CITE_REPORT" | jq -r '(.uncited_learnings // []) | length')
STALE_90D=$(echo "$CITE_REPORT" | jq -r '.staleness["90d"] // 0')
echo "Cache hit rate: $HIT_RATE"
echo "Uncited learnings: $UNCITED"
echo "Stale (90d uncited): $STALE_90D"
fi
else
# ao-free fallback: compute approximate metrics from files
echo "Cache health (ao-free fallback):"
echo "Active learnings (30d): $(find .agents/learnings/ -name '*.md' -mtime -30 2>/dev/null | wc -l | tr -d ' ')"
echo "Forge candidates pending: $(ls .agents/forge/*.md 2>/dev/null | wc -l | tr -d ' ')"
if [ -f .agents/ao/citations.jsonl ]; then
echo "Total citations: $(wc -l < .agents/ao/citations.jsonl | tr -d ' ')"
echo "Unique learnings cited: $(grep -o '"artifact_path":"[^"]*"' .agents/ao/citations.jsonl 2>/dev/null | sort -u | wc -l | tr -d ' ')"
else
echo "No citation data (citations.jsonl not found)"
fi
[ -f .agents/ao/outcomes.jsonl ] && echo "Session outcomes recorded: $(wc -l < .agents/ao/outcomes.jsonl | tr -d ' ')"
fi
if command -v ao &>/dev/null; then
ao metrics flywheel status 2>/dev/null || echo "ao metrics flywheel status unavailable"
ao status 2>/dev/null || echo "ao status unavailable"
ao maturity --scan 2>/dev/null || echo "ao maturity unavailable"
ao anti-patterns 2>/dev/null || echo "ao anti-patterns unavailable"
ao badge 2>/dev/null || echo "ao badge unavailable"
# Knowledge maintenance
ao dedup --merge 2>/dev/null || true
ao contradict 2>/dev/null || true
ao constraint review 2>/dev/null || true
ao curate status 2>/dev/null || true
ao metrics health 2>/dev/null || true
ao metrics cite-report --days 30 2>/dev/null || true
# Active pruning: archive stale, evict low-utility, and curate noisy uncited learnings
ao maturity --expire --archive 2>/dev/null || true
ao maturity --evict --archive 2>/dev/null || true
ao maturity --curate --archive 2>/dev/null || true
# Retrieval quality: use the representative live corpus when it exists
if [ -d cli/cmd/ao/testdata/retrieval-bench-live ]; then
ao retrieval-bench --live --corpus cli/cmd/ao/testdata/retrieval-bench-live --json 2>/dev/null || true
fi
else
echo "ao CLI not available — using file-based metrics"
echo "Pool depths:"
for pool in learnings patterns forge knowledge research retros; do
echo " $pool: $(ls .agents/${pool}/*.md 2>/dev/null | wc -l | tr -d ' ')"
done
echo " global patterns: $(ls ~/.claude/patterns/*.md 2>/dev/null | wc -l | tr -d ' ')"
echo "See references/promotion-tiers.md for tier definitions"
fi
If .agents/ao/skill-telemetry.jsonl exists, use jq to extract: invocations by skill, average cycle time per skill, gate failure rates. Include in health report (Step 6) under ## Process Metrics.
Cross-reference validation: scan knowledge artifacts for broken internal references.
Use scripts/artifact-consistency.sh (method documented in references/artifact-consistency.md).
Default allowlist lives at references/artifact-consistency-allowlist.txt; use --no-allowlist for a full raw audit.
Health indicator: >90% = Healthy, 70-90% = Warning, <70% = Critical.
Write to: .agents/flywheel-status.md
# Knowledge Flywheel Health
**Date:** YYYY-MM-DD
## Pool Depths
| Pool | Count | Recent (7d) |
|------|-------|-------------|
| Learnings | <count> | <count> |
| Patterns | <count> | <count> |
| Research | <count> | <count> |
| Retros | <count> | <count> |
## Velocity (Last 7 Days)
- Sessions with extractions: <count>
- New learnings: <count>
- New patterns: <count>
## Artifact Consistency
- References scanned: <count>
- Broken references: <count>
- Consistency score: <percentage>%
- Status: <Healthy/Warning/Critical>
## Cache Health
- Hit rate: <percentage>%
- Uncited learnings: <count>
- Stale (90d uncited): <count>
- Status: <Healthy/Warning/Critical>
## Retrieval Quality
- Live corpus coverage: <percentage or unavailable>
- Live corpus learnings: <count or unavailable>
- Status: <Healthy/Warning/Critical>
## Health Status
<Healthy/Warning/Critical>
## Friction Points
- <issue 1>
- <issue 2>
## Recommendations
1. <recommendation>
2. <recommendation>
Tell the user:
| Metric | Healthy | Warning | Critical |
|---|---|---|---|
| Learnings/week | 3+ | 1-2 | 0 |
| Stale artifacts | <20% | 20-50% | >50% |
| Research/plan ratio | >0.5 | 0.2-0.5 | <0.2 |
| Cache hit rate | >80% | 50-80% | <50% |
Four golden signals (always shown) reveal whether knowledge is truly compounding or just accumulating noise.
ao flywheel status # table output with golden signals
ao flywheel status --json # machine-readable
| # | Signal | Question | Key Metric |
|---|---|---|---|
| 1 | Velocity Trend | Is σρ-δ increasing? | Linear regression slope of baseline velocities (7d/30d) |
| 2 | Citation Pipeline | Are citations useful? | % of feedback with reward > 0.6 |
| 3 | Research Closure | Is research being mined? | % orphaned research (no learning backlink) |
| 4 | Reuse Concentration | Is the whole pool active? | Gini coefficient of citation distribution |
| Signal | Healthy | Warning | Critical |
|---|---|---|---|
| Velocity Trend | compounding (slope > +0.01) | stagnant | decaying (slope < -0.01) |
| Citation Pipeline | reinforcing (>60% high-util) | inert (30-60%) | degrading (<30%) |
| Research Closure | mining (<=10% orphans) | — | hoarding (>=10% orphans) |
| Reuse Concentration | distributed (Gini<0.4, active>30%) | concentrated | dormant (Gini>0.7 or active<10%) |
Overall verdict: 3+ healthy = compounding, 3+ critical = decaying, mixed = accumulating.
| Verdict | Action |
|---|---|
| decaying | Run /compile cycle, archive stale artifacts, increase citation via ao lookup |
| accumulating | Review orphaned research (/research→/post-mortem --quick pipeline), improve forge quality |
| compounding | Maintain cadence. Consider capturing baselines (ao metrics baseline) for trend tracking |
Read references/cache-eviction.md for the full eviction pipeline (passive tracking → confidence decay → maturity scan → archive).
Phase 4 (soc-ytpq) governance for ~/.agents/learnings/ — all advisory, none block by default. Full details in references/hub-budget.md.
ao maturity --evict --target-size=250M (lowest-utility-first; respects lifecycle.IsEvictionEligible so canonical / high-confidence files are protected).ao harvest WARNs when promotions exceed --max-promotions=N (default 500; AO_MAX_PROMOTIONS=N env as fallback; ≤0 disables). WARN-only — the 2,638-promotion soc-ujls drain proves a hard gate would falsely block legitimate runs.source_rig: in its frontmatter (empty writers serialize as source_rig: unknown). Both harvest.Promote and pool.(*Pool).Promote content-dedup against the same hub via ~/.agents/pool/promoted-index.jsonl.SkipGlobalHub defaults to true (the agentops-b3v / soc-ujls fix), then grep -h '^source_rig:' ~/.agents/learnings/*.md | sort | uniq -c | sort -rn to identify the regressed writer. Use --target-size, never raw rm.User says: /flywheel — Counts pool depths, checks recent activity, validates artifact consistency, writes health report to .agents/flywheel-status.md.
Hook trigger: After /post-mortem — Compares current vs historical metrics, flags velocity drops and friction points.
| Problem | Cause | Solution |
|---|---|---|
| All pool counts zero | .agents/ directory missing or empty | Run /post-mortem (or --quick) to seed knowledge pools |
| Velocity always zero | No recent extractions (last 7 days) | Run /post-mortem (or --quick) to extract and index learnings |
| "ao CLI not available" | ao command not installed or not in PATH | Install ao CLI or use manual pool counting fallback |
| Stale artifacts >50% | Long time since last session or inactive repo | Run /provenance --stale to audit and archive old artifacts |
ao flywheel CLI command behavior, linked to cmd tests (soc-jnfgi)