automation-agent

Update the okf/ knowledge bundle after a change to the system — the touched concepts, their index entries, the affected diagrams, and the bundle log. Use at the end of any change that alters system shape (an agent, a Kind, a route, a check name, a package, an env var, a port convention), or standalone when the bundle has drifted from reality.

Convert acceptance criteria, Jira tickets, Gherkin scenarios, PRDs, or any product requirements into a filled-in spec under specs/ using this repo's templates. Use when translating PM artifacts or informal asks into an add, change, migrate, or remove spec ready for implementation.

Scaffold a new deterministic, agent-free tooling package on the modern pair, with tests and its knowledge concept. Use when the system needs a new platform capability (an API client, ingress, transport, notifier-style package) rather than a new workflow.

Scaffold a new workflow agent end-to-end on the modern pair — ingest Kind, dispatcher registration, agent package, tests, webhook route, and the knowledge updates. Use when adding an entirely new workflow (a new fixer, digest, or reviewer-style agent) to the system.

Interview the user one question at a time to resolve every unfilled marker in a spec file (`<!-- TODO -->`, raw template placeholder prose, `<YYYY-MM-DD>`-style header stubs, empty plan steps, unconfirmed reverse-spec presumptions). Use on hand-authored specs, stale specs, or when the user says "grill me" or "stress-test this plan". The conversion skills (/ac-to-spec, /reverse-spec) embed this logic inline, so freshly-converted specs don't need a separate pass. Recommends an answer for every question, explores the codebase and okf bundle instead of asking when it can, and writes resolutions back with a Decisions log.

Execute a library, API, or framework swap on a port — mechanical migration that preserves observable behavior, verified against the shipped API. Use when bumping a major SDK version (e.g. the ADK), swapping a library, or moving to a new provider API.

Reverse-engineer a spec from existing code — reconstructs presumed intent, event flow, external contracts, config, and business rules by reading source, tests, prompts, and git history. Use when inheriting undocumented behavior, onboarding onto a workflow agent or platform package, checking modern-pair drift, or capturing a baseline before a change or migration.

The house pre-PR flow — port gates green, CodeRabbit CLI review on the branch diff, evidence-based triage, then present everything and WAIT for human approval. Use when a branch is feature-complete, before any commit/push/PR.

Run the emulator-gated Firestore test suites (session + park store) for the Go and Python ports. Use after changing session/park-store code or workflow event fields — these suites are excluded from the default `make ci` gate.

Generate a structured briefing on the whole system, a workflow agent, a language port, or a standard, driven by the okf/ knowledge bundle. Use for onboarding, context-switching, or before reviewing unfamiliar code.

Modify existing behavior from a change spec — concept-first reading, Go-first implementation, Python mirror, contract preservation, and the knowledge updates. Use when changing how an existing agent, package, or flow behaves.

Verification pipeline with three scopes — diff (default, changed ports only + okf conformance), full (all four ports' gates), and okf (bundle conformance only). Use after any code or docs change.