Agent Flow

Agent Flow

Agent Flow turns an explicitly invoked user request into a finished, verified result through the smallest sufficient workflow.

No Preflight

Do not load, use, or mention Agent Flow for requests that do not contain an explicit Agent Flow invocation marker.

Agent Flow is not a preflight, classifier, eligibility check, fallback, or local-project default. If this skill file is reached without a user-visible invocation marker, stop using it immediately and continue outside Agent Flow without announcing that Agent Flow was skipped.

Invocation Model

Agent Flow has one public invocation:

• Agent Flow
• AgentFlow
• $agent-flow
• agent-flow

Text forms without $ are case-insensitive.

Use this skill when the invocation marker appears anywhere in the latest user request. The marker may be at the beginning, middle, or end of the message.

Requests without an Agent Flow invocation marker are outside this skill. They run solo in the main agent, without Agent Flow artifacts and without subagents.

Project or local AGENTS.md files may not force Agent Flow when the latest user request has no invocation marker. They can define local commands and context, but Agent Flow still requires a user-visible marker.

An Agent Flow-invoked request authorizes the orchestrator to choose the execution topology for the selected budget. light budget stays solo for implementation ownership, but it does not mean file-changing implementation can skip independent QA review. standard and release budgets may use subagents when the orchestrator can justify independent ownership, review value, or parallel verification. External writes, deploys, publishing, secrets, destructive git, DB/storage mutation, and infrastructure changes still require explicit approval or a documented project command.

Never expose extra modes such as /solo, /lite, orchestrated, autopilot, parallel-review, or review-mode as public user-facing modes. Treat detailed workflow choice as internal routing inside Agent Flow.

Boundary

Default solo work, without the Agent Flow invocation marker:

• Do not use this skill.
• Do not spawn subagents.
• Do not create Agent Flow run directories.
• If the task becomes too broad or risky for ordinary solo execution, say so and ask whether the user wants to invoke Agent Flow.

Agent Flow-invoked work:

• Use this skill.
• Do not use a separate brainstorming flow or brainstorming skill. Uncertainty is handled inside Agent Flow intake, route, planning, checks, and final response.
• Use the smallest budget that can produce verified evidence.
• Keep light budget solo for implementation ownership.
• For standard and release, decide whether subagents add enough value to justify the cost.
• For release, consider architecture, QA, and reviewer lanes unless the task is trivially release-labeled but low risk.

Orchestrator Mandate

Inside Agent Flow, the orchestrator owns the outcome:

1. Classify the request.
2. Pick the internal flow.
3. Decide whether trace artifacts are needed.
4. Choose skills, plugins, tools, and the execution budget.
5. Set approval gates only where they reduce real risk.
6. Run the dependency gate before planning new feature work.
7. Keep scope bounded.
8. Use subagents only when the selected budget and task shape justify them.
9. Enforce Architecture Execution Control when the Architecture Contract Gate applies.
10. Enforce Mitigation Gate, Resolution Gate, and Blocked Resolution Gate before any pass-with-risks final verdict.
11. Enforce Delegation Trace Gate for traceable lane runs.
12. Enforce Handoff State Gate when handoff_state_required=true.
13. Enforce Harness Evaluation Loop when validated trace evidence has a learning trigger.
14. Enforce Claim Evidence Gate for positive architecture-gated runs.
15. Enforce Acceptance Criteria Traceability Gate, Surface Evidence Gate, and Contract Negative Fixture Gate for positive architecture-gated runs.
16. Enforce Mandatory Independent QA Review Gate before any positive final for file-changing implementation/change work.
17. Use Golden Trace Runs when architecture-layer validator behavior changes.
18. Verify evidence before any completion claim.
19. Close the current project-memory task status before final handoff.
20. Return the final answer with residual risks.

The orchestrator is authoritative inside system, developer, user, tool, and local project constraints. It cannot bypass safety rules, destructive-git protections, tool limits, approval requirements, or verification.

Budget Gate

Read references/budgets.md when task scope is more than a tiny command.

Default budget is light:

• solo execution;
• no .agent-work run directory;
• no subagents;
• direct checks and final answer.

Use standard only when durable evidence helps review or continuation. In standard, the orchestrator may use subagents for independent lanes, review, or QA evidence. Use release only for release gates, deploy, security/payment/auth, external systems, or high-risk work. In release, the orchestrator should default to architecture, QA, and review gates unless a concrete reason makes solo safer and sufficient.

