Standards

Standards Skill

Language-specific coding standards loaded on-demand by other skills.

Purpose

This is a library skill - it doesn't run standalone but provides standards references that other skills load based on file types being processed.

Standards Available

How It Works

Skills declare standards as a dependency:

skills:
  - standards

Then load the appropriate reference based on file type:

# Pseudo-code for standard loading
if file.endswith('.py'):
    load('standards/references/python.md')
elif file.endswith('.go'):
    load('standards/references/go.md')
elif file.endswith('.rs'):
    load('standards/references/rust.md')
# etc.

Domain-Specific Checklists

Specialized checklists for high-risk code patterns. Loaded automatically by /validate and /pre-mortem when matching code patterns are detected:

Skills detect triggers via file content patterns and import statements. Each checklist's "When to Apply" section defines exact detection rules.

Deep Standards

For comprehensive audits, skills can load extended standards from vibe/references/*-standards.md which contain full compliance catalogs.

Integration

Skills that use standards:

• /validate - Loads based on changed file types
• /implement - Loads for files being modified
• /review - Loads for change-quality and blast-radius checks
• /doc - Loads markdown standards
• /review - Loads for root cause analysis
• /refactor - Loads for refactoring recommendations

Examples

Vibe Loads Python Standards

User says: /validate (detects changed Python files)

What happens: 1. Vibe skill checks git diff for file types 2. Vibe finds auth.py in changeset 3. Vibe loads standards/references/python.md automatically 4. Vibe validates against Python standards (type hints, docstrings, error handling) 5. Vibe reports findings with standard references

Result: Python code validated against language-specific standards without manual reference loading.

Implement Loads Go Standards

User says: /implement ag-xyz-123 (issue modifies Go files)

What happens: 1. Implement skill reads issue metadata to identify file targets 2. Implement finds server.go in implementation scope 3. Implement loads standards/references/go.md for context 4. Implement writes code following Go standards (error handling, naming, package structure) 5. Implement validates output against loaded standards before committing

Result: Go code generated conforming to standards, reducing post-implementation vibe findings.

Troubleshooting

Reference Documents

• references/architecture-terms.md
• references/common-standards.md
• references/behavioral-discipline.md
• references/examples-troubleshooting-template.md
• references/cli-wireup-template.md — Reproducible cobra subcommand template (noun + verb, injectable Options, ~10 min/cycle)
• references/go.md
• references/json.md
• references/markdown.md
• references/python.md
• references/rust.md
• references/shell.md
• references/skill-structure.md
• references/standards-index.md
• references/typescript.md
• references/javascript.md
• references/sql-safety-checklist.md
• references/llm-trust-boundary-checklist.md
• references/race-condition-checklist.md
• references/codex-skill.md
• references/test-pyramid.md
• references/yaml.md
• references/skill-tier-caps.md
• references/external-source-attribution.md

Architecture Terms (Ubiquitous-Language Register)

This file is the canonical register for the DDD/Hexagonal vocabulary AgentOps uses. It complements PRACTICE-REGISTRY.md, which owns practice slugs rather than architecture terms. Every skill, hook, schema, and CLI command that names one of these concepts MUST use the term as defined here. New terms are appended; existing entries are revised in place rather than renamed. Citations point to the source work that named the concept (Author Year) or to a canonical AgentOps doctrine surface. Code anchors are relative-path links; some anchors point at files scheduled by later waves of the DDD+Hexagonal v1 plan and may not yet exist on disk — that is intentional forward referencing.

Aggregate / Aggregate Root

Aggregate / Aggregate Root — Evans, Domain-Driven Design, 2003 (Part II, ch. 6). An aggregate is a cluster of domain objects treated as a single unit for the purpose of invariant enforcement and persistence; the aggregate root is the one entity outside collaborators are allowed to reference, and it gate-keeps every mutation so the aggregate's invariants hold at every transaction boundary. In AgentOps v1, ExecutionPacket is the sole aggregate root — phase transitions, attempt history, and verdict assignment all flow through it so that "a packet is always in a legal phase with a consistent attempt graph" remains invariant. Anchor: `../../../cli/internal/domain/packet/aggregate.go` (created in Wave 1 #6).

Bounded Context

Bounded Context — Evans, Domain-Driven Design, 2003 (Part IV, ch. 14). A bounded context is an explicit boundary inside which a single model and its ubiquitous language apply consistently; outside the boundary the same words may mean different things, and translation is required at the seam. In AgentOps each skill directory under skills/<name>/ is treated as one bounded context: terms like "validate", "promote", or "phase" carry skill-local meanings, and cross-skill contracts go through declared inputs/outputs rather than shared mutable state. Anchor: `../../../skills/` (each subdirectory is one context).

Ubiquitous Language

Ubiquitous Language — Evans, Domain-Driven Design, 2003 (Part I, ch. 2). A ubiquitous language is a vocabulary deliberately shared between domain experts and code so that the same words name the same concepts in conversation, documentation, and source — eliminating the translation layer that otherwise rots requirements. AgentOps maintains its ubiquitous language as two coupled registries: the practice-slug registry at `../../../PRACTICE-REGISTRY.md` for cross-era practice names, and this file for DDD/Hexagonal architectural terms. Anchor: `../../../PRACTICE-REGISTRY.md` — the slug registry section.

Port / Adapter

Port / Adapter — Cockburn, "Hexagonal architecture" (alistair.cockburn.us), 2005. In hexagonal architecture a port is a domain-defined interface describing one kind of conversation the application can have with the outside world; an adapter is the concrete implementation of that conversation against a specific technology. Ports come in two flavors: primary (driving) ports are called by outside actors (CLI, HTTP, test harness) to invoke the domain, while secondary (driven) ports are called by the domain to reach external systems (storage, Git, LLM, beads). In AgentOps the PacketRepository, ClaimEmitter, and EvaluatorBus interfaces are secondary ports; the ao CLI commands are primary adapters that drive those ports. Anchor: `../../../cli/internal/ports/` (created in Wave 1 #6).

Anti-Corruption Layer (ACL)

Anti-Corruption Layer (ACL) — Evans, Domain-Driven Design, 2003 (Part IV, ch. 14, "Anticorruption Layer" pattern). An anti-corruption layer is a translating boundary placed between our model and a foreign model (legacy system, third-party API, vendor SDK) so that the foreign model's vocabulary and assumptions cannot leak into and corrupt our domain — concretely, the ACL exposes a clean port-shaped interface to our side and absorbs all the impedance-matching work on the other. AgentOps plans ACLs at every external seam: Git operations (commit, branch, push), LLM provider calls (Anthropic / OpenAI / local), and beads issue-tracker integration each get their own translator so the domain layer never imports git, anthropic, or bd types directly. Anchor: `../../../cli/internal/adapters/` — each subdirectory (git/, llm/, beads/) is one ACL (created in Wave 2).

Context Map

Context Map — Evans, Domain-Driven Design, 2003 (Part IV, ch. 14, "Context Map" pattern). A context map is a diagram (and/or document) that enumerates every bounded context in the system, names them, and labels the relationship between each pair — shared kernel, customer/supplier, conformist, anti-corruption layer, separate ways, open-host service, published language. AgentOps generates its context map programmatically from skill frontmatter (hexagonal_role, consumes, produces, context_rel) so the map stays in sync with code rather than drifting into wishful documentation. Anchor: `../../../docs/contracts/context-map.md` (auto-generated in Wave 2 #4).

Invariant

Invariant — Meyer, Object-Oriented Software Construction, 1988/1997 (Design by Contract: preconditions, postconditions, class invariants). An invariant is a predicate that must hold over an object's observable state at every stable point — after construction, before and after every public method, and across the boundaries of any operation that exposes the object to other code. In AgentOps the ExecutionPacket aggregate carries explicit invariants — phase ∈ a legal set, attempt sequence is monotonically numbered, verdict is set iff phase is terminal, citations reference resolvable artifacts — and each is enforced inside the aggregate rather than scattered through callers. Anchor: `../../../cli/internal/domain/packet/invariants.go` (created in Wave 1 #6).

Tracer Bullet

Tracer Bullet — Hunt & Thomas, The Pragmatic Programmer, 1999 (Topic 11, "Tracer Bullets"). A tracer bullet is a thin end-to-end slice of working functionality built early to validate the architectural path under realistic load before thickening any layer — the slice goes from outermost input to outermost output, all the seams light up, and you adjust aim from feedback rather than from a paper plan. AgentOps's DDD+Hexagonal v1 picked ExecutionPacket as its tracer aggregate: one aggregate, one set of ports, one set of adapters, historically exercised end-to-end through the retired RPI CLI and now through the operating loop plus cli/internal/rpi tests; only after that path is green do other types (claims, verdicts, briefings) get migrated into the hexagonal seam. Anchor: `../../../cli/internal/rpi/execution_packet.go` — the current ExecutionPacket source, which the v1 slice will alias and re-home through the new domain package.

Behavioral Discipline for Agentic Work

Purpose: Reduce common agent failure modes during implementation and review. Use this alongside language standards, not instead of them.

When to Apply

Apply this reference for:

• non-trivial /implement, /review, /validate, and /pre-mortem work
• ambiguous requests where different interpretations would change the solution
• agent-authored diffs, broad refactors, or any task with blast-radius risk

1. Think Before Coding

Do not silently pick an interpretation and run with it.

• State the task in your own words before editing.
• Name assumptions that materially affect the solution.
• If two reasonable interpretations lead to different code, ask or present options.
• Surface tradeoffs when the requested path looks heavier than necessary.
• Stop when repo reality contradicts the prompt. Resolve the mismatch first.

AgentOps Translation

• Check whether the capability already exists before proposing or building it.
• Prefer runtime truth (cli/**, hooks/**, scripts/**, generated docs) over memory or explanatory docs.
• If a simpler file boundary exists, choose it and explain why.

2. Simplicity First

Choose the smallest change that satisfies the request.

• Reuse existing helpers, commands, hooks, and patterns before adding new ones.
• Do not add configurability, abstractions, or extension points without a present requirement.
• Do not build a framework for a one-off need.
• Do not add defensive branches for impossible or unobserved scenarios just to look thorough.
• If the patch keeps growing, pause and ask whether there is a smaller cut.

Quick Test

Would a senior engineer call this solution obviously larger than the problem? If yes, simplify.

3. Surgical Changes

Keep the blast radius tight.

• Define what files or surfaces are in scope before editing.
• Every changed line should map to the request, acceptance criteria, or cleanup made necessary by your change.
• Do not fold in adjacent refactors, formatting passes, or comment rewrites unless they are required.
• Match local style and structure unless the task explicitly includes a style correction.
• Only remove dead code or imports that your own change made obsolete.
• If you find an unrelated problem, record it separately instead of bundling it into the patch.

AgentOps Translation

• If unrelated follow-up work appears, create a bead instead of smuggling the fix into the current change.
• Avoid touching generated or mirrored artifacts unless the workflow requires it.

4. Goal-Driven Execution

Turn requests into verifiable outcomes.

• Rewrite the task as success criteria before editing.
• Prefer evidence: tests, smoke commands, parity checks, schema validation, or focused diffs.
• For multi-step work, pair each step with a verification check.
• Do not claim completion without the evidence that matches the requested outcome.
• If validation could not be run, say so explicitly and explain the gap.

AgentOps Translation

• "Fix the CLI bug" becomes "add a reproducer, patch it, run the targeted test."
• "Improve this skill" becomes "update the contract, validate skill integrity, then check the shipped runtime copy."
• "Clean up the hook" becomes "preserve the contract, edit only the required files, then run the hook/doc parity gate."

Before/After Examples

Example 1: Hidden Assumptions

Request: "Make search faster"

Before

• picks one meaning of "faster" without clarifying
• adds caching, async work, and new knobs all at once
• verifies only that the code still runs

After

• asks whether "faster" means latency, throughput, or perceived speed
• picks the smallest change that matches the answer
• verifies against the metric that actually mattered

Example 2: Overbuilt Solution

Request: "Add a discount helper"

Before

• introduces strategies, factories, and extension points for a one-off need
• adds flexibility nobody asked for

After

• starts with a small helper that solves the current requirement
• defers abstraction until a real second use case exists

Example 3: Drive-By Editing

Request: "Fix empty emails crashing the validator"

Before

• rewrites adjacent validation logic
• edits comments and formatting unrelated to the bug
• leaves a large diff for a narrow request

After

• adds a reproducer for the empty-email case
• fixes only the email path plus cleanup caused by that fix
• records unrelated cleanup separately instead of bundling it into the patch

Example 4: Weak Proof

Request: "Improve this AgentOps skill"

Before

• edits the skill doc and stops
• forgets the mirrored Codex artifact or validation step

After

• updates the shared contract and the checked-in Codex copy
• regenerates affected artifact metadata when needed
• runs the relevant validation commands before claiming completion

Review Questions

Use these four questions when validating a plan, patch, or PR:

1. What assumptions is this change making, and were they surfaced or silently chosen? 2. Could the same outcome be achieved with a smaller or more local change? 3. Does every changed line trace back to the stated goal? 4. Is the verification checking the behavior that was claimed, or only that the code compiles?

CLI Wireup Template (Go + cobra + Hexagonal Adapter)

The reproducible cycle-shape for exposing a production adapter as an ao subcommand. Empirically derived across /evolve cycles 144-146 (three ao subcommands shipped in ~10 minutes each, ~250-335 LOC including tests + docs). Captured durably here so any future port-to-subcommand slice is mechanical.

Mirror of docs/learnings/2026-05-13-cli-wiring-cycle-shape.md (canonical source). Copied per CI's no-symlinks rule so /standards-consuming agents discover it via the skill-link path.

The 3 Reference Cycles (Empirical Baseline)

8-10 minutes wall-clock, ~250-335 LOC. Adapter-side complexity dominates the variation — Loop took longer because it needed JSON slicing logic; CI was simplest because the adapter already had a clean stub-injectable shape.

The Template

// cli/cmd/ao/<noun>.go
var <noun>Cmd = &cobra.Command{
    Use:   "<noun>",
    Short: "BC<n> <surface> operations",
}

var <noun><Verb>Cmd = &cobra.Command{
    Use:   "<verb> [flags]",
    Short: "Short imperative description",
    Long:  `Long description with Examples block.`,
    RunE:  run<Noun><Verb>,
}

type <noun><Verb>Options struct {
    // flag-derived fields
    writer io.Writer
    // injectFn lets tests substitute the port without real I/O
    injectFn func(ctx context.Context, opts <noun><Verb>Options) ([]ports.X, error)
}

func init() {
    <noun>Cmd.GroupID = "core"
    rootCmd.AddCommand(<noun>Cmd)
    // flag registrations
    <noun>Cmd.AddCommand(<noun><Verb>Cmd)
}

func run<Noun><Verb>(cmd *cobra.Command, _ []string) error {
    // pull flag values, build options, delegate
    return <noun><Verb>Run(cmd.Context(), opts)
}

func <noun><Verb>Run(ctx context.Context, opts <noun><Verb>Options) error {
    if opts.writer == nil { opts.writer = os.Stdout }
    fn := opts.injectFn
    if fn == nil { fn = <noun><Verb>ViaPort }
    items, err := fn(ctx, opts)
    if err != nil { return fmt.Errorf("<noun> <verb>: %w", err) }
    enc := json.NewEncoder(opts.writer)
    for _, item := range items {
        if err := enc.Encode(item); err != nil {
            return fmt.Errorf("<noun> <verb> encode: %w", err)
        }
    }
    return nil
}

func <noun><Verb>ViaPort(ctx context.Context, opts <noun><Verb>Options) ([]ports.X, error) {
    adapter := newProduction<X>(/* construction args */)
    return adapter.<Method>(ctx, /* args */)
}

