ApprovalFlow Agent Instructions

Use this file when an AI coding agent works on ApprovalFlow.

Authority Order

Read and follow sources in this order:

1. Assignment-faithful wording in docs/REQUIREMENTS.md
2. Approved Human Developer decisions in docs/REQUIREMENTS.md
3. docs/SCOPE.md (V1 baseline only)
4. Accepted decisions in ADR.md
5. docs/ARCHITECTURE.md
6. docs/planning/BASELINE_PLAN.md (frozen main) · docs/planning/V4_PLAN.md (current dev work; V2/V3 plans historical)
7. AGENTS.md
8. CLAUDE.md

An accepted ADR may clarify architecture. It may not weaken the assignment, weaken approved requirements, or make optional work mandatory.

On dev, docs/planning/V4_PLAN.md is the plan-of-record (Human-approved 2026-07-13); the assignment, requirements, and lecture teachings stay the top authority. main is frozen per M2 and governed by docs/planning/BASELINE_PLAN.md/docs/SCOPE.md. V2_PLAN.md and V3_PLAN.md are historical.

Scope

Build the smallest clear assignment implementation.

Keep exactly three business services:

• Workflow
• Decision
• Payment

NGINX, Redis, Dapr sidecars, Docker Compose, and the static UI are infrastructure.

Keep all assignment-mandatory F1-F10, M1-M18, and D1-D7 work. Keep the four D5 journeys, anti-cheese checks, at least two no-human approvals, Docker Compose, required Dapr capabilities, gateway and rate limiting, minimal UI, async processing, notification, payment consistency, idempotency, durable human pause/resume, deterministic ceiling safety, structured logs, clean provider failure, CI, tests, OpenAPI, README, and demo.

Also keep Human-approved mandatory gates:

• all-20 fixture conformance
• INV-1009
• INV-1014A/B
• INV-1015
• exact duplicate correction behavior
• trusted server-side human approver identity
• AI and browser input cannot authorize payment
• deterministic hard stops cannot be overridden by a human
• durable compensation visibility
• Payment validates trusted authority before any financial effect

N1-N5 and B1-B3 are deferred unless the Human Developer explicitly assigns them.

Minimum-Scope Rule

Do not add production infrastructure or speculative abstractions.

Do not add generic repositories, command buses, mediator libraries, saga frameworks, provider registries, plugin systems, workflow engines, generalized policy engines, custom dependency-injection containers, shared platform packages, extra services, extra endpoints, or extra state machines unless a current mandatory requirement needs them.

Prefer direct functions, one concrete implementation, narrow Dapr calls, one source of truth per state, one error shape, one configuration path, one audit record shape, one final notification record, one authority validation operation, and one verification command.

Do not call a simple durable pending record an outbox. The full transactional outbox is optional N3.

Safety Rules

• AI is advisory. Deterministic Python owns the final route.
• AI output cannot authorize payment.
• The real LLM-backed AI advisory provider must use a bounded Tool Call Agent Loop only inside the AI advisory layer.
• Do not add write tools, payment tools, approval tools, rejection tools, workflow mutation tools, or irreversible side-effect tools to the LLM tool registry.
• Do not let the LLM approve, reject, pay, create authority, enforce policy, mutate Workflow state, or bypass human approval.
• Do not give the LLM final route authority.
• Do not feed the full policy document into the LLM prompt as the main policy mechanism.
• Use read-only policy tools backed by deterministic Python policy code for policy facts.
• Keep the router deterministic.
• Keep human approval authority separate from AI advisory output.
• Do not encode all invoices as always requiring human approval.
• Browser input cannot authorize payment.
• Request-body approver_id cannot override the server-established approver identity.
• Human approval cannot override invalid invoice data, explicit policy rejection, exact duplicate, an auto-approval above the autonomy ceiling, stale version, invalid authority, or any deterministic hard stop. An escalated above-ceiling invoice is not a hard stop: it requires and may receive explicit human approval (Human-approved clarification, 2026-07-13).
• Human approval after AI_PROVIDER_ERROR is allowed only when deterministic checks succeeded and no hard stop applies.
• Decision creates trusted authority.
• Payment validates trusted authority before reservation or payment.
• Exact duplicates remain terminal, including linked corrections with the same exact fingerprint.
• Failed release after reservation remains visibly COMPENSATION_PENDING.

Task Execution

Work only on the assigned task. Do not start the next task early.

Use the skills available to you: invoke the relevant skill (planning, TDD, debugging, verification, code review) and announce it.

Before coding, present a short plan and surface every decision that needs making, with options and a recommendation. No silent decisions: if you are choosing, ask and wait for approval. Surface new decisions mid-task the same way.

Batch independent tool calls in one turn, and read only the relevant ranges of a file rather than reloading whole files.

For observable mandatory behavior, use strict TDD:

1. Add a focused failing test.
2. Capture RED evidence.
3. Implement the smallest change.
4. Capture GREEN evidence.
5. Refactor only while tests remain green.

Smoke verification is enough for Dockerfiles, static UI shell, simple configuration, Dapr wiring, health, OpenAPI, and documentation formatting.

A task is complete when the required behavior works, focused tests pass, required evidence exists, and the Human Developer can explain it.

Documentation Completion Gate

After each task or meaningful feature group is completed, update the project documents before the final handoff. The relevant PLAN file is a mandatory status target every time; V1 also uses the V1 project-status file when V1 status changes. Then do a targeted documentation sweep for every other file whose architecture, command, evidence, or demo wording is affected by the task.