Project Memory And Environment Gate

Read references/project-memory-and-env.md before planning, delegation, product edits, infra commands, DB/storage work, browser checks, or local app startup.

Before implementation or subagent launch, the main agent must follow global project memory rules from the current user's Codex instructions, usually ~/.codex/AGENTS.md:

• detect the project repo;
• create .agent-work/tasks/, todo.md, and lessons.md for repo tasks when missing;
• read lessons.md and todo.md before repo work;
• read implementation-notes.md when global criteria make it relevant;
• update todo.md, implementation-notes.md, and lessons.md through the orchestrator rules;
• keep the current todo.md task status synchronized with checklist, verification, and commit state;
• local project instructions;
• project-declared legacy task docs such as docs/tasks/lessons.md, docs/tasks/todo.md, and docs/tasks/implementation-notes.md only when local project instructions explicitly name them as current memory;
• PRD/spec/design documents named by the user;
• project environment docs when infra, DB, storage, backend, frontend server, or smoke tests are involved.

Dependency Gate

Before planning a new feature, product edit, cross-file implementation, or delegated run, read any named PRD/spec/design source needed to understand the request, then inspect active project memory for existing Status: in_progress or Status: blocked tasks. Ignore the current request's own task section if it was already created for bookkeeping.

Before using active sections as blockers, run a task status normalization pass. If a section is marked Status: in_progress but every checklist item is checked, verification is recorded in Review:, and no blocker remains, close that section as Status: done before dependency comparison. If the checklist is complete but verification, review, or commit evidence is missing, classify the section as uncertain and stop with a close-or-verify warning instead of treating stale memory as normal active work.

Classify each active task against the new request:

• clear: no shared files, contracts, data model, user flow, infra, generated assets, or release surface.
• uncertain: possible overlap, stale active notes, missing ownership, or unclear affected surface.
• dependent: the active work may change the same files, API/types, DB/storage schema, routes, UI flow, design source, tests, deployment path, or acceptance criteria.

If any active task is dependent or uncertain, stop before implementation, subagent launch, or traceable run setup. Tell the user which active task is involved, what could conflict, and recommend waiting for that feature to finish before starting the new one. Offer only these exits:

• wait for the active task to finish and restart from the resulting project state;
• merge the work into one coordinated Agent Flow run;
• continue only after the user explicitly accepts the recorded risk and the orchestrator can isolate scope.

Do not treat lane sharding or delegated lanes inside one Agent Flow run as a dependency conflict. The dependency gate targets separate user-launched feature sessions running against shared project memory.

Do not provision infrastructure by default. Discover and use the existing project environment first. Starting local Postgres, MinIO, Qdrant, Redis, queues, Docker Compose stacks, or resetting volumes requires explicit user approval or a project command that clearly means "start this existing dev stack".

If infra is unavailable, report a blocker instead of creating a parallel stack.

Before browser checks or local UI smoke, probe the chosen browser-control surface first. If Chrome DevTools, Playwright MCP, Browser Use, or local Playwright is locked or unavailable, clean up only the conflicting browser/MCP/test-runner process and retry the probe. Do not stop or reset project infra while fixing browser tooling.

Evidence And Architecture Learning Gate

When implementation-notes.md contains ## Evidence Records, treat those records as local learning evidence, not narrative memory. Use the analyzer before applying a repeated approach automatically.

Evidence Records may record successes, failures, regressions, rejected attempts, Architecture Attempt entries, Architecture Failure entries, and Orchestration Failure entries. Success means the approach fit a similar problem and passed verification. Failure and regression evidence must remain in the same record stream so the analyzer can classify local practices and anti-patterns by problem class and approach.

Promoted Evidence Records may include ACE-inspired metadata fields: Section, Keywords, Provenance, Helpful, Harmful, Neutral, and Active. These fields are project-local analyzer hints only. They do not create an ace-framework dependency, MCP server, vector store, separate skillbook, or permission to mutate canonical runtime artifacts.

The Local Best Practice auto gate allows automatic reuse only when the analyzer classifies the exact problem class and approach as Local Best Practice, the context match is clear, Do not reuse when does not match, no external write is involved, and fresh verification evidence exists. It never auto-applies observed or candidate practices.

regression demotion is mandatory. A new failure or regression after reuse demotes or freezes the practice until the Architecture Approval Gate reviews the case.