// cli/cmd/ao/<noun>_test.go
// 4-6 tests covering:
//   - stub returns N items → N lines emitted
//   - stub returns empty → 0 bytes emitted
//   - stub error → wrapped error
//   - live root (filesystem fixture) → walks correctly
//   - flag combinations (limit, range, etc.) honored

After the .go + _test.go files: scripts/generate-cli-reference.sh regenerates cli/docs/COMMANDS.md. Don't forget `generate-registry.sh` too — the cli-command-dual-generator learning documents the failure mode where one is regenerated and the other isn't.

Why This Shape Works

1. Parent noun + verb subcommands. ao loop history reads better than the flat loop-history spelling. The parent groups future subcommands (ao loop write, ao loop tail) under one verb-space. cobra handles this natively.

2. Injectable function field on Options. Production runs use the default port wrapper; tests substitute a stub. This is the same pattern cycle 117's productionCIStatus.runGH proved — refined here from a struct field to an option-bag function. Faster than fake-file-tree harnesses and platform-neutral.

3. Line-delimited JSON output. One record per line means the output composes with jq -c, head, grep, awk. Operators don't need to remember the schema; they pipe and jq '.field'.

4. Error wrapping with the command name. "<noun> <verb>: underlying error" makes debugging easy when the cobra layer surfaces an error to stderr.

5. Validate by live smoke after build. Each cycle ran make build then ./bin/ao <noun> <verb> <args> against real data. Proves end-to-end semantic correctness, not just compilation.

Anti-Patterns (Observed Across The 3 Cycles)

• Name collisions in `cli/cmd/ao`. Cycle 144's first helper was

named loadCycleHistory — collided with an existing function in metrics_health.go. go vet caught it; renamed to loadCycleHistoryViaPort. Always `grep` before naming helpers in `cli/cmd/ao` (the package is ~150 files).

• Shadowing Go builtins. Cycle 117 used cap := limit; same rule

applies to CLI helpers.

• Dead imports of `internal/ports` in test files. Cycle 144's

first test file had a dead import; go vet caught it.

• Forgetting the registry regen. scripts/generate-cli-reference.sh

is the obvious regen; scripts/generate-registry.sh is the not-obvious one. Both are required when adding a cobra.Command. See the cli-command-dual-generator learning for the failure mode.

Pre-Flight Checklist

Before writing the .go file:

# 1. Pick noun + verb. Verify no collision in cli/cmd/ao:
grep -rn "Cmd = &cobra.Command" cli/cmd/ao/ | grep -i "<noun>"

# 2. Verify helper names don't collide:
grep -rn "func <helperName>\b" cli/cmd/ao/