Always check and update the relevant plan:

• docs/planning/V4_PLAN.md for dev work (BASELINE_PLAN.md governs the frozen main; V2/V3 plans are historical and stay unchanged)

Then check and update as applicable:

• README.md
• docs/ARCHITECTURE.md
• ADR.md and assigned ADR wording
• docs/RECORDING_SCRIPT.md
• evidence files under docs/evidence/

Keep the docs honest: mark what is complete, pending, deferred, planned, or future; distinguish current implementation from target architecture; remove stale references to renamed files or old commands. Do not edit assignment sources or docs/PRODUCT_DILEMMA.md unless explicitly assigned.

Refactoring Policy

Refactor as you go when it directly improves clarity, safety, or maintainability for the assigned task.

Keep refactoring small and close to the code being changed. Do not let refactoring expand the task.

Allowed refactoring during a task:

• extract small helpers
• rename confusing functions or variables
• remove duplication
• move cohesive logic into a focused module when tests already protect the behavior
• add short comments for non-obvious safety or assignment-scope decisions

Do not do broad refactors unless explicitly assigned.

Large refactors must be separate tasks or separate commits, with no intended behavior change and full regression tests.

When refactoring, preserve public API behavior, response shapes, route/status/state transitions, deterministic authority boundaries, and existing tests unless the test itself is intentionally updated.

Speed / Scope Rules

Work narrowly. Do not run broad repository checks before editing.

Before editing, inspect only the files listed in the prompt. If another file is needed, explain why before reading or modifying it.

Do not re-audit completed tasks. Do not re-read all docs unless scope is unclear or the task explicitly requires it.

Make the smallest change that satisfies the assigned task.

Command Style Rules

Prefer simple, separate shell commands.

Run verification commands one at a time.

Do not chain commands with &&, ;, pipes, command substitution, shell loops, or multiline scripts unless the Human Developer explicitly approves.

Do not create or run temporary scratchpad Python scripts from /private/tmp, agent scratchpad folders, or other generated temp paths.

If a complex diagnostic is truly needed, ask first and explain why simple commands are not enough.

Do not combine many commands into one long chained Bash command with &&, ;, pipes, command substitution, or multiline python3 -c unless the task explicitly needs it.

Use separate commands so the Human Developer and tool permissions can review each action clearly.

Good:

git status --short
tools/test.sh services/workflow/tests -q

Avoid:

echo "status" && git status --short && DIR=$(ls -td services/* | head -1) && cat "$DIR/app.py"

For diagnostics, run one command at a time and explain what each command checks.

Code Quality Rules

Write code for a human beginner/intermediate Python developer to read and explain.

Prefer simple, direct, explicit code over clever abstractions.

Use clear names, small functions, and straightforward control flow.

Document non-obvious decisions with short comments. Do not comment obvious code.

Follow normal cross-cutting practices where they are useful for the assigned task:

• logging
• validation
• configuration
• error handling
• testability
• maintainability

Do not add production-scale infrastructure, generalized frameworks, extra abstraction layers, or speculative scalability work unless the assigned task explicitly needs it.

Best practices should make the solution clearer and safer, not bigger or harder to understand.

Keep business authority explicit:

• AI may advise or extract evidence only.
• Deterministic code owns routing and policy enforcement.
• Payment authority must be trusted and server-created.
• Human approval cannot override deterministic hard stops.

Avoid fixture-specific hacks, hidden side effects, broad rewrites, and behavior changes hidden inside refactors.

Verification Budget

Use tools/test.sh as the canonical repo-local pytest command. It runs pytest through .venv/bin/python when available and falls back to python3; do not rely on globally installed pytest.

For all tests, run:

tools/test.sh

For focused tests, run:

tools/test.sh path/to/test_file.py
tools/test.sh path/to/test_file.py -q

The direct venv alternative is:

.venv/bin/python -m pytest -q

1. Run focused tests for the changed area first.
2. Run related service tests if the change touches shared behavior.
3. Run the full relevant pytest suite only before the final response.
4. Do not run Docker/Compose unless the task changes infrastructure, gateway, Dapr, browser UI behavior, or the prompt explicitly asks for it.

Git Rules

Do not stage. Do not commit. Do not push.

Reviews

The Human Developer reviews every task or meaningful feature group.

Independent review is required after any task that touches a safety-critical boundary: the deterministic routing/ceiling boundary, cross-service contracts, payment authority validation or reservation, the AI advisory layer, or the final integrated system. In V2 that maps to T3 (contracts boundary), T4 (Decision ledger/state machine), T5 (MAF advisory), Optional Task B (Payment/ETag reserve), and T7 (final integrated gate).

Do not require independent review after every small task.

Documentation Ownership

Agents may edit docs/REQUIREMENTS.md, docs/SCOPE.md, docs/ARCHITECTURE.md, docs/planning/BASELINE_PLAN.md, AGENTS.md, CLAUDE.md, and assigned ADR wording when explicitly asked. Agents may edit README.md during implementation.

Preserve the Human Developer's actual ADR decisions. Do not silently add, remove, or change a decision.

Do not edit docs/PRODUCT_DILEMMA.md unless the Human Developer explicitly assigns that file.

Git and Boundaries

Do not commit, push, merge, or create pull requests without Human Developer authorization.

Do not edit assignment sources.

Do not change implementation code outside the assigned task.

Stop when the assigned task is complete. Do not add polish, optional refactoring, production hardening, extra endpoints, extra tests, or more documentation unless explicitly assigned.