skills/boshu2__agentops
1
0
Fork 0
mirror of https://github.com/boshu2/agentops.git synced 2026-09-14 15:08:13 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
ao-pre-reduction@5b334a13f
boshu2__agentops/docs/newcomer-guide.md
T
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
2026-06-03 20:44:06 -04:00

5.6 KiB
Raw Permalink Blame History

Newcomer Guide: Understanding the AgentOps Repo

If you're new to this repository, this guide gives you a practical mental model, a map of where things live, and a fast path to becoming productive.

What this repo is

AgentOps is the operational layer for coding agents: a skills + CLI system that provides bookkeeping, validation, primitives, and flows so sessions compound instead of restarting from zero. (AgentOps 3.0 is hookless by default — CI is the authoritative gate; hooks are an opt-in surface you author yourself.)

At a high level:

  1. Run primitives and flows with skills (/research, /implement, /validation, /rpi)
  2. Persist bookkeeping in .agents/
  3. Inject the best prior learnings into the next session
  4. Enforce quality through CI gates (AgentOps 3.0 is hookless — CI is the authoritative gate; hooks are opt-in)

See also:

Repo structure (what matters most)

Think in four layers:

  1. Product/docs layer — docs/ + selected repo-root entrypoints such as README.md, CHANGELOG.md, GOALS.md, and PRODUCT.md
  2. Skills layer — skills/, checked-in skills-codex/, and skills-codex-overrides/ (SKILL.md contracts + per-skill scripts/references + Codex-only tailoring)
  3. CLI layer — cli/ (cli/cmd/ao/, cli/internal/, generated cli/docs/COMMANDS.md)
  4. Validation layer — scripts/, tests/, and .github/workflows/validate.yml (CI is the authoritative gate; AgentOps 3.0 ships no hooks)

Source-of-truth precedence

When docs disagree, follow this order:

  1. Executable code + generated artifacts (cli/**, scripts/**, cli/docs/COMMANDS.md)
  2. Skill contracts/manifests (skills/**/SKILL.md, schemas/**)
  3. Explanatory docs (docs/**, README.md)

For Codex skills specifically:

  1. skills/<name>/SKILL.md is the canonical behavior contract
  2. skills-codex-overrides/<name>/ is the Codex-specific tailoring layer
  3. skills-codex-overrides/catalog.json records the Codex treatment decision for every skill
  4. skills-codex/<name>/ is the checked-in Codex runtime artifact

For the core Codex execution chain, skills-codex-overrides/catalog.json also stores machine-readable operator_contract markers. When you change one of those prompts, update the contract alongside the prose so the validator can enforce the intended Codex-specific guarantees. After Codex prompt/artifact changes, run bash scripts/refresh-codex-artifacts.sh --scope worktree so hash refresh and Codex-specific validators follow one obvious repair path.

Key concepts to learn first

1) Context quality is the core design principle

The architecture assumes output quality depends on input context quality. Most patterns in this repo are about context scoping, isolation, and compounding.

2) Skills are composable primitives and flows

Use the router in Skills Reference to choose the right entry point:

  • Start with uncertainty: /research
  • Break work into issues: /plan
  • Implement one issue: /implement
  • Run multi-issue waves: /crank
  • Run end-to-end lifecycle: /rpi

3) Hooks are opt-in, not a default

AgentOps 3.0 ships zero hooks; nothing auto-injects or runs at session boundaries. CI (.github/workflows/validate.yml) is the authoritative gate. If you want a bounded local gate of your own, author one with the hooks-authoring skill — AgentOps does not ship one.

4) CLI docs are generated, not hand-maintained

cli/docs/COMMANDS.md is generated. If command behavior changes, regenerate docs and keep parity checks passing.

5) CI checks many non-code contracts

CI validates not just builds/tests but also docs parity, skill integrity/schema, security scans, and contract compatibility.

Suggested learning path

Day 1 reading order

  1. README.md
  2. docs/documentation-index.md
  3. docs/how-it-works.md
  4. docs/ARCHITECTURE.md
  5. docs/SKILLS.md

Then pick one domain

  • CLI behavior: cli/cmd/ao/, cli/internal/, cli/docs/COMMANDS.md
  • Skill behavior: skills/<name>/SKILL.md
  • Opt-in hooks: skills/hooks-authoring/ (AgentOps ships none by default)
  • Validation/release/security: scripts/*.sh + tests/ + .github/workflows/validate.yml

Recommended first contributions

  1. Docs-only fix (safe): update wording or cross-links and run docs validation scripts.
  2. Skill/docs parity fix (medium): update docs to match a SKILL.md change and validate parity.
  3. Small CLI command improvement (advanced beginner): update command behavior, regenerate CLI docs, and run CLI checks.

Practical tips

  • Run the local gate before pushing: bash scripts/pre-push-gate.sh --fast (smart conditional gate that only checks what changed).
  • Trust runtime files over narrative docs when there is a mismatch.
  • Keep changes small and verify with local gates before pushing.
  • Treat .agents/ as a first-class part of the system behavior.
  • Treat Codex as a first-class runtime: when a skill change affects Codex UX or execution style, inspect skills-codex-overrides/, update skills-codex-overrides/catalog.json if treatment changes, update the checked-in skills-codex/ copy when needed, and run the Codex validation scripts.
  • If you touch command surfaces or skill contracts, expect related parity checks to fail until updated.

Where to go next

Reference in New Issue View Git Blame Copy Permalink