# 3. Confirm the port + production adapter exist:
ls cli/internal/ports/<surface>.go cli/internal/adapters/*<X>*.go

After committing:

# Regenerate BOTH:
scripts/generate-cli-reference.sh
scripts/generate-registry.sh

# Smoke test:
cd cli && make build && ./bin/ao <noun> <verb> <args>

Worked Reference Implementations

The 3 reference implementations on main:

• cli/cmd/ao/loop.go + loop_test.go — ao loop history
• cli/cmd/ao/ci.go + ci_test.go — ao ci latest/recent
• cli/cmd/ao/corpus_inject.go + corpus_inject_test.go — ao corpus inject

Read those 3 pairs before writing a new wireup; they're shorter than this template.

See Also

• docs/learnings/2026-05-13-cli-wiring-cycle-shape.md — canonical

source (this file is the skill-side mirror)

• docs/learnings/2026-05-13-bc-ports-wire-up-arc.md — the broader

14-port wire-up arc (cycle 122); historical/architecture, not a reusable template

• docs/learnings/2026-05-13-bc-ports-narrowness-postmortem.md — the

narrowness debate that preceded the wire-up

• references/go.md — Go conventions this template assumes

Codex Skill Standards

Canonical Contract

Source of truth: docs/contracts/codex-skill-api.md

Frontmatter

Codex SKILL.md frontmatter must contain only name and description:

---
name: skill-name
description: 'When this skill triggers and when it does not.'
---

Prohibited fields (Claude-internal, ignored by Codex): skill_api_version, context, metadata, allowed-tools, model, user-invocable, output_contract

Tool References

Skills must reference only tools available in Codex sessions:

Prohibited Tool References

These Claude Code primitives have no Codex equivalent and must not appear:

• TaskCreate, TaskList, TaskUpdate, TaskGet, TaskStop
• TeamCreate, TeamDelete, SendMessage
• EnterPlanMode, ExitPlanMode, EnterWorktree
• Skill(skill=...) — Codex uses $skill-name invocation, not a Skill tool
• Agent(subagent_type=...) — Codex uses agent roles, not subagent_type

Mapped Forms Also Prohibited

Lowercase-hyphenated forms are equally invalid (task-create, team-create, send-message).

The previously-mapped todo_write and update_plan are not available as general-purpose tools in Codex sessions (empirically verified via codex exec).

Skill Discovery Paths

Prohibited paths: ~/.claude/skills/, ~/.codex/skills/

Sub-Agent Patterns

Codex orchestration uses:

NOT: TaskList-based queueing, TeamCreate/SendMessage coordination, or Skill tool chaining.

Common Issues

Testing Codex Skills

Two-Phase Validation (Recommended)

Use a two-phase approach for comprehensive coverage at minimal cost:

Phase 1 — Static (fast, no API cost):

• Check frontmatter has only name + description
• Grep for Claude-only primitives (TaskCreate, TeamCreate, SendMessage, etc.)
• Check for ~/.claude/ paths
• Verify reference files are also clean

Phase 2 — Live (thorough, requires Codex API):

# Check if skill loads and is understood
codex exec -s read-only -C "$(pwd)" \
  "Read \$skill-name. Verify it loads, check all referenced tools exist. Rate PASS/PARTIAL/FAIL."

DAG-First Traversal

When validating multiple interdependent skills, traverse in dependency order (leaves first). This ensures that when a skill references $other-skill, the referenced skill has already been validated. Encode the dependency graph explicitly — computed DAGs from frontmatter parsing are error-prone.

Prompt Constraint Boundaries

When using LLM judges to evaluate skills, always include explicit constraint boundaries:

• "Read-only sandbox and missing network access are NOT reasons to FAIL — those are test environment limits, not skill defects"
• "Rate the skill's design quality, not whether it can execute in this test environment"

Without these boundaries, judges conflate environment limits with skill defects.

Shell Compatibility

Scripts that validate Codex skills must work on both macOS (BSD tools) and Linux (GNU tools):

• Use [[:space:]] not \s in grep patterns (BSD grep doesn't support \s)
• Use awk instead of BSD-incompatible sed compound expressions
• Pre-process multi-line LLM output with tr -d '\n' before regex extraction

Release Gate Script

Full DAG-based validation: scripts/smoke-test-codex-skills.sh

scripts/smoke-test-codex-skills.sh --static-only    # Fast CI check (no API)
scripts/smoke-test-codex-skills.sh --chain 2         # Test one chain
scripts/smoke-test-codex-skills.sh                   # Full 54-skill live test

Checklist

When reviewing Codex skills (skills-codex/*/SKILL.md):

