* docs(positioning): wave 1 — README hero rewrite to wiki framing (soc-nybd)
Apply the locked decisions D1–D10 from the positioning doc-sweep packet:
- D1 headline: "A wiki for your agents. Built so you own the moat."
- D2 wiki-framing opener; D3 moat statement + "shovel" anchor
- D4 non-positioning ("AgentOps is not a coding harness")
- D5 receipts block (timestamped 2026-05-04 stable snapshot)
- D6 enterprise-pattern statement (pattern claim, no company names)
- D7 "What if the labs ship this natively?" section before Contributing
- D8 Notion vs AgentOps comparison table (7 rows)
- D9 SE → Context translation table (11 rows) replacing prior SDLC/CDLC table
- D10 line budget: 420 → 295 lines
Drops: intra-page nav bar, Validate/Nightly badges (stars retained),
"Competitive Positioning" section, 12-Factor Doctrine 4-tier table (now
single sentence linking 12factoragentops.com), mermaid diagram, AOP-CLAIM
markers, cross-runtime <details> block.
Forward references to docs/wiki-for-agents.md and docs/trust-factory.md
will resolve when Wave 4 lands those new files.
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
* docs(positioning): wave 2 — strategic doc alignment to wiki framing (soc-ylp9, soc-rnbf, soc-x3b6, soc-b1r3)
Align PRODUCT.md, GOALS.md, docs/index.md, docs/agentops-brief.md with
the README's locked positioning thesis.
PRODUCT.md (soc-ylp9):
- Mission opener: wiki framing replaces "keeps the books / compiles the
context / compounds the corpus"
- "What the Product Actually Is" leads with wiki framing before four-layer model
- New "What if the labs ship this natively?" section (D7 verbatim with
"Anthropic's Managed Agents")
- Evidence section timestamped: corpus wipe on 2026-05-07, durability fix
tracked in soc-rv5p
- Cross-links to docs/trust-factory.md (forward to Wave 4)
- last_reviewed: 2026-05-06 → 2026-05-07
GOALS.md (soc-rnbf):
- Lede: "A wiki for your agents — repo-native, version-controlled,
mechanically maintained"
- New North Star: "The wiki maintains itself: every session contributes to
.agents/ by default"
- New directive #11: corpus durability (tag corpus-state, soc-rv5p)
- All 10 prior directives preserved
docs/index.md (soc-x3b6):
- Hero rebuilt: D1 headline + subhead + D2 wiki framing + D3 italicized
moat + "AgentOps is the shovel. Start digging."
- mkdocs hero buttons (Install / See It Work / GitHub) preserved
- Body sections unchanged
docs/agentops-brief.md (soc-b1r3):
- Opener swapped to D2 + D3 (wiki framing + shovel anchor)
- New "What if the labs ship this natively?" paragraph (D7 verbatim)
- See-also forward links to docs/trust-factory.md, docs/wiki-for-agents.md
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
* docs(comparisons): wave 3 — comparison surface refresh + 2 new lane docs
Refresh 3 existing comparison docs to current competitive state and add
2 new comparison docs covering volume-marketplace and cross-harness lanes.
Refresh:
- competitive-radar.md (soc-33kk): 7-competitor lane table, 6 differentiators
(persistent corpus, off-API daemon, multi-model council, model-independent
phase routing, context-engineering vocabulary, honest empirical disclosure),
5-lane segmentation, last_reviewed → 2026-05-07
- vs-compound-engineer.md (soc-al8s): CE current state (37 skills/51 agents/
7-phase/10-target), new model-independent phase routing row, last_reviewed
added
- vs-superpowers.md (soc-zhig): Anthropic marketplace fact, 29K+ stars, wiki
framing in cross-session memory section (25-year-old idea), last_reviewed
added
NEW:
- vs-tons-of-skills.md (soc-fmkw): volume-marketplace lane comparison —
Tons-of-Skills (425 plugins, 2,810 skills, 200 agents, CCPI grading) vs
AgentOps as different categories. 90 lines.
- vs-everything-claude-code.md (soc-jhtu): cross-harness-parity lane
comparison — everything-claude-code (48 subagents, 182 skills, 5-runtime
DRY parity) vs AgentOps's per-phase model routing. Includes credibility-
move flag on the unverified 140K+ stars / 21K+ forks claim. 181 lines.
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md, council
research at .agents/council/2026-05-07-research-readme-positioning.md
Epic: soc-9xn0
* docs(positioning): wave 4 — bridge docs + index update (soc-momx, soc-envj, soc-e031)
Two new bridge documents that complete the positioning surface, plus the
documentation index update to make all 4 new docs reachable.
NEW docs/trust-factory.md (soc-momx, 112 lines, 854 words):
The 5-step trust-factory primitive (Identity → Reproducibility → Evaluation
→ Evidence → Recovery) mapped to AgentOps mechanisms. Bridge document for
engineering leads in regulated environments who think in trust-factory
vocabulary already. Pairs with the wiki framing as the alternative buyer
view.
NEW docs/wiki-for-agents.md (soc-envj, 93 lines, 824 words):
Standalone wiki framing — "wikis aren't new, the novel part is making the
discipline mechanical so it actually happens." Uses the D8 Notion comparison
table verbatim, covers the .agents/ directory layout, and explains why most
wikis fail (write-tax + bitrot) and how AgentOps inverts the pattern.
docs/documentation-index.md (soc-e031):
- Added "Bridge / framing docs" sub-list under Four Product Layers with
trust-factory.md and wiki-for-agents.md (visible above the fold)
- Added vs-tons-of-skills.md and vs-everything-claude-code.md to existing
Comparisons section (alphabetical with other vs-* entries)
- 222 → 226 entries; 309 → 316 lines
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
* docs(positioning): wave 5 — body doc cross-links + light framing align (soc-igqq, soc-chkd, soc-cout)
Light touch on three linked body docs to align with the wiki framing
without restructuring their substance.
docs/cdlc.md (soc-igqq):
- Lede leads with "Software engineering took 50 years..." + the 11-row
SE→Context translation table (D9 verbatim)
- "CDLC" acronym deferred to body intro after the table establishes the
concept (acronym kept in 11+ body uses)
- Companion docs section cross-links to wiki-for-agents.md, trust-factory.md
- 248 → 273 lines
docs/the-science.md (soc-chkd):
- Practitioner-facing pointer under TL;DR: "see [Trust Factory]" +
"[A wiki for your agents]"
- Companion docs section
- 671 → 678 lines, science content intact
docs/positioning/devops-for-vibe-coding.md (soc-cout):
- Primary tagline → wiki framing ("A wiki for your agents — built so you
own the moat"); secondary recast as DevOps-lineage tagline
- Category line acknowledges DevOps lineage as historical, not category label
- Date 2026-01-31 → 2026-05-07; version 1.2.0 → 1.3.0
- Cross-link to ../wiki-for-agents.md
- DevOps argument preserved (14 DevOps mentions intact, 6-differentiators
table untouched)
- 343 → 351 lines
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
* docs(positioning): wave 6 — fix mkdocs --strict link warnings (soc-uc3w)
The wave 4 bridge docs and wave 3 competitive-radar refresh used relative
links that escape the mkdocs docs/ tree:
- ../README.md and ../PRODUCT.md cross-links → switched to absolute
https://github.com/boshu2/agentops/blob/main/{README,PRODUCT}.md
(matches existing docs/documentation-index.md convention)
- ../../.agents/council/ research link → demoted to plain-text path
reference (the .agents/ tree is gitignored runtime state, not a
publishable doc surface)
Verified: scripts/docs-build.sh --check now exits 0 with "OK: mkdocs
build --strict passed". Five strict-mode warnings cleared.
Wave 6 validation results (12-item checklist):
- mkdocs --strict: PASS
- competitive-freshness: PASS (8/8 docs ≤45 days)
- README ≤ 300: 295 lines
- D1-D10 visible across README, PRODUCT, GOALS, docs/index, docs/agentops-brief, docs/wiki-for-agents
- Cross-links: README→{wiki-for-agents, trust-factory}, PRODUCT→{trust-factory, wiki-for-agents}
- New comparison docs (vs-tons-of-skills, vs-everything-claude-code) exist
and are linked from competitive-radar.md and documentation-index.md
- "operational discipline" residues are historical-only (release notes,
origin-story, devops-for-vibe-coding messaging hierarchy)
Note: ao goals measure shows ambient fails unrelated to this sweep — the
tool is cwd-sensitive and reports "No such file or directory" for scripts
that exist (separate bug, not introduced by this work).
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
docs/INDEX.md (contract catalog) and docs/index.md (MkDocs landing) shared the
same case-folded name on case-insensitive filesystems, leaving the working tree
in a phantom-modified state and breaking contract-compatibility-gate when the
script read whichever file the OS resolved at run time.
Resolves TASK-1 + TASK-2 of .agents/plans/2026-04-26-resolve-docs-index-case-collision.md:
- Move catalog content from HEAD:docs/INDEX.md into docs/documentation-index.md
- Repoint contract validators (scripts/check-contract-compatibility.sh,
scripts/contract-orphans-allowlist.txt) and their tests at the new path
- Update navigation references across README.md, AGENTS.md, CLAUDE.md, and the
docs/ tree (newcomer-guide, CONTRIBUTING, CI-CD, plans/, positioning/,
templates/, contract examples)
- Replace stale docs/README.md mentions in CLAUDE.md / AGENTS.md / repo-execution
profile example with docs/index.md (the actual MkDocs landing)
Verification:
- bash scripts/check-contract-compatibility.sh -> 0 failures, 24 contracts catalogued
- bash tests/scripts/test-contract-compatibility-gate.sh -> 7/7 PASS (verified pre-rebase)
- bash tests/skills/test-repo-native-orchestration.sh -> 28/28 PASS (verified pre-rebase)
- git ls-files | awk casefold-dup scan -> empty
TASK-3 (casefold-collision guard script) and TASK-4 (worktree disposition) from
the plan remain to be done in a follow-up.
## Docs site — boshu2.github.io/agentops
- Replace Jekyll minima with MkDocs Material (slate dark palette default)
- Landing hero scoped to .landing-hero (no gradient bleed on inner pages)
- Section landings (getting-started, architecture, reference, contracts, levels) with narrative ledes
- Generate skill catalog + per-skill pages from skills/*/SKILL.md at build
- Generate CLI reference from cli/docs/ at build (fails build on missing source)
- Fix every internal link via one-shot migration (scripts/migrations/2026-04-19-fix-docs-links.py)
- Wire mkdocs build --strict into pre-push gate (Check 25a)
- Replace .github/workflows/pages.yml with .github/workflows/docs.yml (actions/deploy-pages)
- README + docs/CONTRIBUTING updated with docs-build toolchain on-ramp
- tests/docs/validate-links.sh patched to understand mkdocs-generated paths
## RPI orchestrator strict-delegation contract
- Strict sub-skill delegation is now the default for /rpi, /discovery, /validation. No --full flag — always on.
- Canonical contract in skills/shared/references/strict-delegation-contract.md (plus Codex mirror)
- Forged learning with detection phrases + corrective actions (ao-inject-ready)
- Rename --no-lifecycle -> --no-scaffold in /discovery (Claude + Codex) with deprecation alias through v2.40.0
- Harden inline-work hotspots with orchestrator-owned markers in /crank STEPS 3a.3, 6.5, 8.7 + Inline Work Policy footer
- Flag consistency: --auto and --interactive scopes documented; --complexity syntax formalized
- CHANGELOG [Unreleased] documents + scaffolds; runtime hook enforcement explicitly deferred
## fix(hooks): go-test-precommit skips when no Go files staged
- Previously ran go vet + go build unconditionally, blocking non-Go commits when Go toolchain was missing or at a different version
- Now checks staged diff and exits cleanly if no *.go or go.{mod,sum,work} files are staged
- Applied to both hooks/ (source) and cli/embedded/hooks/ (synced)
Provenance: full RPI lifecycle with strict delegation at every phase boundary (Phase 1 Skill(discovery) -> Phase 2 Skill(crank) -> Phase 3 Skill(validation) -> Skill(vibe), Skill(post-mortem), Skill(retro)).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Positioning previously overweighted validation while underspecifying
learning and loop closure. Now both docs frame all three gaps as equal
parts of a single lifecycle contract, with links to context-lifecycle.md.
Fix right-side │ border alignment in box diagrams. Three fix types:
- Trailing space adjustment for border alignment
- Box border widening for content that exceeded width
- Bottom border dash count matching top border
Bo