mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
Bo
2207c5b278
> **Review findings closed.** The re-check's residue (`perl -pibak` bundled-cluster bypass) is applied in `2675bb383`: the perl alternation accepts any non-space run after the in-place flag, a new FIRE bats proves the deny, 48/48 policy-dispatch bats green, codex twins regenerated. Merging on Bo's instruction. ## What Five semantic lanes from the 2026-08-23 estate audit, each implemented in an isolated worktree and independently validated by a fresh context, plus one integration-fixup commit. **1. Goals: the zero-denominator green is dead** (`estate/goals-honest`) `GOALS.md` lost its Gates table in the 07-14 cut, so `ao goals validate` reported `Valid: true` with `GoalCount: 0` in the release smoke on every push. Now: zero parsed goals ⇒ `Valid: false` with an actionable error (RED test first); `GOALS.md` carries a real 6-row Gates table whose every `Check` was executed via `ao goals measure` before shipping; `goals-affects-files.yaml` pruned of dead ids; the smoke asserts `goal_count ≥ 1`. Two of the eight fitness properties (behavior-before-activity, stop-boundary) have no executable check yet — disclosed in GOALS.md rather than faked. **2. Front door: the contract file gets a map** (`estate/front-door`) `AGENTS.md` had zero build/test commands and zero layout — the Go mechanics lived only in `.claude/rules/go.md`, which Codex (the declared default runtime) never loads. Added a terse "Repository map and mechanics" section; compressed the architecture-poetry opener to plain language; README opens with what-it-does, the maintainer binary install moved to `docs/install-day2-ops.md`, and the quickstart now ends with an invitation to open an issue with your verdict. Deleted the dead `.claude/CLAUDE-base.md` + `build-claude.py` pipeline (zero consumers since June). `CLAUDE.md` remains a symlink to `AGENTS.md`. **3. Hooks: first policy that guards the user's invariant** (`estate/hooks-invariant`) All four shipped policies guarded this repo's own artifacts. New `core.verdicts:hand-edit` denies Edit/Write/Bash hand-writes into `.agents/ao/verdicts/**` — verdicts are content-addressed evidence written only by the validate flow. RED committed before GREEN (`d264682c0`); bats prove deny on hand-writes and allow on reads, intents, and the sanctioned `validate.py` writer. The lane shipped with in-place editors disclosed as un-matched; the cross-family review treated that as a blocker and the gap is closed in this PR (see below). **4. bdd-foundry stops instructing dead commands** (`estate/workflows-fix`) The R4 phase told agents to run `ao yield emit`; Phase 5 said pull holdouts via `ao scenario`; comments cited `ao membrane derive-checks` — all tombstoned, so R4 failed on every run. Emission is dropped per the tombstone's guidance (observation stays in the workflow result), Phase 5 grades in-run ground truth plus any caller-supplied register scenarios, and the lane's initially-overreaching "there is no external holdout register" wording was caught by its validator and corrected in integration. Bonus: `workflow-scripts-syntax.yml` globbed the gitignored `.claude/workflows/` (matched nothing in CI since inception) — now checks the tracked `workflows/` tree. **5. Docs honesty: retired vocabulary stops reading as live** (`estate/docs-honesty`) `intel_scope` removed from all 24 source SKILL.md + fixture + template + tutorial (declared by half the corpus, read by zero Go); the schema keeps accepting it for old-shape third-party skills but now self-describes as deprecated. `docs/SKILL-API.md` no longer presents `INTEL`/flywheel/forge/push/ratchet as live. `docs/knowledge-flywheel.md` states design-vs-implemented truthfully. ADR-0014's dead link fixed. 25 drifted `images/gemini/skills/` copies re-synced byte-identical per that bundle's own README contract. All codex projections regenerated once at integration (`regen-all.sh --check` passes). ## Evidence - `cd cli && go test ./...` exit 0 · 4 skill validators PASS · `policy-dispatch.bats` + `cross-runtime-hook-baseline.bats` PASS · `check-doc-hooks-drift` + `check-hookless-cold-start` PASS · `validate-goal-count` PASS · `node --check` on all 8 workflow scripts PASS · `regen-all.sh --check` PASS - From repo root: `ao goals validate --json` → `valid: true, goal_count: 6`; from a wrong cwd it now fails closed instead of reporting green. - Each lane branch carries its own commits; merge commits preserve the lane structure. Fresh per-lane validators re-ran every suite themselves; the one FAIL each (workflows wording, cross-lane doc fallout) was fixed in the integration commit, not waived. ## Cross-family review (Codex, fresh context) First pass: **FAIL** with one blocker — the new verdict guard explicitly excluded in-place editors, so `sed -i` silently mutated digest-named evidence (dispatcher probe returned exit 0). Repaired in `f53945c26` (one bounded round): three FIRE bats observed RED before the matcher landed (in-place sed, in-place perl, file deletion), two negative bats prove reads never fire; policy rationale and SKILL.md updated; codex twins regenerated; 47/47 bats green. Everything else in the first pass was affirmed (goals behavior, symlink/build bar, zero retired verbs in workflows, byte-identical gemini copies, current projections). Focused re-check: blocker confirmed closed via the dispatcher probe; one regex corner (`perl -pibak`, header note above) stopped the loop under the spiral rule. ## Follow-ups (not in this PR) - `workflows/bdd-foundry.js` `SKILL` constant points at `skills/behavior-first-planning/SKILL.md`, which was retired in v3.3 — every phase prompt references a dead path (pre-existing). Needs a design call: restore the phase discipline inline or repoint honestly. - Verdict-guard: the noclobber override redirect (`>|`) remains the one disclosed unmatched write shape. - `docs/UPGRADING.md` note for third parties still declaring `intel_scope` (schema accepts, nothing reads).
4.5 KiB
4.5 KiB
Create Your First Skill
AgentOps is built out of skills. A good first contribution is not "make a huge framework." It is "teach the system one reusable intent."
This guide shows the smallest current path to adding a new skill without tripping the repo gates.
Before You Start
Pick a skill idea that is:
- Narrow: one clear job, not an entire workflow
- Reusable: something you would invoke more than once
- Observable: it should produce an artifact, decision, or validation step someone can check
Good first-skill ideas:
- A focused validator for one common failure mode
- A domain-specific research or triage helper
- A contribution helper for one external tool or service
- A narrow knowledge-management skill that transforms one artifact type into another
Avoid first-skill ideas that:
- duplicate an existing skill in
docs/SKILLS.md - require a big new runtime abstraction
- mix discovery, implementation, and release into one entrypoint
The Minimum Shape
Create a directory:
mkdir -p skills/your-skill-name
Then create skills/your-skill-name/SKILL.md using the current frontmatter contract:
---
name: your-skill-name
description: 'What this skill does. Triggers: "trigger phrase", "other phrase".'
skill_api_version: 1
context:
window: fork
intent:
mode: task
sections:
exclude: [HISTORY]
metadata:
tier: execution
---
# your-skill-name
## Purpose
What this skill is for and what problem it solves.
## When to Use
- Trigger condition one
- Trigger condition two
## Inputs
- What the user should provide
- Any repo or runtime assumptions
## Instructions
1. The first concrete step.
2. The main execution flow.
3. The validation or closeout step.
## Output
- What artifact, decision, or side effect this skill should produce
## Examples
```text
Example prompt or invocation
Use [templates/skill.template.md](templates/skill.template.md) as a starting point if you want a copyable scaffold.
## Pick The Right Tier
Most first contributions should use one of these:
- `execution`: a focused task skill
- `session`: onboarding, status, or recovery help
- `knowledge`: transforms or traces knowledge artifacts
- `product`: product, docs, or release oriented
- `contribute`: contribution-specific workflow support
See [SKILL-API.md](SKILL-API.md) for the full frontmatter contract and [../skills/SKILL-TIERS.md](https://github.com/boshu2/agentops/blob/main/skills/SKILL-TIERS.md) for the full taxonomy.
## Keep The Entry Point Lean
Your `SKILL.md` should be the operator surface, not the whole encyclopedia.
If the skill needs more detail, add:
- `references/*.md` for deeper guidance
- `scripts/*.sh` for helper logic or validation
- `schemas/*.json` only when downstream tooling consumes a structured contract
If you add files under `references/`, make sure `SKILL.md` links to them. CI fails when reference files exist but are not linked.
## Common CI Footguns
These are the most common ways first skill PRs fail:
- Missing or stale frontmatter
- New references not linked from `SKILL.md`
- Adding a skill directory without syncing counts
- Leaving `TODO` or `FIXME` text in `SKILL.md`
- Adding symlinks anywhere in the repo
This repo is strict because skills are shipped artifacts, not informal notes.
## Validate Before You Open A PR
Run the current local checks:
```bash
# Required for any skill change
bash skills/skill-builder/scripts/heal.sh --strict
# Required when docs or skill counts change
bash tests/docs/validate-doc-release.sh
# If you added or removed a skill directory
python3 scripts/generate-skill-mesh.py
# Recommended fast changed-surface check
ao gate check --fast --scope worktree
If your change affects Codex behavior or the checked-in Codex bundle, also run:
bash scripts/audit-codex-parity.sh --skill your-skill-name
bash scripts/validate-codex-generated-artifacts.sh --scope worktree
Where To Look For Good Examples
Start from a simple, high-signal skill rather than the biggest orchestration layer.
Useful examples:
Opening The PR
Explain four things clearly:
- the user intent the skill handles
- why an existing skill was not enough
- what artifact or outcome it produces
- what checks you ran locally
Useful supporting docs: