Everyday practice: from idea to release.

11.1 The loop at a glance

The previous chapters explained each building block on its own. In everyday work they mesh together. The factory’s guiding principle sums it up in three sentences: You describe. The factory builds. You approve. In between lies a cycle that you go through again for every feature:

Idea
  → Spec (goal, non-goals, acceptance criteria with IDs)
  → Spec approval (human, MAINTAINER or higher)
  → Plan run (plans/*.md with Spec:/AC: reference)
  → Activate backlog item
  → Build run on its own branch
  → Validation (build) → correction loop if needed
  → Quality gate (reviewers, incl. acceptance criteria)
  → Approval before merge / pull request
  → Check why-trace, maintain memory
  → Milestone release
  → next idea

Two things matter about this cycle. First, there are deliberate stops where a human decides — spec approval, approval before execution (the default without an approval policy) and approval before merge (set up via an approval policy or compliance profile). Second, between the stops the factory works on its own, including corrections. You don’t need to watch an agent type; you need to take the stops seriously.

Open full-size graphicOpen full-size graphic

11.2 Step 1: Sharpen the idea

Our example project is MaintHub, the maintenance order portal from the user manual: Spring Boot backend with a REST API under /api/v1, React frontend, roles ADMIN and DISPONENT (dispatcher), hexagonal architecture. The project already exists; a few build runs have produced order CRUD and the order list.

The business department gets in touch: “Dispatchers should be able to cancel orders.” That is a typical idea — short, plausible and full of unresolved questions:

• Can any order be cancelled, even one that is already completed?
• Is a cancelled order deleted, or does it stay visible with a status?
• Is a reason required? Who sees it?
• What happens if two dispatchers cancel at the same time?
• May a technician cancel?

If you hand this idea unchanged to an agent as a run goal, it will answer every one of these questions — silently, at its own discretion, somewhere in the code. The factory’s engineering guardrails do require the agent to disclose its assumptions and choose the most conservative interpretation, but that does not replace a business decision. That is why the first step is not the run but the conversation: you clarify the questions with the business department or record them as open questions.

What you do

• Collect business questions and get them answered.
• Record what is explicitly not included (e.g. “no restoring of cancelled orders in this step”).
• Check whether the idea fits into one run or breaks down into several backlog items.

11.3 Step 2: Write the spec

The answers become the spec. Chapter 4 covered structure, EARS templates and typical mistakes in detail; here is just the result, in compact form:

---
id: SPEC-007
titel: Cancel order
version: 1
status: DRAFT
owner: Dispatch business unit
contracts: []
ersetzt: null
---

# SPEC-007 — Cancel order

## Ziel
Dispatchers can cancel open maintenance orders with a reason, so that
erroneous entries and called-off appointments disappear cleanly from
planning without losing the history.

## Nicht-Ziele
- No restoring of cancelled orders.
- No notification of technicians (separate spec).

## Akzeptanzkriterien
- **AC-007-01** — When a user with role DISPONENT cancels an order in
  status OFFEN with a reason of 10 to 500 characters, the system shall
  set the status to STORNIERT and store the reason, user and timestamp.
- **AC-007-02** — If the order is not in status OFFEN, then the system
  shall reject the cancellation with HTTP 409 and leave the status
  unchanged.
- **AC-007-03** — If the reason is missing, shorter than 10 or longer
  than 500 characters, then the system shall reject the cancellation
  with HTTP 400 and an understandable message.
- **AC-007-04** — If a user without role DISPONENT or ADMIN cancels,
  then the system shall reject the request with HTTP 403.
- **AC-007-05** — The system shall hide cancelled orders in the order
  list by default and show them via a filter.

## Edge cases
- Two simultaneous cancellations of the same order: exactly one wins,
  the second receives 409.

## Open questions
- (none)

Note what this spec achieves: every criterion describes behaviour, not implementation. Limits are concrete (10 to 500 characters, HTTP codes). The non-goals prevent the agent from “helpfully” building a restore function or email notification. The concurrency edge case is recorded; you could also turn it into its own AC if it is to be formally accepted.

11.4 Step 3: Plan and fill the backlog

Five acceptance criteria sound manageable, but they touch the domain, persistence (new columns or a migration), the REST interface, permissions and the frontend. Instead of packing everything into one run, you let the factory plan. A plan run changes no production code; it writes proposals as Markdown under plans/.

A good plan for this feature could look like this:

Each plan file states its spec reference in two lines — exactly as chapter 5 described:

Spec: SPEC-007
AC: AC-007-01, AC-007-02, AC-007-03, AC-007-04

11.5 Step 4: Build

Now the agent works. For you this is the phase where you have the least to do — and where the temptation to intervene is greatest. Resist it. What you do instead:

• Skim the live logs, don’t read every line. Things that stand out are loops (the agent keeps reading the same file), tool errors and signs of missing context.
• Don’t work in parallel in the same workspace. Only one agent ever writes per workspace; your own changes belong on a separate branch or have to wait.
• Abort on genuine wrong turns instead of watching — and then improve the task rather than restarting the same run.

If the build goes red, that is no cause for concern. That is exactly what the correction loop is for: the factory gives the agent the build output as new information and lets it fix things. Only if that repeatedly fails is it your turn.

11.6 Step 5: Read the quality gate

A green build says: the code compiles, the existing tests pass. It does not say whether the code is secure, respects the architecture or does the right thing. That is what the quality gate is for. In everyday work you read its result like a review comment from an experienced colleague — with the same mix of trust and scrutiny.

What you check

• The verdict: PASSED, WARNING, FAILED, SKIPPED or ERROR. ERROR means a reviewer crashed. That is never a silent pass but a reason to look.
• The findings by category: security findings (e.g. SQL concatenation, hard-coded keys) and architecture findings (e.g. a modified existing Flyway migration) weigh heavily.
• AC coverage (checked automatically by the spec-conformance reviewer since v0.38.0): for every bound criterion there must be at least one test that references the AC ID (test name, an annotation such as @Spec("AC-007-02"), or a comment). If one is missing, the criterion is not evidenced.
• Uncovered behaviour: changed production files not mapped to any criterion deserve a look — perhaps the agent “helpfully” built something that is listed in the non-goals.

11.7 Step 6: Acceptance and approval before merge

The gate is green. Now comes the stop that is most often underestimated: human approval before the merge. It does not happen by itself: set it up via an approval policy (/policies) or a compliance profile with mandatory approval VALIDATION; without it, the factory merges (or opens the PR) directly after a green gate, and your review takes place in the PR. It is not a formality. With your approval you take responsibility for the code — just as you would for a colleague’s pull request.

How to read an agent diff

1. Spec first, then the diff. Read the acceptance criteria again before you look at code. That way you check against the task, not against your gut feeling.
2. Tests first. Check whether the tests really capture the behaviour of the criteria. A test that only checks “no error” proves nothing. Look for negative and boundary cases (9 and 501 characters for the reason).
3. Then the production changes. Every changed line should be traceable to a criterion. Large-scale reformatting, “clean-up work” in unrelated classes or new dependencies are warning signs.
4. Read the agent’s decision notes. The guardrails require it to disclose assumptions and deviations. If anything there touches business logic, it belongs back in the spec.
5. Be especially thorough with migrations and security. Database changes are hard to undo; authorization errors are the most expensive errors.

11.8 Step 7: Release and the next pass

Both items are DONE. For the business department, only the shipped version counts. A release bundles completed work, documents it and marks the state in the repository. Then the cycle starts over — either with the next idea or with a change to the spec, because after the first few weeks the business department wants a list of predefined reasons instead of free text after all.

This second case in particular shows the value of the spec: you change SPEC-007, a new version is created, and the comparison on the spec detail page already shows today which criteria are new, removed or changed. Since v0.38.0, after approval the factory additionally marks open backlog items bound to a changed or removed criterion as stale, moves bound workflow tasks to WAITING_FOR_REPLAN and writes the comparison as SPEC_DRIFT into the audit chain. Instead of “something changed”, you get a precise list.

11.9 Anti-patterns: please don’t

The following patterns show up in almost every team that starts working with agents. Each has a simple countermeasure.

11.10 Checklists for everyday work

Before the first run in a project

• Project definition complete: vision, target audience, stack, architecture, security, NFRs, Git conventions filled in; no empty placeholders in the generated artifacts.
• Artifacts read: skimmed PROJECT.md, INSTRUCTIONS.md, AGENTS.md once.
• Team chosen: suitable agent roles, preferred models set deliberately.
• Adapter and auth mode settled: subscription only for personal use; in a team, API key or gateway.
• Sandbox decided: container mode for build runs if Docker is available.
• Gate mode set: at least advisory.
• Budget set (at least observing) and spec mode chosen.
• Practise with mock first if you don’t know the flow yet.

Before spec approval

• Goal phrased from the user’s perspective, not as a technical task.
• Non-goals named.
• Every criterion has an ID, describes a behaviour and is testable (no vague words like “fast” or “user-friendly”).
• Negative and boundary cases covered.
• No open questions left in the “Open questions” section.
• Confirmed from a business perspective by someone who is not implementing it.

Before merge approval

• Gate verdict understood, no ERROR ignored.
• Every bound AC evidenced by a test, negative cases included.
• No changes outside the task (uncovered behaviour checked, non-goals respected).
• Migrations and permissions checked separately.
• Agent’s decision notes read; business assumptions fed back into the spec.
• Not your own run, if segregation of duties applies.

After the release

• Why-trace spot-checked: bound spec version, model, approvals.
• Memory extended with learnings, outdated entries removed.
• Backlog tidied: rejected plans removed, stale items reassessed.
• Costs of the milestone reviewed in /analytics.
• Spec changes for the next version started as a new draft version.

11.11 Roles in everyday team work

Agents change who does what, not that someone has to carry responsibility. In practice the following responsibilities have proven themselves; they can be mapped onto the factory’s role model.

Alongside these are the agent roles in the factory’s teams (Architect, Developer, Reviewer, QA, Security Reviewer, Documentation, Merge/Release). They describe the mission and rules an agent works with — they replace none of the human roles above, and in particular not approval.

11.12 Where to go from here

You now have the theoretical and practical tools to work effectively with the factory. Knowledge becomes skill through repetition. A proven path:

1. First pass with mock: create a project with the project wizard, write and approve a spec, plan run, activation, build — at no cost, to get to know the UI. Guides: Quick start and Tutorial.
2. Real adapter, small feature: a spec with three to five criteria, spec mode LEICHT, gate advisory. Goal: learn to read gate findings.
3. Get stricter: spec mode STRENG, gate blocking, approval before merge with segregation of duties.
4. Existing repo: import one of your own repositories and start with a spec for existing behaviour.
5. Team and operations: set up roles, tenants, budgets and policies (administration manual).
6. Parallel and regulated: try out the workflow layer (chapter 7) and compliance profiles with audit export and offline verifier (chapter 9).

For reference: user manual, administration manual, FAQ and the known limitations. And if you want to refresh a concept: the overview leads to all chapters; looking back at chapter 4 (Specs and EARS) is especially often worthwhile.

Chapter questions

These questions draw on the entire course. If you can answer them confidently, you have understood the essentials.

1. Name the stops in the loop where a human decides, and explain for each what could go wrong without it.

   Model answer

   Spec approval: without it the agent builds against unconfirmed requirements, and the gate checks against the wrong criteria. Approval before execution (default without an approval policy): without it an agent starts without consent, e.g. with the wrong goal or adapter. Approval before merge: without it code would be in the base branch before anyone agreed — a signed commitment would be a facade. In workflows, plan approval is added.

2. Why does a backlog item only become DONE once its build run has been merged, and not as soon as the code is written?

   Model answer

   Because successors build on the base branch. An item whose work is still on the run branch (e.g. with NEEDS_CORRECTION or an open PR) is not available to dependent items. A premature DONE would release dependencies that are in fact not yet satisfied.

3. In the example, a test for AC-007-04 was missing. Describe the path from finding to corrected state and explain why this is not a blind retry.

   Model answer

   spec-conformance reports AC-007-04 as not referenced by any test. In spec mode STRENG this is a CRITICAL finding in the blocking gate and triggers the correction loop; the new run on the same branch receives the finding as feedback and delivers the negative test. It is not a blind retry, because new information (the concrete finding) goes in and makes the second attempt deliberately different.

4. During a build run, an agent changes specs/SPEC-007-…/spec.md and adds a criterion. What happens to it, and what is your job?

   Model answer

   The factory adopts the change after the build as a new DRAFT version; it is never approved automatically, and the running run stays bound to the version bound at start. Your job: review the draft, get it clarified from a business perspective and have it approved or discarded — by a person with MAINTAINER or higher.

5. You are asked to approve an agent’s pull request. In which order do you read, and why that order?

   Model answer

   First the spec’s acceptance criteria (set the yardstick), then the tests (do they evidence the behaviour including negative and boundary cases?), then the production changes (can every line be traced to a criterion?), then the agent’s decision notes, with special attention to migrations and permissions. That way you check against the task instead of your gut feeling and spot uncovered behaviour.

6. A colleague suggests setting the quality gate to off because the hallucination-reviewer produces too many notices. What do you answer?

   Model answer

   With off, security, architecture, dependency and spec findings disappear too. Better: understand the findings (they often point to real gaps such as missing tests), refine the task or the spec, and if necessary use advisory instead of blocking. Switching off a gate because it reports something is like unplugging a smoke detector because it beeps.

7. After three weeks the business department changes SPEC-007: AC-007-03 gets a list of predefined reasons instead of free text. What does the factory show you after the new version is approved, and what do you do?

   Model answer

   The AC-level comparison shows AC-007-03 as changed; the factory writes SPEC_DRIFT with the affected AC ID into the audit chain, marks open backlog items bound to AC-007-03 as stale and moves bound workflow tasks to WAITING_FOR_REPLAN. You then plan the adjustment (plan run or new item) with reference to the new version; the tests for AC-007-03 are adjusted.

8. Half a year later, an auditor asks why cancellation was built without notifying technicians. Which traces in the factory help you answer?

   Model answer

   The approved spec version with the non-goal “No notification of technicians”, its approval (SPEC_APPROVED with version and hash, who and when), the why-trace of the build runs with RUN_SPEC_GEBUNDEN (which version), the commit trailers Spec:/Implements: and the run approvals. If needed, an admin creates an audit-ready bundle under /export that the auditor can verify independently with the offline verifier.

9. Transfer: your team wants to use routines so that a plan run happens every night and build runs every morning. Which three prerequisites do you put in place first?

   Model answer

   Example: (1) Budgets and token limits, because automation continuously generates costs (hard cap per tenant). (2) Quality gate set to blocking and approval before merge, so that nothing reaches the base branch unchecked. (3) Spec mode STRENG with approved specs, so that automatically planned work is bound to confirmed requirements. Also sensible: segregation of duties and a fixed time at which someone works through the approvals.

10. Summarize the guiding principle “You describe. The factory builds. You approve.” in your own words and assign at least two factory functions to each sentence.

    Model answer

    Describe: project definition and project wizard, specs with acceptance criteria, memory, guardrails. Build: plan and build runs with adapters, a branch per run, correction loop, quality gate, workflow layer. Approve: spec approval by MAINTAINER or higher, approval before execution and before merge with inline diff, segregation of duties, why-trace and signed audit chain as evidence. The core: the human is responsible for the what and the whether, the factory for the how — verifiably.