mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
ao-pre-reduction@5b334a13f
22 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Bo
|
6d5d111faf |
feat(skills): land four-vendor skill corpus (#803)
## Summary - Lands the AgentOps skill corpus across source and Codex wrappers, including Gemini image targets. - Integrates the skill branch onto current origin/main and refreshes generated manifests/catalogs. - Normalizes local next-work queue enum drift and fixes shellcheck in alias-collision validation. ## Validation - bash scripts/regen-all.sh --check - bash scripts/validate-skill-schema.sh - bash tests/skills/test-token-budgets.sh - bash tests/skills/run-all.sh - bash scripts/audit-codex-parity.sh && bash scripts/validate-codex-override-coverage.sh && bash scripts/validate-codex-generated-artifacts.sh --scope worktree && bash scripts/validate-codex-api-conformance.sh && bash scripts/validate-codex-runtime-sections.sh && bash scripts/lint-codex-native.sh - bash skills/heal-skill/scripts/heal.sh --strict - PRE_PUSH_SKIP_MKDOCS=1 bash scripts/pre-push-gate.sh --fast MkDocs strict remains skipped locally via the documented PRE_PUSH_SKIP_MKDOCS=1 override because the repo currently emits repo-wide strict-link warnings unrelated to this landing; CI remains authoritative. |
||
|
Bo
|
f4f991bbda |
docs: fix broken intra-repo links in docs/ (ag-28dp #docs-link-rot) (#781)
## What Fix 44 broken intra-repo links across 7 files under `docs/`, surfaced by a `docs/` markdown link audit. `mkdocs.yml` has `strict: false`, so the broken links slipped past CI — but they break GitHub-raw viewing and agent file-reading (the repo treats pointer rot in base docs as a defect). ## Two pointer-rot classes 1. **41× `](skills/<name>.md)` → `](../skills/<name>/SKILL.md)`** — skills live at `skills/<name>/SKILL.md`, never `skills/<name>.md`, and `docs/` is one level deep so the target needs `../`. Several links already had the **correct link text** (e.g. `[skills/pre-mortem/SKILL.md](skills/pre-mortem.md)`) — only the href was wrong, confirming intent. Special case: `skills/catalog.md` → `SKILLS.md` (`docs/SKILLS.md` = the complete 82-skill reference). 2. **3× `](cli/commands.md)` → `](../cli/docs/COMMANDS.md)`** — the generated CLI command doc. Files: `GLOSSARY.md`, `index.md`, `context-lifecycle.md`, `behavioral-discipline.md`, `create-your-first-skill.md`, `context-packet.md`, `software-factory.md`. **Not touched:** the intentional placeholder links in `docs/standards/markdown-style-guide.md` (syntax demos: `url`, `image.png`, `./other-doc.md`, etc.). ## Verification - `docs/` broken-link scan: **44 → 0** outside the style-guide placeholders. - `markdownlint-cli2` on all 7 files: **0 errors**. - Pure link-href changes (44 insertions / 44 deletions); no prose or behavior change. Closes-scenario: ag-28dp#docs-link-rot Bounded-context: BC1-Corpus Evidence: ag-28dp |
||
|
Bo
|
b8731a4378 |
docs(audit): remediate stale root + key docs — hookless refs, skill counts, retired CI jobs (ag-lk80 #staleness-fixes) (#705)
## What Remediates verified staleness from the 2026-06-03 doc audit of root governance/product docs + the key `docs/` cluster. Two systemic rot patterns drove almost every finding: **skill-count drift** (73/78/~80 vs truth 82) and **hooks references that survived the 3.0 hookless teardown**. All fixes independently verified against `cli/**`, `scripts/**`, `.github/workflows/validate.yml`, and `skills/**`. ## Changes (by bead) | Bead | Sev | Fix | |---|---|---| | ag-swi1 | CRIT | `newcomer-guide.md`: removed hooks-as-runtime-layer framing (3.0 ships zero hooks); 5→4 layers; fixed dead `scripts/install-dev-hooks.sh` ref; reframed hooks as opt-in via `hooks-authoring` skill | | ag-99xv | CRIT | `index.md`: skill count 73→82. **The "broken catalog link" was a false positive** — `docs/skills/catalog.md` is generated at build by `gen_skill_pages.py`; link left unchanged | | ag-xa2b | CRIT | `cli-skills-map.md`: removed 5 phantom skills (`pr-plan`, `pr-retro`, `update`, `readme`, `oss-docs`) an agent could mis-invoke. Deep hooks-decoupling of this file (title, "Hook Callers" column, "Hooks → Commands" section) **decomposed to a follow-up** — half-editing leaves it internally inconsistent | | ag-w4t8 | CRIT | `AGENTS-CI.md`: dropped retired advisory rows `practice-citations` (RETIRED 2026-05-19) and `factory-claim-ledger-strict` (no such job; references nonexistent file) | | ag-bcl4 | HIGH | `index.md` + `documentation-index.md`: counts → 82, **and extended `sync-skill-counts.sh`** to cover both call-sites so the count self-heals and CI (`validate-doc-release.sh` → `sync --check`) catches future drift — the durable fix, not just retyping the number | | ag-p7zg | HIGH | `CLAUDE.md`: aligned Ship-phase pre-push command to `scripts/pre-push-gate.sh --fast`, matching `AGENTS-WORKFLOW.md` | | ag-y5ii | MED | `documentation-index.md`: dropped stale "hooks" from the how-it-works description | ## Deferred (filed as follow-up beads, not in this PR) - PRODUCT.md "April 2026 Claude Code source analysis" reframe — product positioning, operator's call - Full hooks-decoupling of `cli-skills-map.md` — structural rework, needs its own verification - `bd worktree create --branch` syntax is wrong in CLAUDE.md/AGENTS-WORKFLOW.md (needs a positional name) — discovered this session - `validate-bd-closeout-contract.sh` requires `bd dolt push` conditional wording in AGENTS.md that the AGENTS split dropped (pre-existing main red, local-only gate) - Second-wave sweep of the remaining ~80 `docs/` files (ag-bz8n) ## Verification - `scripts/sync-skill-counts.sh --check` → clean (both new call-sites covered) - `scripts/validate-cli-skills-map.sh` → PASS - `tests/docs/validate-doc-release.sh` → PASS - No residual `hooks/` / `hooks.json` runtime refs in `newcomer-guide.md` - All referenced paths exist (`skills/hooks-authoring/`, `scripts/pre-push-gate.sh`) Closes-scenario: ag-lk80#staleness-fixes Bounded-context: BC1-Corpus Evidence: docs/index.md |
||
|
Bo
|
c640ef2379 |
fix(ops): route work selection through reconciliation
Route status/quickstart/release/beads through ao reconcile before backlog selection or release-health claims. Correct release-tag CI skip docs, regenerate registry, and clarify the reconcile release-tag next action. |
||
|
Boden Fuller
|
b8c5a3761b |
feat(agentops): make 3.0 hookless-first
Add DDD skill-domain contracts, hook lease inventory, replacement ports, artifact-first RPI skill boundaries, and release exact-SHA validation. Demote ao inject to a compatibility adapter and remove prompt-only default hooks. |
||
|
Boden Fuller
|
ee763750ba |
docs: rename PRACTICE.md to PRACTICE-REGISTRY.md + add CDLC narrow-waist doctrine
Rescope PRACTICE.md into PRACTICE-REGISTRY.md: it now owns only the practice-slug lineage registry, not product positioning or CDLC doctrine. Update all references (schema, validate-practice-citations.sh, bats test, architecture-terms.md, documentation-index.md, aggregate.go comment). Introduce the Context Density Rule as a canonical domain concept: every high-value context token carries intent, boundary, evidence, decision, constraint, or next action. New domain entry context-density-rule.md (+ codex mirror). Thread the BDD/Gherkin + DDD + Hexagonal + TDD narrow waist through cdlc.md, README.md, PRODUCT.md, GOALS.md, and the rpi/domain/ post-mortem skills. Sync codex artifacts. |
||
|
Bo
|
ab479e2670 |
docs(positioning): wiki-framing sweep across all surface docs (soc-9xn0) (#262)
* 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
|
||
|
Bo
|
2e4653938b |
feat: factory claim ledger with proof taxonomy (soc-kizn.1) (#256)
* feat(docs,scripts,tests): factory claim ledger with proof taxonomy (soc-kizn.1) Lands the claim-to-proof ledger for the factory reconcile program (epic soc-kizn). Maps every claim-bearing paragraph in 9 public source docs to its current evidence, missing proof, owner issue, validation level, release posture, and anti-overclaim wording. Enforced mechanically. Scaffolded contract: - docs/contracts/factory-claim-ledger.md — operator-facing contract doc - docs/contracts/factory-claim-ledger.schema.json — JSON Schema with closed enums for validation_level, release_posture, evidence_status, authority_state, promotion_state - docs/contracts/factory-claim-ledger.example.json — 24-row authoritative ledger covering README, PRODUCT, GOALS, docs/index, docs/agentops-brief, docs/assurance-profile, docs/software-factory, docs/comparisons/**, docs/contracts/factory-*.md - docs/assurance-profile.md — new authoring surface; high-assurance posture doc with three claim markers - scripts/check-factory-claim-ledger.sh — validator (--strict mode rejects unledgered high-claim paragraphs in scanner sources, mismatched markers, orphan rows, L2/L3 rows without evidence_artifacts, unknown enum values) - tests/fixtures/factory-claim-ledger/ — positive + 4 negative fixtures (missing-marker, orphan-row, unknown-enum, l2-no-evidence) exercise the validator's reject paths under --strict Source-doc claim markers: - GOALS.md, PRODUCT.md, README.md, docs/index.md, docs/agentops-brief.md, docs/software-factory.md, docs/contracts/factory-admission.md, docs/contracts/factory-yield-ledger.md, and 4 docs/comparisons/* now carry <!-- agentops:claim:AOP-CLAIM-* --> markers adjacent to the matching claim paragraphs Acceptance: bash scripts/check-factory-claim-ledger.sh --strict exits 0; the bead validation block requires this and the new fixture suite verifies strict-mode reject paths. Anti-overclaim discipline: L0/L1 claims stay described as roadmap/contracted_l0/locally_checked_l1; only L2/L3 rows with evidence_artifacts may use "validated" wording in source docs. * fix(tests): add demoted-claim row to positive fixture (soc-kizn.1) Bead acceptance requires fixtures cover downgrade/demotion behavior. Adds FIXTURE-DEMOTED-CLAIM with promotion_state=demoted, evidence_status=stale, validation_level=L0, release_posture=roadmap, plus matching README marker. Validator --strict still PASS. * fix(docs): keep claim ledger validator path mkdocs-safe * chore(docs): normalize claim ledger fixture endings * fix(docs): add four-layers claim row + marker (rebase fixup, soc-kizn.1) Rebase onto main pulled in sx99's new four-layers paragraph in docs/agentops-brief.md (line 11), which contains "validated" without a marker. Adds AOP-CLAIM-BRIEF-FOUR-LAYERS row to the ledger and injects the matching marker. Validator --strict back to PASS. |
||
|
Bo
|
a427dcce6d |
docs(positioning): assurance profile + goals as reconcile setpoints (soc-sx99) (#257)
* docs(positioning): add assurance profile for agent factory rigor * docs(positioning): frame goals as reconcile setpoints * chore(scripts): suppress SC2034 on bd_out — set by run_capture via name-ref Drive-by fix needed to push crank/soc-sx99 — pre-push shellcheck flagged bd_out as unused in test-rpi-surface-smoke.sh, but it is set indirectly by run_capture's name-ref pattern. Adds a targeted shellcheck disable comment. |
||
|
Boden Fuller
|
60d7463e2c |
docs: align index.md hero and problem section to three-layer model
Replace "four operational layers" table (Bookkeeping/Validation/Primitives/ Flows) with three product layers (Context Compiler, Validation Gates, Knowledge Flywheel). Update hero tagline, mermaid diagram, and architecture card description to match README and PRODUCT.md. |
||
|
Boden Fuller
|
80f53fb028 |
feat(eval): add context_comprehension dimension, CDLC identity, and observability feedback loop
Reframe AgentOps as a "context compiler" across README, docs/index.md, and PRODUCT.md — replacing "operational discipline" / "local operating layer" with context-first language aligned to the Context Development Life Cycle (CDLC). Add context_comprehension eval dimension (schema + Go types + validation) with a deterministic eval suite and shell fixture that scores SKILL.md structural quality (steps, flags, examples, output spec, length). Add SkillLoadEvent to the citation pipeline so ao inject --for=<skill> records a skill_loaded CitationEvent via ratchet.RecordCitation, closing the gap between "what context was loaded" and "how the session went." Wire quality-signal corrections from hooks/quality-signals.sh into the flywheel close-loop so user corrections reduce utility of loaded skills, completing the observe → adapt feedback loop. Ref: soc-hsef, Debois CDLC talk (AI Engineer 2026) |
||
|
Boden Fuller
|
f382d42bc3 | docs: clarify AgentOps golden paths | ||
|
Boden Fuller
|
39477a9533 | feat(onboarding): unify repo seed golden path | ||
|
Boden Fuller
|
342a8fc010 | release: restore prep state and plan zero-trust gate | ||
|
Boden Fuller
|
82e9cacc2a |
Merge branch 'evolve/prep-2026-04-30' into main
# Conflicts: # .agents/ao/last-processed # .agents/findings/registry.jsonl # .agents/learnings/2026-04-07-v2.35.0-release-postmortem.md # .agents/learnings/2026-04-19-orchestrator-compression-anti-pattern.md # .agents/learnings/2026-04-27-ci-contract-scanners-need-syntax-parity.md # .agents/patterns/pre-tag-ci-validation.md # .agents/rpi/execution-packet.json # .agents/rpi/next-work.jsonl # PRODUCT.md # README.md # docs/index.md # skills-codex/.agentops-manifest.json # skills-codex/crank/.agentops-generated.json # skills-codex/evolve/.agentops-generated.json # skills-codex/implement/.agentops-generated.json # skills-codex/plan/.agentops-generated.json # skills-codex/rpi/.agentops-generated.json # skills-codex/swarm/.agentops-generated.json # skills/plan/references/plan-document-template.md |
||
|
Boden Fuller
|
c2099fc364 | fix(codex): make closeout dirty-safe | ||
|
Bo
|
2648e57a41 |
docs: voice + positioning — DevOps for the agent (#192)
* docs: voice + positioning — DevOps for the agent
Aligns the README and mkdocs landing page to the showcase's voice
(12factoragentops.com) and the explicit DevOps positioning. The
showcase site says "DevOps for the agent" — the repo should sing
the same song.
Critical changes:
• README H2: "Coding agents don't do their own bookkeeping."
→ "DevOps for the agent." (the brand line)
• Lifts "The point is not a bigger prompt. The point is a repo
that remembers what worked." (was buried at line 184) into
the hero block. Strongest sentence in the repo, surfaced first.
• Drops "context compiler" jargon from the public README opener.
The framing belongs in PRODUCT.md / ARCHITECTURE.md, not the
first-impression surface.
• New "Why DevOps?" section maps the DevOps Three Ways
(Flow / Feedback / Continual Learning) to the four AgentOps
layers (Primitives+Flows / Validation / Bookkeeping). Cites
docs/the-science.md and docs/brownian-ratchet.md. Closing
line: "DevOps is what made software ship. AgentOps is what
makes coding agents compound. Same shape, new substrate."
• New "Proof: the three-gap contract" subsection surfaces
Judgment / Durable Learning / Loop Closure, previously hidden
in PRODUCT.md only. Closes the doctrine-to-product gap.
• "How AgentOps Fits With Other Tools" → "Competitive
Positioning" with sharper one-line lead: "Most tools optimize
work within a session. AgentOps compounds across them."
• New "Ready?" footer before Contributing — 3-step CTA in a
code block (install / quick-start / validate).
• Cross-runtime block: 37-word run-on collapsed to four short
sentences leading with "Multi-runtime, one workflow."
• Local-state framing flipped from negative
("There is no telemetry or cloud service requirement")
to positive ownership
("All state lives in local .agents/ — auditable, versionable,
yours. Zero telemetry. Zero cloud dependency.").
mkdocs landing page (docs/index.md):
• Hero tagline now leads with **DevOps for the agent.** and
names the four tiers in one sentence (was: "operational layer
that makes every session start where the last one left off").
• "The primary use case" → "The Problem". Imperative noun.
• 4-sentence narrative setup collapsed to 2 sentences leading
with "Every agent session starts from zero. Same mistakes.
Same rework."
• "AgentOps fixes that. It gives coding agents four things they
don't have by default" → "AgentOps solves this with four
operational layers" (benefit-led, not feature-list).
• Skills line "Flows compose them when you want more structure."
→ "Compose flows for end-to-end cycles." (drops conditional
hedge.)
• "Advanced: Day Loop and Night Loop" → "Unsupervised Cycles"
with parallel-structure benefit headers ("Day: autonomous
improvement" / "Night: knowledge compounding"). Dream framing
flipped from negative ("never mutates source code, invokes
/rpi, or performs git operations") to positive ("Purely
bookkeeping work over .agents/ — source code stays untouched,
/rpi never fires, no git operations.").
• "Two commands that show what AgentOps actually does." →
"Two commands. Real output." (no fluff word.)
• Same local-state framing flip as README.
• New "Next steps" transition between skills and Explore — same
3-step CTA as README's "Ready?" footer, with a closing
sentence pointing at the doctrine site.
Voice rules applied throughout:
- Zero fluff intensifiers (really / very / actually / essentially
/ fundamentally / ultimately / in order to / the fact that)
- Imperative verbs lead CTAs (Install / Run / Validate / Read)
- "Your agent" not "we"
- One claim per sentence in any sentence over ~20 words
- Sections end on a CTA or a sharp claim
Verified:
- mkdocs build --strict passes (pre-existing INFO warnings on
unrelated docs untouched)
- All anchors resolve (#install, #quick-start, #why-devops,
#skills, #the-ao-cli)
- Public link targets verified (12factoragentops.com,
docs/the-science.md, docs/brownian-ratchet.md,
docs/context-lifecycle.md, docs/SKILLS.md, cli/docs/COMMANDS.md
all in this public repo)
What does NOT change:
- PRODUCT.md, GOALS.md (internal docs, correctly positioned)
- Auto-generated cli/docs/ + skills/*/SKILL.md
- docs/comparisons/ (clinical voice already right)
- Four-layer model naming + order (product contract)
- "Coding agents don't do their own bookkeeping." opener claim
(load-bearing, kept inside hero in both surfaces)
- "See It Work" demo command outputs (specific timestamps stay)
- Knowledge-flywheel mermaid diagrams (identical in both surfaces)
- mkdocs nav structure (mkdocs.yml unchanged)
* docs: lock product thesis — operational discipline + moat-as-knowledge
Per 2026-04-30 5-judge council
(.agents/council/2026-04-30-agentops-product-positioning.md) and three
user overrides that sharpened the value-prop framing:
• Mission lead noun: "operational discipline for coding agents"
(replaces "operations layer" / "control plane" / "DevOps for the
agent" — user disowned the last as too lame).
• Mission engineering claim explicit: "ship reliable code with
unreliable agents that don't remember anything."
• Mission answer: "build the knowledge and memory into the system
AND the process — a Meadows compounding system." The "AND" is
preserved verbatim — system AND process, not one or the other.
• Mission moat anchor: "the context you, your team, and your
business have earned: every landmine, every decision, every scar."
• Strategic Bet honest about AgentOps' own commoditization timeline:
"Knowledge is the moat. AgentOps isn't. Every harness — ours
included — gets absorbed into the model." Frontier vendors will
ship memory primitives, learning loops, even validation gates.
The corpus is what stays.
• AgentOps' product role named: "the bridge tool: skills, hooks,
and a CLI that smooth the sharp edges of current models so you
produce reliable output today and build the moat that stays."
Files:
PRODUCT.md
- Mission, Vision, What the Product Actually Is, Core Value Props,
Strategic Bet, Known Gaps, Design Principles all rewritten
around the new thesis. Personas, Anthropic-convergence table,
and the structural shape preserved. last_reviewed 2026-04-30.
- Six design pillars expanded: Meadows / DevOps Three Ways / SRE
(SLOs + error budgets) / Kubernetes control loops / Brownian
Ratchet / Knowledge Flywheel.
- Operational principles add "the corpus is the user's. The
harness is ours." — encodes the override into the doctrine.
- Evidence section refreshed: 320 stars (+55 in 6 days), 4940
learnings (+30x from prior snapshot), 1195 patterns, 40
planning rules, 111 codex overrides.
README.md
- H2 swapped from "DevOps for the agent." (disowned) to
"Operational discipline for coding agents."
- Opener paragraph carries the engineering claim + Meadows
compounding system + AND emphasis.
- Hero pull-quote: "The moat is the context you, your team,
and your business have earned. AgentOps is how it compounds."
- "Why DevOps?" section gets a new closing blockquote naming
AgentOps' own commoditization timeline and pointing at
PRODUCT.md for the full thesis.
docs/index.md (mkdocs landing)
- Hero matches README: same H2 wording, same engineering claim,
same moat sub-tagline. Description meta updated.
.agents/council/2026-04-30-agentops-product-positioning.md
- Council artifact appended with three User Override sections
(#1 value-prop reshape, #2 Meadows compounding, #3 AgentOps
commoditization) plus the final approved Mission and Strategic
Bet paragraphs and a propagation map for downstream surfaces.
Build: mkdocs --strict passes.
Showcase repo (agentops-showcase) propagation: pending — separate
commit on the showcase side mirrors these paragraphs.
* fix(product): drop broken .agents/council link
.agents/ is gitignored on this repo, so the council artifact is
local-only — not in the repo tree. The PRODUCT.md 'See Also' link
broke CI's link-validation gate. Removed the link and reframed the
Known Gaps row to reference the council without the path.
Council artifact still exists locally at
.agents/council/2026-04-30-agentops-product-positioning.md for the
maintainer's working notes; it just doesn't get a public link.
|
||
|
Boden Fuller
|
9d802a122e |
fix(docs): restore docs/index.md as MkDocs landing page
Commit
|
||
|
Bo
|
8e0da39d61 | Remove lowercase docs index | ||
|
Boden Fuller
|
1e073d8363 |
chore: purge archived AO↔Olympus bridge integration + prefer local Go in precommit hook
Olympus (ol) was the power-user daemon predecessor to AgentOps, archived in strategic-direction.md. The bridge contracts (SPEC_ONLY, never enforced), MemRL policy surface, OL quarantine constraints collector, and supporting scripts/tests all referenced a now-dead integration. Purging them removes ~2400 lines of stale surface area. ## Deleted files - docs/ol-bridge-contracts.md - docs/architecture/ao-olympus-ownership-matrix.md - docs/plans/2026-02-13-ao-olympus-bridge-next-steps.md - docs/contracts/memrl-policy-integration.md - docs/contracts/memrl-policy.schema.json - docs/contracts/memrl-policy.profile.example.json - cli/cmd/ao/inject_ol_test.go - skills/vibe/scripts/ol-validate.sh + codex mirror - skills-codex/swarm/scripts/ol-ratchet.sh, ol-wave-loader.sh - tests/ol-integration/ (entire directory) ## CLI code stripped - internal/search/types.go: OLConstraint struct + InjectedKnowledge.OLConstraints field - internal/search/inject_run.go: CollectOLConstraints, WriteConstraintsSection, quarantineRelPath const, all related trim/render logic - cmd/ao/inject.go: gatherOLConstraints, collectOLConstraints wrapper, olConstraint type alias, init-time call site - Package comments in provenance/storage/types/formatter updated "olympus" → "agentops" - formatter/markdown.go: session tag "olympus" → "agentops" (+ test update) - Tests: deleted TestCollectOLConstraints + TestInject_collectOLConstraints, stripped OL subtests from TestFormatKnowledgeMarkdown and TestInject_*, renamed "olympus" literal test data to "other-repo" - rpi_phased_context.go: stripped "matches Olympus DefaultTimeout" and "Modeled on Olympus internal/git/worktree.go" comments ## Docs + skills stripped - mkdocs.yml nav: 3 entries removed (AO-Olympus Matrix, MemRL Policy, OL-AO Bridge) - docs/INDEX.md, contracts/index.md, architecture/index.md, index.md: cross-refs removed - strategic-direction.md: retirement rationale compressed to one paragraph - docs/context-packet.md, positioning/devops-for-vibe-coding.md, plans/README.md: OL-specific content removed - skills/vibe/SKILL.md + codex mirror, swarm/SKILL.md: OL script refs removed - skills/vibe/references/deep-checks.md, plan/references/planning-rules.md (+ codex), pre-mortem/references/council-fail-patterns.md (+ codex): OL rule/pattern entries removed - skills-codex hashes regenerated (plan, pre-mortem, swarm, vibe) ## Precommit hook fix - hooks/go-test-precommit.sh: prefer ~/.local/go/bin/go when present. Hooks don't inherit interactive-shell PATH, so apt-provided go-1.22 would otherwise override a user-local 1.26 install. Mirrors the zshrc pattern. ## Retained (historical / useful) - strategic-direction.md: 1-paragraph archival note - Historical release notes (docs/releases/*.md) — immutable past-release record - cli/testdata/transcripts/real-2.4mb.jsonl — captured test fixture - docs/brownian-ratchet.md ol-rg3p bead-ID refs — internal bead prefix, not Olympus ## Verification - go build ./... && go vet ./... clean - go test ./... clean except pre-existing TestGCBridgeVersion_Live panic - scripts/docs-build.sh --check (mkdocs strict) clean - scripts/check-contract-compatibility.sh passes - scripts/regen-codex-hashes.sh run — 4 skills updated |
||
|
Boden Fuller
|
3425393dc2 |
docs(landing): lead with primary use case + headline skills table
Previous landing was too abstract ("operational layer") and buried the
skills behind a catalog link. Rewrite to:
## docs/index.md
- Open with the concrete problem: "Coding agents don't do their own
bookkeeping" → session 15 rediscovers session 1's lessons without
AgentOps
- Add "The primary use case" section with the 4-layer table (bookkeeping,
validation, primitives, flows) and the flywheel diagram
- Add "See It Work" section with actual terminal examples of /council
and /rpi so readers see what the system does, not just what it is
- Add "The headline skills" table with 9 skills + "use it when" framing
(matches README.md)
- Add "Advanced: Day Loop and Night Loop" explaining /evolve and /dream
- Tabbed install blocks for Claude Code / Codex / OpenCode + ao CLI
## docs/_hooks/gen_skill_pages.py — skills/index.md generator
- Replace generic "Featured Workflows" with the same 9-skill headline
table + use-case framing (consistent with landing and README)
- Reorganize complete catalog into 8 family groups (Validation, Flows,
Bookkeeping, Session, Product, Utility, Platform, PR workflow) so
readers can navigate 69 skills by purpose instead of alphabet
- "Related references" card block moved to the bottom
Both pages now answer "what is this and which skills do I try first"
before linking to the exhaustive catalog.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
Boden Fuller
|
cc6750c4e8 |
feat(docs,skills): rebuild Pages site with MkDocs Material + harden RPI orchestrator delegation contract
## 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>
|