• [ ] Frontmatter has only name + description
• [ ] No Claude primitive names (PascalCase or lowercase-hyphenated)
• [ ] No ~/.claude/ paths
• [ ] No Skill(skill=...) tool invocations
• [ ] No Agent(subagent_type=...) tool invocations
• [ ] No context.* or metadata.* frontmatter
• [ ] Reference files (references/*.md) also free of Claude primitives
• [ ] Instructions are actionable for a Codex agent with only Codex tools

Common Standards Catalog - Cross-Language Patterns

Version: 1.0.0 Last Updated: 2026-03-03 Purpose: Universal coding standards shared across all languages. Language-specific files reference this document for philosophical and cross-cutting patterns, keeping language-specific implementation details in their own catalogs.

---

Table of Contents

1. Error Handling Philosophy 2. Testing Best Practices 3. Security Principles 4. Documentation Standards 5. Code Organization Principles 6. Dedup Manifest

---

Error Handling Philosophy

Errors are first-class citizens. Every language has different mechanisms (Result types, exceptions, error returns), but the underlying principles are universal.

Core Rules

Error Chain Preservation

Every language provides a mechanism for preserving error chains. Use it.

Intentional Error Ignores

When errors are intentionally ignored (e.g., best-effort cleanup), document the reason:

Error Aggregation

When multiple operations can fail independently (parallel execution, multi-step cleanup), use the language's error aggregation mechanism rather than discarding all but the first error.

Custom Error Hierarchies

Define a base error type per project/crate/package. Subtypes encode categories.

Principles:

• Base type enables catch-all at API boundaries
• Subtypes enable programmatic handling by callers
• Machine-readable codes (where applicable) enable telemetry
• Human-readable messages enable debugging

Severity Classification

Anti-Patterns (Universal)

---

Testing Best Practices

Test Organization

Table-Driven / Parameterized Tests

The table-driven pattern is universal. Define inputs and expected outputs in a data structure, then iterate.

Benefits:

• Easy to add new cases (one line per case)
• Clear test naming
• DRY -- assertion logic written once

Fixtures and Mocking Philosophy

Test Double Types

Coverage Targets

Coverage philosophy:

• Coverage is a floor, not a ceiling -- low coverage signals under-testing, high coverage does not guarantee quality
• Prioritize critical paths (error handling, security, data integrity) over boilerplate
• Measure branch coverage, not just line coverage -- untested branches hide bugs

Property-Based Testing

Test invariants that must hold for ALL inputs, not just hand-picked examples.

When to use:

• Serialization roundtrips (encode then decode = original)
• Mathematical properties (commutativity, associativity)
• Parser contracts (valid input always parses, invalid always fails)
• Boundary conditions (output never exceeds input, no negative values)

Doc Tests / Example Tests

Code examples in documentation should be executable tests. Guarantees documentation accuracy.

---

Security Principles

No Hardcoded Secrets

Detection: Prescan pattern P2 flags hardcoded secrets in all languages.

Input Validation

Validate at system boundaries (user input, external APIs, file reads). Trust internal code within the same trust boundary.

Injection Prevention

Cryptographic Best Practices

Dependency Auditing

eval/exec/system Avoidance

OWASP Top 10 Mapping

HTTP Handler Security Patterns

Path Traversal Prevention

Resolve user-supplied paths to absolute form, then verify the result stays within the allowed directory.

Key rules:

• Always resolve BEFORE checking — ../ sequences bypass naive prefix checks
• Block null bytes (\0) in file paths — some runtimes truncate at null
• Reject absolute paths in user input when relative paths are expected

Logging Security

Rate Limiting Guidance

Implementation notes:

• Apply rate limits at the reverse proxy / API gateway level when possible
• Return 429 Too Many Requests with Retry-After header
• Log rate limit hits for abuse detection
• Consider separate limits for read vs write operations

---

Documentation Standards

What to Document

What NOT to Document

Examples in Documentation

• Include usage examples for public APIs
• Examples should be runnable (doc tests where supported)
• Show the common case first, edge cases second
• Include error handling in examples

Keeping Documentation in Sync

Cross-Reference Patterns

• Link to related concepts rather than duplicating content
• Use relative paths within a project
• Reference external standards by URL (e.g., RFC numbers, OWASP guides)

---

Code Organization Principles

Module/Package Naming

Public vs Private Visibility

Circular Dependency Avoidance

File Size Heuristics

Version-Aware Development

Language-specific standards SHOULD declare the target language/runtime version and organize modern features by version availability. This prevents using features unavailable in the target version and ensures developers adopt modern alternatives when available.

Import Ordering

All languages follow the same conceptual grouping:

1. Standard library imports 2. External/third-party imports 3. Internal/project imports

Separated by blank lines. Alphabetical within each group.

---

Dedup Manifest

This table maps which sections in each language-specific file contain universal philosophical content that can be replaced with a cross-reference to this document, and which must remain because they contain language-specific implementation details.

Legend:

• keep-as-is -- Section contains primarily language-specific implementation details. No changes needed.
• trim-universal-keep-specific -- Section contains some universal philosophical content that overlaps with this document. Add a cross-reference note at the top of the section pointing here, but keep all language-specific examples and tool commands.
• replace-with-ref -- Section is entirely universal philosophy. Replace with a cross-reference. (None found -- all language sections contain significant implementation details.)

Conservative approach: All language-specific files retain their full content. Only two section categories get a small cross-reference header added. This ensures no loss of language-specific implementation guidance.

---

Related: Language-specific standards in go.md, python.md, rust.md, typescript.md, shell.md

Examples + Troubleshooting Template

Reference template for adding ## Examples and ## Troubleshooting sections to skills. Workers MUST follow this format exactly.

Section Placement

• ## Examples goes BEFORE ## See Also (or at end of file if no See Also)
• ## Troubleshooting goes AFTER ## Examples, BEFORE ## See Also

Append-vs-Create Rules (4 cases)

1. Neither section exists: CREATE both ## Examples and ## Troubleshooting before ## See Also 2. Only `## Examples` exists: APPEND new examples below existing ones; CREATE ## Troubleshooting after Examples 3. Only `## Troubleshooting` exists: CREATE ## Examples before Troubleshooting; APPEND new rows to existing table 4. Both exist: APPEND new examples and new troubleshooting rows to existing sections (don't rewrite)

Examples Format

## Examples

### <Scenario Title>

**User says:** `/<skill> <args>`

**What happens:**
1. Agent does X
2. Agent does Y
3. Output written to Z

**Result:** Brief description of outcome

Each example MUST include:

• A realistic trigger phrase showing how a user invokes the skill
• Step-by-step behavior description (what the agent actually does)
• Expected output or result

Troubleshooting Format

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| Error message or symptom | Why it happens | How to fix |

Each entry MUST include:

• A specific, recognizable error message or symptom
• The root cause explanation
• A concrete fix (command, config change, or workaround)

Per-Tier Requirements

Note: shared is excluded — it's a reference collection, not a skill.

Troubleshooting: max 200 words per skill across all tiers.

Total SKILL.md word count MUST stay under 5000 words. Verify with wc -w SKILL.md.

Quality Bar

• Examples must reflect actual skill behavior (not placeholder text)
• Troubleshooting entries must describe real failure modes users encounter
• Internal skills: show programmatic invocation (how other skills call them)
• User-facing skills: show natural language triggers a human would type

Attribution Patterns for External-Source Absorption

When a skill or reference absorbs patterns from an external corpus (ACFS, gstack, or any third-party knowledge source), attribution is required even when the absorption is pattern-only and contains no verbatim text. Two attribution patterns are supported. Pick one per skill based on source-count.

Pattern A — Skill-level LICENSE.md

Use when the skill is primarily derived from a single external source.

• Place at skills/<name>/LICENSE.md.
• Reference from SKILL.md as plain text, never as a relative markdown link:
• ✅ See \LICENSE.md\ in this skill directory for attribution.
• ❌ See [LICENSE.md](LICENSE.md) for attribution.
• The relative-link form breaks mkdocs --strict because mkdocs flattens skill directories during build (skills/<name>/SKILL.md → skills/<name>.md), so the sibling-file link [LICENSE.md](LICENSE.md) resolves to skills/LICENSE.md which does not exist.
• Example path: skills/<name>/LICENSE.md (the former system-tuning skill used this pattern before its 2026-06 retirement).

Pattern B — Per-reference footer

Use when the skill's references/*.md files draw from two or more external sources.

• Each references/<topic>.md file gets a footer block at the bottom:

  ---
  **Source:** Adapted from <corpus> / <doc-name>. Pattern-only, no verbatim text.

• The skill's SKILL.md does not need its own attribution — the per-ref footers cover all absorbed material.

Choice rule

Constraints (binding for any pattern)

• Pattern-only, no verbatim text. Do not copy >5 consecutive words from the external source.
• Attribute the canonical pattern title when one exists (e.g., "Asuper-style sync" → cite Asupersync corpus).
• Do not use relative markdown links to root-level co-located files in `SKILL.md` — references/ subdir works ([name](references/name.md)), but root-level files (LICENSE.md, notes.md) do not. mkdocs --strict will fail the build.
• Apply a clean-room policy for any external-corpus-derived work. Allowed observations are counts, paths, filenames, metadata, package shape, validation outcomes, CLI behavior, and derived categories. Do not copy external prose, prompts, examples, references, scripts, templates, or role text.

Cross-references

• Pattern A example: any skill carrying a single-source LICENSE.md at its root (see the path rule above).

Go Standards (Tier 1)

Target Version

Detect from go.mod. Use all features up to and including that version. Never use features from newer versions. Current project target: Go 1.26.

Required

• gofmt (automatic)
• golangci-lint run passes
• All exported symbols documented

Error Handling

• Always check errors: if err != nil
• Wrap errors with context: fmt.Errorf("doing X: %w", err)
• Never _ = err without // nolint:errcheck comment
• Use errors.Is(err, target) instead of err == target -- works with wrapped errors (1.13+)
• Use errors.Join(err1, err2) to aggregate errors from parallel operations or multi-step cleanup (1.20+)
• Use context.WithCancelCause / context.Cause to attach error reasons to cancellations (1.20+)

Common Issues

Interfaces

• Accept interfaces, return structs
• Keep interfaces small (1-3 methods)
• Define interfaces where used, not implemented

Documentation

• All exported symbols must have godoc comments starting with the symbol name
• Package-level doc in doc.go for non-trivial packages
• Include runnable Example_* functions in _test.go files
• Run go doc ./... to verify documentation

Concurrency

• Always pass context.Context as first param
• Use sync.Mutex for shared state; use type-safe atomics (atomic.Bool, atomic.Int64, atomic.Pointer[T]) for simple flags/counters (1.19+)
• Prefer channels for communication
• Use sync.OnceFunc(fn) instead of sync.Once + wrapper; sync.OnceValue(fn) when returning a value (1.21+)
• Use context.AfterFunc(ctx, cleanup) to register cleanup on cancellation (1.21+)
• Loop variables are safe to capture in goroutines since 1.22 (each iteration gets its own copy)

Modern Standard Library

slices package (1.21+)

Prefer slices over hand-written loops:

Iterator consumption (1.23+):

maps package (1.21+; Keys/Values return iterators as of 1.23)

cmp package (1.22+)

• cmp.Or(a, b, c) -- returns first non-zero value. Replaces if x == "" { x = default } chains:

  name := cmp.Or(os.Getenv("NAME"), config.Name, "default")

strings / bytes improvements

net/http improvements (1.22+)

Enhanced ServeMux with method and path parameters:

mux.HandleFunc("GET /api/users/{id}", func(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    // ...
})

May eliminate the need for third-party routers for simple APIs.

Other stdlib

Struct Contract Completeness

When adding fields to a struct, every code path that creates an instance must populate them. Partial population creates an inconsistent contract for consumers.

Checklist for adding struct fields: 1. Grep StructName{ across the package — every literal must set the new field 2. Check factory functions and builder patterns 3. Check synthesized/summary instances created outside the main loop 4. Add a structural assertion test: iterate all output instances, assert new field is non-zero (or document why zero is valid)

Wire Input Validation

When parsing external JSON/YAML into structs with enum-like fields, validate against an allowlist before trusting the value.

// BAD: trust whatever the wire sends
if ev.ErrorClass != "" {
    // use it as-is — "bogus" passes through
}

// GOOD: validate against known values
var validClasses = map[ErrorClass]bool{ ... }
if ev.ErrorClass != "" && !validClasses[ev.ErrorClass] {
    ev.ErrorClass = classify(ev) // reclassify from content
}

Also normalize impossible states: if IsError=false but ErrorClass="timeout", clear it.

Testing

Exact Assertion Rule

Always assert the exact expected value, never just "not the wrong one."

// BAD: passes even if classification drifts to a different wrong class
if got == StreamErrorClassRateLimit {
    t.Errorf("should not be rate_limit")
}

// GOOD: pins the exact expected behavior
if got != StreamErrorClassExecutionError {
    t.Errorf("got %q, want execution_error", got)
}

This applies to all classifier/enum tests. != X assertions silently pass when the result drifts to a third, equally wrong value.

Structural Invariant Tests

For structs with required fields, add a sweep test that asserts ALL output instances populate them:

func TestAllViolationsHaveStructuredFields(t *testing.T) {
    // Run through multiple scenarios, collect all violations
    for _, v := range allViolations {
        if v.TeamName == "" && v.Rule != RuleSomeException {
            t.Errorf("violation %+v missing TeamName", v)
        }
        if v.Timestamp.IsZero() {
            t.Errorf("violation %+v missing Timestamp", v)
        }
    }
}

CI-Safe Test Pattern

When testing functions that shell out to external CLIs (bd, ao, gh, etc.), test the low-level function directly instead of the wrapper that invokes the CLI. This ensures tests pass in CI where the CLI may not be installed.

// BAD: calls processDiscoveryPhase() which requires bd CLI
func TestGateDiscoveryVerdictC2Event(t *testing.T) {
    processDiscoveryPhase(ctx, root, opts) // fails in CI — bd not available
}

// GOOD: test event shape directly via the underlying function
func TestGateDiscoveryVerdictC2Event(t *testing.T) {
    ev, err := appendRPIC2Event(root, rpiC2EventInput{
        RunID: runID, Phase: 1, Type: "gate.discovery.verdict",
        Message: "Pre-mortem verdict: PASS",
        Details: map[string]any{"verdict": "PASS", "report": "report.md"},
    })
    require.NoError(t, err)
    assert.Equal(t, "gate.discovery.verdict", ev.Type)
}

Rule: If a function's only untestable part is the external CLI call, extract the testable logic (event emission, state mutation, file I/O) into a separate function and test that.

Table-Driven Tests

Prefer table-driven tests for functions with multiple input/output cases:

func TestClassifyServeArg(t *testing.T) {
    tests := []struct {
        name      string
        flagRunID string
        args      []string
        wantGoal  string
        wantRunID string
    }{
        {"empty", "", nil, "", ""},
        {"flag run-id", "rpi-abc12345", nil, "", "rpi-abc12345"},
        {"arg goal", "", []string{"fix the bug"}, "fix the bug", ""},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            goal, runID := classifyServeArg(tt.flagRunID, tt.args)
            assert.Equal(t, tt.wantGoal, goal)
            assert.Equal(t, tt.wantRunID, runID)
        })
    }
}

Test Conventions

• File naming: Test files MUST be named <source>_test.go. NEVER cov*_test.go, *_extra_test.go, or other non-standard prefixes. Keep all tests for a source file in one test file.
• Function naming: Test<Uppercase> (e.g., TestFoo_Bar). Go requires uppercase letter after Test.
• No coverage-padding: Tests that use trivial != "" or != nil assertions solely to inflate coverage are banned. Every test must assert behavioral correctness.
• No zero-assertion smoke tests: Every test must have assertions. For print/output functions, use captureStdout and assert output contains expected strings.
• Assert exact expected values: Use == expected, never != wrong. (See Exact Assertion Rule above.)
• Table-driven tests preferred for multi-case functions. (See example above.)
• Test low-level functions directly; don't depend on external CLIs (bd, ao) in tests. (See CI-Safe Test Pattern above.)
• Guard-test fixtures must use the real persisted shape. Skip/dedup/consumed/idempotency/regression guard tests must round-trip a real persisted sample (production writer → production reader) or assert against a checked-in real example — never a hand-built in-memory constructor that sets a marker at a granularity the on-disk format never emits (e.g. consumed at item-level when next-work.jsonl marks it at batch-level). A fixture of a shape production can't produce gives a false green (ag-mjlg / PR #652). Full rationale: test-pyramid.md → "Fixture Fidelity".
• Test isolation — restore shared global/process state via `t.Cleanup`. cli/cmd/ao tests share one rootCmd + package-global cobra flag vars and run inside the repo tree, so a test that mutates shared state without restoring it leaks into whatever test the -shuffle=on order runs next. This is a recurring flake class: goals goalsMeasureScenariosOnly cobra-global (a9dab21c4), core.bare git-env (ek8v), cwd floor (hvb).
• Set a package-global cobra flag only through a self-cleaning helper, so every set-site auto-restores and no order can leak it:

    func setGoalsMeasureScenariosOnly(t *testing.T, v bool) {
        t.Helper()
        old := goalsMeasureScenariosOnly
        goalsMeasureScenariosOnly = v
        t.Cleanup(func() { goalsMeasureScenariosOnly = old })
    }

• Scope process state: t.Chdir(t.TempDir()), t.Setenv, and git -C <tempRepo> with cmd.Dir set. Never run a state-mutating git op against the real repo via an unset cmd.Dir / leaked GIT_DIR.
• Find leakers by analysis (grep set-sites for a missing reset), not by chasing reproducing seeds: order-dependent flakes are population+seed-specific, so "couldn't reproduce" ≠ fixed — close on the root (the missing cleanup).
• The push==CI full race suite runs -shuffle=on as the late backstop; it is not the primary guard.

Benchmark Tests (BF7)

Use Go's built-in benchmark support for hot-path functions:

func BenchmarkParseConfig(b *testing.B) {
    input := generateLargeConfig(1000)
    b.ResetTimer()
    for b.Loop() {  // Go 1.24+; use `for i := 0; i < b.N; i++` for older versions
        parseConfig(input)
    }
}

Run with: go test -bench=. -benchmem ./...

Compare across changes with benchstat:

go test -bench=. -count=10 ./... > old.txt
# ... make changes ...
go test -bench=. -count=10 ./... > new.txt
benchstat old.txt new.txt

Backward Compatibility Tests (BF8)

Maintain golden fixtures in testdata/compat/:

func TestBackwardCompat(t *testing.T) {
    fixtures, err := filepath.Glob("testdata/compat/*.json")
    require.NoError(t, err)
    require.NotEmpty(t, fixtures, "compat fixtures must exist")
    for _, f := range fixtures {
        t.Run(filepath.Base(f), func(t *testing.T) {
            data, _ := os.ReadFile(f)
            result, err := ParseConfig(data)
            require.NoError(t, err, "legacy format must still parse")
            assert.NotEmpty(t, result.Name)
        })
    }
}

Regression Tests (BF6)

Name after the bug ID. Reproduce the exact failure:

func TestBug_AG_XYZ_NilMapPanic(t *testing.T) {
    // Regression: processGoals panicked on nil options map (ag-xyz)
    result, err := processGoals(nil)
    require.NoError(t, err)
    assert.Empty(t, result)
}

Security Tests (BF9)

Test path traversal rejection and secrets redaction:

func TestRejectsPathTraversal(t *testing.T) {
    payloads := []string{"../../../etc/passwd", "..\\windows", "foo/../bar"}
    for _, p := range payloads {
        t.Run(p, func(t *testing.T) {
            _, err := LoadConfig(p)
            assert.Error(t, err, "must reject path traversal")
        })
    }
}

Complexity Budget

• Warn at cyclomatic complexity 15, fail at 25.
• Run golangci-lint run to check.

Before Committing Go Changes

cd cli && go build ./... && go vet ./... && go test ./...

Or equivalently: cd cli && make build && make test

HTTP Handler Security

Go HTTP handlers in this codebase are localhost-only but should still follow defense-in-depth:

Query parameter validation pattern:

param := strings.TrimSpace(r.URL.Query().Get("id"))
if param != "" && (strings.Contains(param, "..") || strings.Contains(param, "/") || strings.Contains(param, "\\")) {
    http.Error(w, "invalid parameter", http.StatusBadRequest)
    return
}

DOM construction instead of innerHTML:

// BAD: innerHTML with user-controlled data
el.innerHTML = '<span>' + userInput + '</span>';

// GOOD: DOM construction
const span = document.createElement('span');
span.textContent = userInput;
el.appendChild(span);

Security-Lint Suppressions (gosec + semgrep)

When a security-lint finding is a false positive on intentional crypto (e.g. SHA-1 used for git object IDs, not as a security primitive), the suppression needs TWO independent annotations on the SAME line. gosec and semgrep run as separate scanners and each ignores the other's directives.

Combine both into one comment and place it on both the import line and the usage/call site — each is flagged independently:

import (
    "crypto/sha1" // #nosec G505 nosemgrep -- git object IDs are SHA-1 by definition; not a security primitive here.
)

func gitBlobID(content []byte) string {
    h := sha1.New() // #nosec G401 nosemgrep -- git blob IDs are SHA-1; matching git.
    // ...
}

The G<NN> codes differ by site: G505 flags the crypto/sha1 import (blocklisted import), G401 flags the sha1.New() call (weak crypto primitive). Pass every code that fires on a given line.

Canonical example in this repo: cli/internal/drrebuild/drrebuild.go.

Future Features (Go 1.24+)

This section tracks features by first-supported Go version and can be used to plan future target upgrades.

JavaScript Standards (Tier 1)

Required

• ES2020 or newer (Node 18+ runtime).
• prettier for formatting; eslint with the recommended ruleset.
• package.json declares "type": "module" for new packages.

Style

• const by default; let only when reassignment is required; never var.
• Arrow functions for callbacks; named function for top-level declarations.
• Strict equality (=== / !==) — no loose equality.
• One module per file; default export only when the module is the unit.

Async

• async/await over raw .then() chains.
• Always await or explicitly handle returned Promises.
• Reject errors with Error instances, never raw strings.

Error Handling

• No empty catch {} blocks; either re-throw or log with context.
• Use try/catch only at boundaries (HTTP, IO, IPC); let errors bubble inside pure logic.
• Validate external input before use; trust internal callers.

Common Issues

Testing

• Vitest or Jest; node --test is acceptable for small libraries.
• Use describe / it blocks; one logical assertion per it.
• Mock external services; don't mock the unit under test.
• Snapshot tests only for stable serialized output, never for UI-rich strings.

Security

• Never use eval(), Function(), or new Function() with untrusted input.
• Sanitize HTML before injecting into the DOM; prefer textContent over innerHTML.
• Use crypto.randomUUID() / crypto.getRandomValues(), not Math.random(), for tokens.
• Pin dependency versions in package-lock.json or pnpm-lock.yaml; audit with npm audit before release.

JSON Standards (Tier 1)

Validation

• Valid JSON (use jq . to verify)
• Consistent formatting (2-space indent)
• No trailing commas

Common Issues

JSONL (newline-delimited)

• One JSON object per line
• No trailing newline on last line
• Each line must be valid JSON

Schema Validation

• Use JSON Schema for validation
• Reference: "$schema": "https://..."
• Required fields should be explicit

Security

• Never use eval() or Function() to parse JSON — use JSON.parse()
• Validate against JSON Schema before processing untrusted input
• Watch for prototype pollution in JavaScript/TypeScript JSON handling
• Sanitize keys and values when constructing JSON from user input

Large Files

• Consider JSONL for append-only logs
• Use streaming parsers for large files
• Compress with gzip for storage

LLM Trust Boundary Checklist

Domain-specific checklist for code that calls LLM APIs or processes LLM outputs.

Mandatory Checks

Input Validation

• [ ] User-supplied prompts are sanitized (no prompt injection vectors)
• [ ] System prompts are not exposed to end users
• [ ] Prompt templates use parameterized injection points, not string concatenation
• [ ] Input length limits enforced before API call (prevent token budget exhaustion)

Output Validation

• [ ] LLM output is validated against expected schema before use
• [ ] JSON responses are parsed with strict schema validation (not just json.loads())
• [ ] Hallucinated field names/values are detected and rejected
• [ ] Output is never used as code input without sandboxing (eval(), exec(), shell commands)
• [ ] Empty responses handled explicitly (not silently passed through)

Error Handling

• [ ] API timeout has explicit handling (retry with backoff)
• [ ] Rate limit (429) has backoff strategy
• [ ] Model refusal detected and handled (not treated as valid output)
• [ ] Malformed response has retry-with-stricter-prompt fallback
• [ ] Cost/token budget tracked per request (prevent runaway spending)

Trust Boundaries

• [ ] LLM output treated as untrusted input at every boundary
• [ ] No direct database writes from LLM output without validation
• [ ] No file system operations from LLM output without path validation
• [ ] No network requests to LLM-generated URLs without allowlist check
• [ ] User-visible LLM output has content safety filtering

Observability

• [ ] Request/response pairs logged (with PII redaction)
• [ ] Token usage tracked per call and per session
• [ ] Latency metrics captured (p50, p95, p99)
• [ ] Retry counts and failure modes tracked
• [ ] Model version pinned and logged (not just "latest")

Testing

• [ ] Tests cover malformed response handling
• [ ] Tests cover empty response handling
• [ ] Tests cover refusal handling
• [ ] Tests use deterministic fixtures, not live API calls
• [ ] Evaluation suite exists for output quality regression

When to Apply

Load this checklist when:

• Changed files import anthropic, openai, google.generativeai, or similar
• Code constructs prompts or processes LLM responses
• Plan includes LLM integration or AI-powered features
• Files match patterns: *llm*, *ai*, *prompt*, *completion*, *chat*

Markdown Standards (Tier 1)

Structure

• Single H1 (#) at top
• Hierarchical headings (don't skip levels)
• Blank line before/after headings

Common Issues

Tables

| Header | Header |
|--------|--------|
| Cell   | Cell   |

• Align | for readability
• Use - for header separator

Code Blocks

• Always specify language: `python
• Use inline ` code ` for short refs
• 4-space indent also works (but fenced preferred)

Links

• Use descriptive link text, not generic "click here"
• Use relative paths for local references
• Check links aren't broken

Python Standards (Tier 1)

Required

• ruff check passes (or flake8)
• ruff format (or black) for formatting
• Type hints on public functions
• Docstrings on public classes/functions

Error Handling

• Never bare except: - always specify exception type
• Use raise ... from e to preserve stack traces
• Log before raising in library code

Common Issues

Security

• Never use eval(), exec(), or __import__() with untrusted input
• Use secrets module for tokens, not random
• Validate and sanitize all external input (user data, file paths, URLs)
• Use parameterized queries for SQL — never string formatting

Dataclass & Model Contract Completeness

When adding fields to a dataclass, Pydantic model, or TypedDict, every code path that creates an instance must populate them.

Checklist for adding fields: 1. Grep ClassName( across the package — every constructor call must set the new field 2. Check factory functions (from_dict, from_json, create_*) 3. Check synthesized/summary instances created outside the main loop 4. Add a structural assertion test (see below)

Wire Input Validation

When parsing external JSON/YAML into models with enum-like fields, validate against known values before trusting.

# BAD: trust whatever the wire sends
if event.error_class:
    # use as-is — "bogus" passes through

# GOOD: validate against known values
VALID_ERROR_CLASSES = {"timeout", "rate_limit", "auth_failure", ...}
if event.error_class and event.error_class not in VALID_ERROR_CLASSES:
    event.error_class = classify_error(event)  # reclassify from content

For Pydantic models, use Literal types or @field_validator to reject invalid values at parse time:

from typing import Literal

class StreamEvent(BaseModel):
    error_class: Literal["timeout", "rate_limit", "auth_failure", ""] = ""

Also normalize impossible states: if is_error=False but error_class="timeout", use a @model_validator to clear it.

Classification & Pattern Matching

When classifying inputs by string patterns (error types, log levels, status codes):

Testing

Exact Assertion Rule

Always assert the exact expected value, never just "not the wrong one."

# BAD: passes even if classification drifts to a different wrong class
assert classify(msg) != "rate_limit"

# GOOD: pins the exact expected behavior
assert classify(msg) == "execution_error"

This applies to all classifier/enum tests. != X assertions silently pass when the result drifts to a third, equally wrong value.

Structural Invariant Tests

For dataclasses/models with required fields, add a sweep test that asserts ALL output instances populate them:

def test_all_violations_have_structured_fields(violations):
    """Every violation must populate team_name, timestamp, and event_index."""
    for v in violations:
        assert v.team_name, f"violation {v} missing team_name"
        assert v.timestamp is not None, f"violation {v} missing timestamp"

Property-Based Tests (BF1)

Use Hypothesis to randomize inputs to data transformations:

from hypothesis import given
import hypothesis.strategies as st

@given(st.dictionaries(
    keys=st.from_regex(r'[A-Z_]+', fullmatch=True),
    values=st.text(min_size=0, max_size=200),
    min_size=1,
))
def test_parse_reader_never_crashes(env_vars):
    """Any valid config must parse without crashing."""
    stream = io.StringIO("\n".join(f"{k}={v}" for k, v in env_vars.items()))
    ctx = parse_reader(stream)
    assert isinstance(ctx, SiteContext)

Target: every parser, serializer, and data transformer. If it accepts external input, fuzz it.

Backward Compatibility Tests (BF8)

Maintain a corpus of real inputs from prior versions as fixtures:

from glob import glob

@pytest.mark.parametrize("fixture", sorted(glob("tests/fixtures/compat/*.env")))
def test_legacy_config_parses(fixture):
    """Every historical config format must still parse."""
    ctx = parse_config_env(fixture)
    assert ctx.site_name  # at least one required field populated

Rule: When changing input formats, add the OLD format as a fixture BEFORE making the change.

Performance/Benchmark Tests (BF7)

Use pytest-benchmark for hot-path functions:

def test_parse_config_performance(benchmark):
    """Parser must handle large configs without regression."""
    large_config = "\n".join(f"KEY_{i}=value_{i}" for i in range(1000))
    result = benchmark(parse_reader, io.StringIO(large_config))
    assert isinstance(result, SiteContext)

Install: pip install pytest-benchmark. Run: pytest --benchmark-only.

Regression Tests (BF6)

Every bug fix gets a reproducing test named after the bug ID:

def test_bug_ag_m0r_empty_value_crashes():
    """Regression: parse_reader crashed on config lines with empty values (ag-m0r)."""
    stream = io.StringIO("SITE_NAME=\nDB_HOST=prod-db")
    ctx = parse_reader(stream)
    assert ctx.site_name == ""
    assert ctx.db_host == "prod-db"

Security Tests (BF9)

Test secrets redaction and input sanitization:

def test_render_export_redacts_secrets():
    """render_export must never emit raw secret values."""
    ctx = SiteContext(site_name="test", db_password="s3cr3t!", api_key="ak-12345")
    output = render_export(ctx)
    assert "s3cr3t!" not in output, "raw password leaked"
    assert "ak-12345" not in output, "raw API key leaked"

def test_rejects_path_traversal():
    """Config paths must reject traversal attempts."""
    for payload in ["../../../etc/passwd", "..\\windows", "foo/../bar"]:
        with pytest.raises(ValueError):
            load_config(payload)

General

• pytest preferred
• conftest.py for shared fixtures
• Mock external services, not internal code

Test Conventions

• pytest preferred; conftest.py for shared fixtures.
• ruff linter: ruff check must pass.
• mypy for type checking.
• Black formatter with 100-character line length. Config in pyproject.toml.
• Type hints on all public functions.
• Docstrings on all public classes and functions.

Security

• Never use eval(), exec(), or __import__() with untrusted input.
• Use secrets module for tokens, not random.
• Validate all external input.
• Never bare except: — always specify the exception type.
• Use raise ... from e to preserve stack traces.

Race Condition Checklist

Domain-specific checklist for concurrent, parallel, or multi-process code.

Mandatory Checks

Shared State

• [ ] All shared mutable state protected by mutex/lock/atomic
• [ ] No global mutable variables accessed from multiple goroutines/threads
• [ ] Map/dict access synchronized (Go maps are NOT goroutine-safe)
• [ ] Slice/list append operations synchronized when shared
• [ ] Read-write locks used where reads dominate (not exclusive mutex everywhere)

File System Races

• [ ] Check-then-act on files uses atomic operations (temp file + rename)
• [ ] File locks used for multi-process coordination
• [ ] PID files checked with flock or equivalent, not just [ -f ]
• [ ] Directory creation uses mkdir -p (idempotent), not check-then-create
• [ ] Log file rotation handles concurrent writers

Database Races

• [ ] Upsert uses INSERT ... ON CONFLICT (not check-then-insert)
• [ ] Counter increments use UPDATE ... SET x = x + 1 (not read-modify-write)
• [ ] Unique constraint violations handled with retry (not just error)
• [ ] Optimistic locking uses version column for concurrent updates
• [ ] Queue consumers use SELECT ... FOR UPDATE SKIP LOCKED

API / Network Races

• [ ] Idempotency keys used for non-idempotent API calls
• [ ] Retry logic uses exponential backoff (not fixed delay)
• [ ] Circuit breaker pattern for failing external services
• [ ] Request deduplication for concurrent identical requests
• [ ] Webhook handlers are idempotent (same event delivered twice = same result)

Go-Specific

• [ ] Channel sends/receives have timeout or context cancellation
• [ ] sync.WaitGroup counter matches goroutine count exactly
• [ ] defer mu.Unlock() immediately after mu.Lock() (no early return gap)
• [ ] Race detector run: go test -race ./...
• [ ] Context propagation through goroutine chains (no orphaned goroutines)

Python-Specific

• [ ] threading.Lock used for shared state (GIL doesn't protect everything)
• [ ] asyncio tasks properly awaited (no fire-and-forget without tracking)
• [ ] multiprocessing shared state uses Manager or Value/Array
• [ ] File I/O in async code uses aiofiles (not blocking open())

Testing

• [ ] Concurrent tests exist (multiple goroutines/threads hitting same code)
• [ ] Race detector enabled in CI (go test -race, PYTHONFAULTHANDLER=1)
• [ ] Stress tests for hot paths (100+ concurrent operations)
• [ ] Deterministic ordering tests (verify no output depends on scheduling)

When to Apply

Load this checklist when:

• Code uses goroutines, threads, asyncio, multiprocessing, or concurrent.futures
• Multiple processes read/write the same files
• Database operations involve concurrent access patterns
• Plan mentions "parallel", "concurrent", "async", "worker pool", or "queue"
• Code uses sync.Mutex, threading.Lock, asyncio.Lock, or similar primitives

Rust Standards (Tier 1)

Required

• cargo fmt (automatic)
• cargo clippy passes (no warnings)
• All public items documented (rustdoc)

Error Handling

• Use Result<T, E> for fallible operations
• Implement custom errors with thiserror or anyhow
• Never unwrap() in library code (OK in tests/bins)
• Use ? operator for error propagation

Adapter Recursion Guard

• Subprocess adapters that can invoke their own kernel must set a guard env var

on every child command: <TOOL>_IN_PROGRESS=1.

• Kernel entry must reject re-entry when that env var is already present.
• This is a two-end check: set-on-spawn plus check-at-entry. One end alone is

not enough.

• Source pattern: commit 97e16fe, bead mo-l1tyqp.23, and

MTO_SKILL_AUDIT_IN_PROGRESS from the Mt Olympus skill-audit adapter fix.

pub const GUARD_ENV: &str = "MY_TOOL_IN_PROGRESS";

fn command() -> std::process::Command {
    let mut cmd = std::process::Command::new("sh");
    cmd.env(GUARD_ENV, "1");
    cmd
}

fn entry() -> Result<(), MyError> {
    if std::env::var_os(GUARD_ENV).is_some() {
        return Err(MyError::Recursion);
    }
    Ok(())
}

Ownership & Borrowing

• Prefer references over cloning
• Use &str in function params over String
• Add explicit lifetime annotations when needed
• Clone sparingly and document why

Common Issues

Unsafe Code

• Always add // SAFETY: comment explaining invariants
• Minimize unsafe scope
• Prefer safe abstractions

Security

• Minimize unsafe blocks — each needs // SAFETY: justification
• Use secrecy::Secret<T> for sensitive values (prevents accidental logging)
• Validate all external input before deserialization (serde validators)
• Prefer ring or rustls over OpenSSL bindings

Documentation

• All public items must have rustdoc comments (///)
• Include # Examples section in doc comments for complex APIs
• Use #![deny(missing_docs)] in library crates
• Run cargo doc --no-deps to verify doc builds

Testing

• cargo test (built-in)
• cargo test --doc (doc tests)
• Use #[cfg(test)] modules
• cargo bench for benchmarks

Shell Standards (Tier 1)

Required Header

#!/usr/bin/env bash
set -euo pipefail

Validation

• shellcheck must pass
• Quote all variables: "$var" not $var

Common Issues

Best Practices

• Use local for function variables
• Trap errors: trap 'cleanup' ERR EXIT
• Check command existence: command -v foo >/dev/null
• Use readonly for constants

Cluster Scripts

• Always verify connectivity first:

  oc whoami &>/dev/null || { echo "Not logged in"; exit 1; }

Skill Structure Standard

Version: 2.0.0 Last Updated: 2026-02-20 Source: Claude Code official documentation (https://code.claude.com/docs/en/skills) Purpose: Defines the required structure, frontmatter, and quality standards for all AgentOps skills.

---

Table of Contents

1. File Structure 2. YAML Frontmatter 3. Description Field 4. Body Structure 5. Progressive Disclosure 6. Quality Checklist 7. AgentOps Extensions

---

File Structure

skill-name/
├── SKILL.md              # Required — exact case, no variations
├── SELF-TEST.md          # Optional — trigger and behavior self-test
├── scripts/              # Optional — helper code
├── references/           # Optional — progressive disclosure docs
└── assets/               # Optional — templates, fonts, icons

Rules

---

YAML Frontmatter

Required Fields

---
name: skill-name
description: 'What it does. When to use it. Trigger phrases.'
---

Only description is technically required (recommended). If name is omitted, the directory name is used.

All Claude Code Frontmatter Fields

Execution Mode (Three-Tier Rule)

Skills follow a three-tier execution model based on what the caller needs to see:

When window: fork is set, the skill's markdown body becomes the task prompt for a forked subagent. The subagent runs in isolation — only the summary returns to the caller's context.

Optionally add execution_mode to the metadata block for documentation (informational only — no tooling reads this field):

metadata:
  tier: execution
  execution_mode: orchestrator  # informational — stays in main context

See SKILL-TIERS.md for the full classification table and tier definitions.

Invocation Control Matrix

String Substitutions

Dynamic Context Injection

The ` !command ` syntax runs shell commands before skill content is sent to Claude:

## Context
- Current branch: !`git branch --show-current`
- Recent changes: !`git log --oneline -5`

AgentOps Extension Fields (under metadata:)

AgentOps uses these custom fields under metadata: for tooling integration:

metadata:
  tier: execution     # see schema enum + tier-caps reference below
  dependencies:       # List of skill names this skill depends on
    - standards
    - council
  internal: true      # true for non-user-facing skills
  replaces: old-name  # Deprecated skill this replaces

Allowed tier values (binding — from scripts/validate-skill-schema.sh:174-178): judgment, execution, library, session, product, contribute, meta, background, orchestration, cross-vendor, knowledge.

Per-tier line caps: see `skill-tier-caps.md` for the canonical mapping enforced by tests/skills/lint-skills.sh:65-77.

SKILL-TIERS.md describes "utility", "team", and "solo" categories — these are narrative groupings, NOT binding metadata.tier values. Skills in those categories use tier: execution (e.g., bug-hunt, brainstorm, system-tuning).

Security Restrictions

• No XML angle brackets (< >) in frontmatter
• No claude or anthropic in skill names
• YAML safe parsing only (no code execution)

---

Description Field

The description is the most critical field — it determines when Claude loads the skill.

Structure

[What it does] + [When to use it] + [Key capabilities]

Requirements

• Target under 120 characters; hard limit 180 characters for the repo catalog
• Converter adapters may still enforce their own external hard caps, but repo

skills should stay far below those caps so all descriptions fit the always-loaded catalog

• MUST include trigger phrases users would actually say
• MUST explain what the skill does (not just when)
• No XML tags

Good Examples

# Specific + actionable + triggers
description: 'Investigate bugs or audit code with repro evidence, root cause analysis, and fixes.'

# Clear value prop + multiple triggers
description: 'Validate code readiness with complexity checks and council or inline review.'

Bad Examples

# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user triggers
description: Implements the Project entity model with hierarchical relationships.

Internal Skills Exception

Library/background/meta skills that are auto-loaded (not user-invoked) may describe their loading mechanism instead of user triggers:

description: 'Auto-loaded by /validate, /implement based on file types.'

---

Body Structure

Recommended Template

---
name: skill-name
description: '...'
metadata:
  tier: execution
---

# Skill Name

## Quick Start

Example invocations showing common usage patterns.

## Instructions

### Step 1: [First Major Step]
Specific, actionable instructions with exact commands.

### Step 2: [Next Step]
...

## Examples

### Example 1: [Common scenario]
User says: "..."
Actions: ...
Result: ...

## Troubleshooting

### Error: [Common error]
Cause: ...
Solution: ...

Requirements

---

Progressive Disclosure

Skills use three levels:

1. Frontmatter — Always in system prompt. Minimal: name + description. 2. SKILL.md body — Loaded when skill is relevant. Core instructions. 3. references/ — Loaded on-demand. Detailed docs, schemas, examples.

Rules

• Keep SKILL.md focused on core workflow
• Move detailed reference material to references/
• Explicitly link to references: "Read references/api-patterns.md for..."
• Move scripts >20 lines to scripts/ directory
• Move inline bash >30 lines to scripts/ or references/

---

Quality Checklist

Before Commit

• [ ] SKILL.md exists (exact case)
• [ ] Folder name matches name: field
• [ ] Folder name is kebab-case
• [ ] Description includes WHAT + WHEN (triggers)
• [ ] Description under 180 characters, preferably under 120
• [ ] No XML tags in frontmatter
• [ ] No claude/anthropic in name
• [ ] metadata.tier is set and valid
• [ ] SKILL.md under 5,000 words
• [ ] User-facing skills have examples section
• [ ] User-facing skills have troubleshooting section
• [ ] Market-facing user skills have SELF-TEST.md
• [ ] Detailed docs in references/, not inlined
• [ ] No README.md in repo-runtime skill folder unless an external package profile explicitly permits it

Trigger Testing

• [ ] Triggers on 3+ obvious phrases
• [ ] Triggers on paraphrased requests
• [ ] Does NOT trigger on unrelated topics

---

AgentOps Extensions

These are AgentOps-specific patterns not in the Claude Code spec:

Tier System

Controls line limits and categorization. Enforced by tests/skills/lint-skills.sh.

Dependencies

Declared under metadata.dependencies. Validated by tests/skills/validate-skill.sh.

Skill Tiers Document

Full taxonomy at skills/SKILL-TIERS.md.

Standards Loading

Language standards loaded JIT by /validate, /implement — see references/standards-index.md.

Marketplace Export Profile

A marketplace-facing package shape differs from AgentOps' repo-runtime shape:

• Published package candidates should pass the target marketplace validator before release.
• Package-clean skills should stay at or under a 50-file validator limit.
• Mega skills above that limit should be split or handled as an explicit product-bundle profile.
• Exported scripts/ files should be non-executable for marketplace validation, even if repo-native AgentOps scripts remain executable.
• Strong market-facing skills should include SELF-TEST.md.
• Large skills should keep SKILL.md as a routing kernel and move expensive context into references/, scripts/, assets/, and, when justified, subagents/.

Use docs/reference/skill-quality-rubric.md for scoring against this profile.

SKILL.md Tier-Specific Line Caps

Source of truth: tests/skills/lint-skills.sh:65-77 (case statement). The PreToolUse hook warns at 248 lines globally, but the binding cap is per-tier. A 260-line meta-tier skill is broken; a 260-line execution-tier skill is fine.

Caps by tier

Why per-tier instead of global

• meta and library skills are short reference contracts; long bodies indicate misuse.
• background skills are autoloaded — long bodies bloat the always-loaded context.
• execution skills run multi-step workflows; their bodies legitimately need more room for steps and examples.
• judgment/product/session skills carry decision frameworks and personas that benefit from narrative depth.

How to plan trimming work

1. Read the skill's tier: frontmatter. 2. Look up the tier's cap in the table above. 3. If wc -l SKILL.md exceeds the cap, plan trimming. Otherwise no work needed.

The 248-line PreToolUse warning is global pre-lint awareness only — it does not mean the skill is in violation.

Cross-references

• Lint enforcement: tests/skills/lint-skills.sh:65-77
• Schema enum: scripts/validate-skill-schema.sh:174-178 (the binding metadata.tier enum)
• Narrative tier categories: skills/SKILL-TIERS.md (note: "utility category" there is a grouping, not a binding tier value)

SQL Safety Checklist

Domain-specific checklist for code that interacts with databases.

Mandatory Checks

Injection Prevention

• [ ] All user input is parameterized (no string interpolation in queries)
• [ ] ORM queries use parameter binding, not f-strings or .format()
• [ ] Raw SQL uses ? or $N placeholders, never concatenation
• [ ] Dynamic table/column names are validated against an allowlist

Migration Safety

• [ ] Migrations are reversible (both up and down defined)
• [ ] No DROP TABLE or DROP COLUMN without explicit data migration plan
• [ ] Large table migrations use batched operations (not full-table locks)
• [ ] Index creation uses CONCURRENTLY where supported (PostgreSQL)
• [ ] Migration tested on production-size dataset (not just empty dev DB)

Query Performance

• [ ] Queries touching >1000 rows have appropriate indexes
• [ ] No SELECT * in production code (explicit column lists)
• [ ] N+1 queries identified and resolved (use includes/preload/JOIN)
• [ ] Pagination used for unbounded result sets
• [ ] EXPLAIN ANALYZE run on new queries touching large tables

Transaction Safety

• [ ] Long-running transactions avoided (< 30s)
• [ ] Deadlock-prone operations use consistent lock ordering
• [ ] Retry logic for serialization failures / deadlocks
• [ ] Connection pool sized for peak concurrent transactions

Data Integrity

• [ ] Foreign keys enforced at database level (not just application)
• [ ] NOT NULL constraints on required fields
• [ ] Unique constraints on business-key columns
• [ ] Check constraints on bounded values (enums, ranges)
• [ ] Soft deletes use deleted_at timestamp, not boolean

When to Apply

Load this checklist when:

• Changed files contain SQL queries or ORM calls
• Migration files are in the changeset
• Database schema changes are proposed in the plan
• Code interacts with database/sql, sqlx, gorm, sqlalchemy, activerecord, prisma, knex, or similar

Standards Index

JIT loading map for validation agents. Load only what you need based on file types.

Extension to Standard Map

Universal Standards (Always Load)

Always load vibe-coding.md first, then common-standards.md and behavioral-discipline.md for universal patterns.

Pattern Files (Load When Relevant)

JIT Loading Pattern for Agents

## Step 1: Detect File Types

Scan the target files to identify languages:
- Use Glob to find files
- Note extensions present

## Step 2: Load Relevant Standards

For each language detected, use Read tool:

Tool: Read
Parameters:
  file_path: "skills/validate/references/<language>-standards.md"

Only load standards for languages actually present in the review.

## Step 3: Apply Standards

Reference the loaded standards when validating code.
Cite specific sections: "Per python-standards.md section 3.2..."

Example: Mixed Python/Go Review

Files detected: src/main.py, pkg/handler.go, scripts/deploy.sh

Load (3 standards only):
1. Read("skills/validate/references/python-standards.md")
2. Read("skills/validate/references/go-standards.md")
3. Read("skills/validate/references/shell-standards.md")

Skip: typescript, yaml, json, markdown (not present)

Context Budget

Keep agents lean. Load only what's needed.

JIT Loading Order

1. vibe-coding.md (universal — trust calibration, failure patterns) 2. common-standards.md (universal — cross-language error handling, testing, security, docs, organization) 3. behavioral-discipline.md (universal — assumptions, simplicity, scope control, verification) 4. Language standards (per detected extensions) 5. Pattern files (if architecture/discovery review)

TypeScript Standards (Tier 1)

Required

• strict: true in tsconfig.json
• prettier for formatting
• eslint with recommended rules

Type Safety

• No any - use unknown + type guards
• No @ts-ignore without explanation
• Prefer interface for objects, type for unions

Common Issues

React (if applicable)

• Functional components only
• useState / useReducer for state
• useEffect with proper deps array
• No inline object/function props (memo issues)

Testing

• Jest or Vitest
• React Testing Library for components
• MSW for API mocking

YAML Standards (Tier 1)

Validation

• yamllint must pass
• 2-space indentation
• No trailing whitespace

Common Issues

Kubernetes/Helm

• Use --- between documents
• Labels: app.kubernetes.io/*
• Always specify resources.limits
• Use ConfigMaps for config, Secrets for secrets

Security

• Never use yaml.load() (Python) — always yaml.safe_load()
• Quote values that look like booleans ("yes", "no", "true")
• Validate against schema before processing untrusted YAML
• Avoid anchors/aliases (*/&) in user-facing configs — confusing and exploitable

