docs(positioning): wiki-framing sweep across all surface docs (soc-9xn0)#262
Merged
Conversation
…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
…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
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
…-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
…n (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
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Lock single positioning thesis (wiki for your agents + corpus moat) across all surface docs. Adds 2 new bridge documents (
docs/trust-factory.md,docs/wiki-for-agents.md) and 2 new comparison docs (vs-tons-of-skills,vs-everything-claude-code). Aligns README, PRODUCT, GOALS, docs/index, agentops-brief, 3 existing comparison docs, and 3 light-touch body docs.Source artifacts:
.agents/discovery/2026-05-07-positioning-doc-sweep.md.agents/council/2026-05-07-research-readme-positioning.md.agents/brainstorm/2026-05-07-trust-infrastructure-shovels-thesis.mdThe 10 locked decisions (D1–D10) — headline, opening paragraph, the moat statement, the "not a coding harness" non-positioning move, the receipts block, the enterprise-pattern statement, the "What if the labs ship this natively?" section, the Notion comparison table, the SE→Context translation table, and the 300-line README target — are all placed.
What changed
README.md (Wave 1): 420 → 295 lines. New hero (D1+D2+D3+D4+D5), Notion comparison table (D8, 7 rows), SE→Context translation table (D9, 11 rows), enterprise-pattern statement (D6), "What if the labs ship this natively?" section (D7). Drops: intra-page nav bar, Validate/Nightly badges, Competitive Positioning section, 12-Factor Doctrine 4-tier table, mermaid diagram.
Strategic docs (Wave 2): PRODUCT.md, GOALS.md, docs/index.md, docs/agentops-brief.md aligned to wiki framing. PRODUCT gains D7 + receipts timestamp + corpus-durability tracking ref to soc-rv5p. GOALS gains a new North Star ("the wiki maintains itself") and a new directive #11 (corpus durability).
Comparison surface (Wave 3): competitive-radar refreshed with 7-competitor lane table + 6 differentiators + 5-lane segmentation. vs-compound-engineer updated to current state (37 skills, 51 agents, 7-phase, 10-target). vs-superpowers updated (Anthropic marketplace, 29K+ stars, wiki mechanism). NEW vs-tons-of-skills (volume-marketplace lane). NEW vs-everything-claude-code (cross-harness lane, with credibility-move flag on the unverified 140K+ stars / 21K+ forks claim from their README).
Bridge docs (Wave 4): NEW docs/trust-factory.md (5-step trust factory primitive — Identity → Reproducibility → Evaluation → Evidence → Recovery — for engineering-leads framing). NEW docs/wiki-for-agents.md (deflationary wiki framing for the busy buyer). documentation-index updated with all 4 new docs.
Body doc light touch (Wave 5): docs/cdlc.md leads with SE→Context concept, defers CDLC acronym to body. docs/the-science.md gains practitioner-facing pointer to trust-factory. docs/positioning/devops-for-vibe-coding.md taglines aligned, DevOps argument preserved.
Validation (Wave 6): Fixed 5 mkdocs --strict link warnings by switching
../README.md/../PRODUCT.mdcross-links in new bridge docs to absolute github.com URLs (matches existing convention).Validation results
scripts/docs-build.sh --check(mkdocs --strict): PASSscripts/check-competitive-freshness.sh: PASS (all 8 docs ≤ 45 days)scripts/corpus-stats.sh --table: runs cleanwc -l README.md: 295 (≤ 300 target)Test plan
scripts/docs-build.sh --checkpasses locally and in CIscripts/check-competitive-freshness.shpasses (45-day window)Beads epic
soc-9xn0(CLOSED)soc-rv5p(corpus-durability fix; out of scope for this docs sweep)Out of scope (intentional non-goals)