The api.automate lifecycle

The staged pipeline automates API-test creation end to end — from topic requirements to committed, accepted tests. Each stage is a dedicated goga skill; every stage except create-testcases is a communication stage that involves you in the default interactive mode (see Autonomous runs for the unattended window).

Need to adjust the pipeline for your project without forking it? See Workflows.

Stages

#	Stage	Purpose
1	create-requirements	Collect detailed requirements for the testing subject → requirements.md
2	requirements-audit	Review the requirements artifact
3	test-design	Design integration test cases (TC-<N>, REQ→TC traceability) → testcases.md
4	test-audit	Review the test cases
5	prepare-testcases	Design the test cells (CODEMANIFEST per Routine) → arch.md
6	review-testcases	Review the test-cells plan
7	create-testcases	Materialize the test cells into tests/<spec>/<id>/
8	code-design	Design the test code (materialization of test_*.py from the cells) → design.md
9	design-review	Review the test design
10	coding-plan	Compile the execution plan — convention rules extracted as mandatory rules, pytest as validation — → plan.md
11	plan-review	Review the plan
12	commit-changes	Commit the work; ask the user whether the tests are ready for acceptance (auto-approved on autonomous runs)
13	accept-result	Accept the test results: consistency check, pytest run, triage of failures with the user, bug records in bugs.md

The create-requirements stage opens the topic: once the testing subject is clarified, its intake runs one idempotent goga history ensure — the topic is the current git branch. Every later stage addresses artifacts with goga history path -f <artifact>.

Building the tests: the design stages produce documents only. After plan-review approves plan.md, the test code is built with goga build <path-to-plan> — goga executes the ralphex plan, writing each test_*.py from the plan's Tasks and running the Validation Commands (pytest). Stage 7 (create-testcases) materializes the test cells (CODEMANIFESTs under tests/<spec>/<id>/), not the test code — the test_*.py files appear only at build time.

Artifacts

The pipeline accumulates one artifact per design stage in the topic's history directory — the path printed by goga history path -f <artifact> (.goga/history/<year>/<topic>/; the topic is the current git branch, created by the requirements stage via goga history ensure):

requirements.md   # detailed requirements (REQ-<N>)
testcases.md      # test cases (TC-<N>) + coverage matrix
arch.md           # test-cells architecture plan
design.md         # test-code design document
plan.md           # ralphex execution plan
bugs.md           # triaged service bugs found at acceptance
tests/<spec>/<id>/  # the materialized test code (in the project tree)

Sandbox runs

When the consumer project carries a sandbox document (.goga/tools/pybuggy/sandbox.yml — see Sandbox), part of the topic's cases can run against the sandbox: the isolated instance with mocked dependency services (postgresql/kafka/vault/http/redis) started by the product sandbox fixture. The decision travels the pipeline as data:

• create-requirements records the fact — §4 "Sandbox": configured (image, services) or not configured (the tests are written without the sandbox; it is never offered) — and, when configured, asks the run target right after the spec-ref question: all cases in the sandbox | target env | mixed (decided per case later). The answer lands in §4 and drives the preconditions phrasing (sandbox seeding needs, never "records of the dev database"), the recorded run commands (a sandbox-only topic carries no --base-url), and the case assignment at the test-design stage.
• test-design assigns environments per the recorded run target: all cases sandbox marks every case sandbox without per-group questions; target env never offers the sandbox; mixed asks — per group — which cases run in the sandbox. Every case carries its environment: sandbox | target env.
• The cells stage wires the sandbox usages (.goga/usages/cooks/pybuggy/sandbox/**) into the affected cells, declares the product sandbox fixture in the Routine signature, and writes the bind — binding the client to the sandbox before any request — as the first step of the Routine.
• code-design and coding-plan carry the bind into the materialized test_*.py and note the docker-compatible container runtime precondition next to the test-run commands; the command itself does not change — a bound test ignores --base-url, the unbound tests keep it.
• At acceptance and in the api.fix cycle, a sandbox startup failure (no docker runtime, image pull, probe timeout, migrations) is an environment problem — not a service bug and not a test defect.

Topic status

Every artifact of the chain marks a status on the goga topic status scale — the package registers one pybuggy.* status per artifact, so a pybuggy topic reports its latest reached stage under its own name instead of the built-in axis:

Artifact	Status
requirements.md	pybuggy.automate.requirements-created
testcases.md	pybuggy.automate.testcases-designed
arch.md	pybuggy.automate.arch-prepared
design.md	pybuggy.automate.code-designed
plan.md	pybuggy.automate.coding-planned
completed/plan.md	pybuggy.automate.done

Each automate status anchors above its built-in twin (automate.done above the built-in done), and goga history status shows the latest reached stage of the topic. Read the scale with goga history status; filter topics by any registered name with goga history status -s <name>. Service bugs recorded in bugs.md are history records — they mark no status on the scale.

Autonomous runs

The pipeline can run unattended from the test-cells review onward. Autonomy is opt-in per pipeline through the pipelines section of the tool config — set it by hand or through the autonomy confirm of pybuggy init:

# .goga/tools/pybuggy/config.yml
pipelines:
  api.automate:
    autonomous: true

With the entry enabled, pybuggy contributes a fixed workflow document (the Workflows mechanism) to every api.automate run:

• The seven-stage auto-approval window review-testcases → commit-changes (stages 6–12 of the table above): every stage of the window is approved automatically — the communication stages no longer pause for your review.
• A build stage appended after commit-changes: the same goga build step as the Building the tests note above, run on the topic's plan.md with an eight-hour timeout and the .ralphex scratch tree removed afterwards — the committed tests are built without a manual build step.

Everything outside the window stays with you: the requirement-shaping stages (create-requirements … prepare-testcases) run interactively, and accept-result is never part of the contribution — it keeps its manual trigger, so accepting the results (the pytest run and the failure triage) remains an interactive step.

The contribution is a silent no-op for every pipeline outside the automate and patch lines — the window shape is carried per pipeline record — and for every disabled state: an absent file, an absent pipelines section, an absent api.automate entry, and autonomous: false all mean a normal interactive run. Autonomy never disables silently on a malformed config: a structural violation of the section (a file root or pipelines value that is not a mapping, an entry shaped other than exactly autonomous: <boolean>) stops the command with a clean error naming pybuggy, and the whole contribution is discarded.

An authored project workflow wins per slot over the contribution — a .goga/workflows/pybuggy:api.automate.yml can re-enable interaction for any window stage or displace the build entry.

How it relates to the rest

• When accepted suites break — now or later — the api.fix lifecycle collects the failures and drives the repair cycle.
• The generated api/ fixtures are what the materialized tests consume.
• The pipeline stages are goga skills (goga-tool-pybuggy-api-automate-*) driven by the goga agent in the consumer project — the same project goga tool pybuggy init bootstraps (usage keys pybuggy-api / pybuggy-asserts teach the consumer's agent the runtime contracts).