Multiline Strings

# Literal (preserves newlines)
description: |
  Line 1
  Line 2

# Folded (joins lines)
description: >
  This becomes
  one line

Standards Skill Self-Test

Trigger Cases

• User says: "audit this skill against AgentOps skill structure standards."
• Expected: load standards as a library skill and use references/skill-structure.md.

• User says: "validate this Go change against repo standards."
• Expected: load standards and use references/go.md.

• User says: "check whether this skill can absorb an external corpus safely."
• Expected: load references/external-source-attribution.md and apply its clean-room policy when applicable.

Non-Trigger Cases

• User asks to implement a feature with no files or language context.
• Expected: do not load every standards reference; wait until file types or risk patterns are known.

• User asks for general product strategy.
• Expected: use product/discovery skills, not standards, unless code or skill standards become relevant.

Behavior Checks

• standards stays a library skill and writes no artifacts by itself.
• Language standards load on demand by file type rather than all at once.
• Domain checklists load only when matching risk patterns are present.
• External-source absorption follows references/external-source-attribution.md.
• Skill authoring and export guidance points to references/skill-structure.md.

Validation Commands

Run from the repo root:

bash skills/standards/scripts/validate.sh
bash skills/heal-skill/scripts/heal.sh --strict
bash scripts/validate-skill-frontmatter.sh --strict

Failure Cases

• Missing reference file: fail skill validation and restore the missing file or remove the link from SKILL.md.
• Wrong standard selected: identify the file type or risk detector that selected it and update the relevant loading rule.
• External corpus content copied verbatim: stop, remove copied content, and keep only pattern-level observations with attribution.