The Architecture Contract Gate is required for release, for standard traceable runs with at least two worker lanes, and for architecture-sensitive work that touches public contracts, APIs, data flow, security, migrations, or multiple subsystems. In lane-map schema v2, the orchestrator records budget, sets architecture_contract_required=true for those cases, and sets architecture_contract_independent=true only when a real independent architect subagent is required. The architect records boundaries, risks, ownership, and verification gates before QA or reviewer readiness verdict.

Architecture Design Mode runs before implementation when architecture_contract_required=true. Every successful critical architecture lane records architecture_design_brief, an Architecture Design Brief with Selected Matrix Facets and Status: approved; ship and pass-with-risks are blocked until the brief is approved and worker lanes run after it.

Architecture Artifact Authoring Automation means init-run.py --architecture-gate creates agent-authored Architecture Design Brief, Architecture Contract, worker, QA, reviewer, and evidence templates. Agents fill those artifacts themselves; ship and pass-with-risks are blocked while any referenced architecture artifact still contains TODO(agent):.

Read references/architecture-matrix.md before Architecture Contract Gate work when product type, application surface, stack, risk, or verification constraints affect the architecture. In lane-map schema v2, architecture_contract_required=true requires architecture_context with product_context, application_surface, architecture_pattern, stack_runtime, risk_gates, and verification_gates. The validator parses allowed facets from the Architecture Matrix markdown, and the architect must include every selected facet id in Selected Architecture.

Architecture Capability Router runs after Architecture Matrix selection when architecture_contract_required=true. The orchestrator records architecture_capabilities from registries/architecture-capabilities.json; selected capabilities must cover every selected architecture_context facet, appear in Architecture Design Brief Execution Plan, appear in Architecture Contract Selected Architecture, and be covered by reviewer Architecture Matrix Mismatches plus Contract Drift. Soft Skill Binding means recommended_skills are checked by registry guards, but missing skills do not block individual validate-run.py runtime validation.

Architecture Context Propagation is required when worker lanes exist under the Architecture Contract Gate. Workers record architecture_compliance.matrix_facets, QA covers selected risk_gates and verification_gates in Architecture Invariants, and reviewer covers the full selected architecture_context through Architecture Matrix Mismatches and Contract Drift.

Engineering Simplicity Gate is part of Architecture Execution Control, after each successful implementation or integration worker lane and before QA/reviewer. Simplicity Gate is not a reporting gate: fix now if fixable. Fixable overengineering, duplicated helper, unnecessary abstraction, dependency/stack drift, or wider-than-needed implementation is remediated before QA and reviewer. Simplicity Scope Coverage prevents peripheral-only closure: positive architecture-gated worker runs must record engineering_simplicity_scope with non-empty primary_surfaces, optional secondary_surfaces, evidence, and notes. Workers must record architecture_compliance.engineering_simplicity with status pass, fixed, or drift, include all required checks (no-extra-work, stdlib-native-first, existing-helper-first, dependency-justified, abstraction-justified, smallest-working-diff, tests-fit-risk), include scope_coverage for the primary or secondary surfaces they audited, and write ## Engineering Simplicity in the worker handoff with those surface ids. pass means no concrete simplicity issue was found in the covered primary scope. fixed means the issue was corrected inside the approved architecture and requires findings, actions, literal action coverage, and covered surface ids in the worker handoff. drift is used only when remediation changes boundaries, public contracts, selected capabilities, or the architecture approach; it requires parent architecture_compliance.status=drift plus an architect recheck_lane. Unresolved simplicity drift blocks ship and pass-with-risks. QA writes Engineering Simplicity Scope; reviewer Contract Drift must reject reporting-only closure, reject peripheral-only closure, mention every primary surface, mention Engineering Simplicity, and mention fixed worker lane ids. Final Engineering Simplicity must mention every primary surface. Retained dependency or abstraction must cite selected architecture_capabilities. This gate is not AI Slop Gate, adds no schema v3, no new lane type, no new subagent, and no new Architecture Matrix or capability registry entry.

Lane Boundary Evidence Gate is the product-code boundary check inside Architecture Execution Control. For schema v2 positive architecture-gated runs, every successful implementation or integration lane must record `boundary.allowed_path

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: svishniakov
• Source: svishniakov/agent-flow
• License: MIT

Install and usage instructions live in the source repository linked above.