amlog-workflow

Agentic SDLC workflow toolkit — installs role-specific AI agents and a CodeGraph knowledge base into any workspace, in one command.

Table of contents

• What is amlog?
• Installation
• Quick start
• Upgrading from a pre-native install
• CLI reference
• Updating
• Uninstalling
• Diagnostics
• Multi-zone repos
• Agent roster
• How agents work
• Automatic agent routing
• Handoff automation & loop guard
• Skills
• Agent flow: the full cycle
• Human-in-the-loop gates
• Self-improvement: agent history & retrospectives
• QA verdict model
• Implementation plan as an issue comment
• Status
• Requirements
• License
• Contributing

What is amlog?

amlog is a CLI that installs a curated set of role-specific AI agents natively into whichever AI coding tool(s) you use, alongside a live code-knowledge graph. Each agent is defined once in a shared registry (registry/) and converted into the exact subagent format each tool expects — no copy-pasting definitions between tools, no format mismatches, and no hand-maintained prose roster in AGENTS.md/CLAUDE.md.

In short, one command gives your AI coding assistant(s):

• A set of specialized subagents tuned to your role (planner, implementor, reviewer, test writer, etc.), each with its own scoped instructions and tool access.
• A CodeGraph index of your codebase, so agents can look up real call paths and symbol definitions instead of guessing from context.
• Companion shell scripts for agents that need to run something concrete (SonarQube scans, test suites, git/PR automation, headless browser verification, etc.).
• A Skills layer of reusable, self-updating knowledge (framework conventions, tool usage) shared across agents instead of duplicated in each one.
• Built-in human-in-the-loop gates at the points that matter most, and per-agent self-improvement history so lessons from one issue carry into the next.

Agents are organized by SDLC role:

| Role | Agents included | |---|---| | --frontend | planner, implementor (Angular), browser-launcher + all dev agents | | --backend | planner, implementor (.NET), test-runner + all dev agents | | --qa | test-generator, test-executor, bug-triage, plus the optional api-contract-tester (back-end changes) and e2e-tester (front-end changes) | | --ba | story-writer, github-manager-ba | | --all | everything above |

dev agents (researcher, security-review, code-quality, review, github-manager, knowledge-base-setup) are cross-cutting and get pulled in automatically alongside --frontend, --backend, or --all.

And installed for whichever tool(s) you pick:

| Tool | Flag | Native location | Format | |---|---|---|---| | Claude Code | --claude | .claude/agents/<name>.md | Markdown + YAML frontmatter | | Codex | --codex | .codex/agents/<name>.toml | TOML | | OpenCode | --opencode | .opencode/agent/<name>.md | Markdown + YAML frontmatter | | Antigravity | --antigravity | .agents/agents/<name>/AGENT.md | Markdown + YAML frontmatter |

You can select more than one tool at once (--claude --codex), and installing for a new tool later never re-copies or duplicates agents already installed for another — each tool gets its own native files, tracked independently in .amlog/state.json.

Note on name collisions: a few agent names (e.g. planner-amlog, implementor-amlog) exist under more than one role (fe and be). Because each native tool folder is flat (one file per name), amlog automatically suffixes the installed filename with the role whenever both are selected together — e.g. planner-amlog-fe.md and planner-amlog-be.md side by side, each with a matching unique name: in its frontmatter so the host tool never sees a duplicate. You'll only see the plain <name>.md when there's no collision for the roles you installed.

Every install also bootstraps CodeGraph so agents have a real, queryable knowledge graph of your codebase from day one.

Installation

Step 1 — Install the CLI (once per machine)

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/selise/amlog-agentic-workflow/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/selise/amlog-agentic-workflow/main/install.ps1 | iex

# Already have Node.js 18+?
npm i -g amlog-workflow

# Or run without installing
npx amlog-workflow

Requires Node.js 18+ — Node is needed for the npm install path. The curl/irm scripts also install via npm under the hood.

Confirm it's on your PATH:

amlog -v

Step 2 — Pick your role

Run this from the root of the repo you want agents installed into:

cd my-project

amlog install --frontend   # Angular developer
amlog install --backend    # .NET developer
amlog install --qa         # QA engineer
amlog install --ba         # Business Analyst
amlog install --all        # Everyone / every role

Prefer explicit control over which agent types get pulled in? Use --target instead of a role shorthand:

amlog install --target fe,qa

Step 3 — Pick your tool(s)

Add one or more tool flags to the same command, or omit them entirely to get an interactive multi-select prompt:

amlog install --frontend --claude                # Claude Code only
amlog install --frontend --claude --codex        # Claude Code + Codex, in one pass
amlog install --backend --tools=opencode,antigravity

That's it. After this command:

• Agents are installed natively into each selected tool's own folder (see the table above) — the tool discovers and invokes them itself, no extra wiring needed.
• Companion scripts some agents ship with live in .amlog/scripts/<agent-name>/ (gitignored), referenced by relative path from the agent's instructions.
• A small .amlog/state.json (also gitignored) tracks which roles/tools are installed, so amlog status, amlog update, and amlog uninstall know what to manage.
• CodeGraph is installed and your codebase is indexed.
• .amlog/, .codegraph/, and .knowledge-graph/ are added to your .gitignore automatically.

Quick start

The fastest path for a brand-new workspace, installing everything for Claude Code:

npm i -g amlog-workflow
cd my-project
amlog install --all --claude --yes

Or skip every flag and just run amlog with no arguments — it walks you through role and tool selection interactively:

amlog

Once it finishes, check what landed:

amlog status

Upgrading from a pre-native install

Older versions of amlog installed every agent as generic markdown under a shared .amlog/agents/<type>/<name>/ tree, and embedded the roster as prose into AGENTS.md/CLAUDE.md. If your workspace still has that layout, the next amlog install or amlog update you run will detect it automatically, show you exactly what it's about to remove, and (after a confirmation, unless you pass --yes):

• Delete the old .amlog/agents/ tree.
• Strip just the <!-- amlog:start --> … <!-- amlog:end --> section it added to your instruction file, leaving everything else in that file untouched.

Nothing else changes — run the command with your usual role + tool flags right after, and agents get installed the new, native way.

CLI reference

amlog                          Interactive installer (prompts for role, then tool)
amlog install [flags]          Install agents natively for the selected tool(s) + bootstrap knowledge base
amlog update [flags]           Refresh installed roles/tools to latest definitions
amlog uninstall [flags]        Remove agents (and optionally the knowledge base) from this workspace
amlog upgrade [version]        Update the amlog CLI itself
amlog list                     Show every agent in the registry, with type/stage
amlog status                   Show installed agents (by tool + role) + CodeGraph index status
amlog doctor                   Diagnose the local environment + detect a legacy .amlog/agents/ install
amlog handoff <action>         Agent handoff loop guard: check | record | reset | status
amlog -v, --version            Print installed CLI version
amlog -h, --help               Show help (also works per-subcommand, e.g. `amlog install --help`)

amlog install

Installs agents into the current workspace and bootstraps CodeGraph. Any role/tool flag can be omitted — you'll be prompted interactively for whichever piece is missing.

| Flag | Description | |---|---| | --frontend | Shorthand for --target=fe,dev | | --backend | Shorthand for --target=be,dev | | --qa | Shorthand for --target=qa | | --ba | Shorthand for --target=ba | | --all | All roles | | --target <csv> | Explicit types: fe,be,qa,ba,dev | | --claude | Install native Claude Code subagents (.claude/agents/) | | --codex | Install native Codex subagents (.codex/agents/) | | --opencode | Install native OpenCode subagents (.opencode/agent/) | | --antigravity | Install native Antigravity subagents (.agents/agents/<name>/AGENT.md) | | --tools <csv> | Explicit tool ids: claude,codex,opencode,antigravity | | --yes | Skip all confirmation/interactive prompts | | --location <scope> | Where CLI config lives: global | local (default: global) | | --auto-handover / --no-auto-handover | Write auto_handover: true / false to .amlog/amlog-workflow.config.json without prompting (see Handoff automation). Without either flag, install asks once and keeps any value already set. |

Role flags and tool flags combine freely — e.g. amlog install --backend --qa --claude --codex installs both roles for both tools in one pass.

amlog update

Re-resolves whichever roles/tools are already recorded in .amlog/state.json and re-pulls the latest agent definitions for them — no flags needed for the common case.

| Flag | Description | |---|---| | --yes | Skip confirmation prompts |

amlog uninstall

Removes every agent recorded in .amlog/state.json from its native tool location(s), then clears the state file.

| Flag | Description | |---|---| | --keep-knowledge-base | Remove agents only, keep .codegraph/ and .knowledge-graph/ | | --yes | Skip confirmation prompts |

amlog upgrade [version]

Updates the amlog CLI itself (not the agents in a given workspace). Pass a specific version to pin to it; omit it to move to latest.

amlog list

Prints every agent in the registry with its name, type, and stage — useful for picking a --target value or just seeing what's available before installing.

amlog status

Shows installed agents grouped by tool then role, whether CodeGraph is wired for each installed tool, and live CodeGraph index stats (files, symbols, edges) per zone.

amlog doctor

Diagnoses the local environment: Node.js version and platform, the resolved CodeGraph command/path (and whether it's reachable and wired for each installed tool), which agent-instruction file was detected (AGENTS.md / CLAUDE.md / GEMINI.md / CURSOR.md), whether .amlog/state.json exists, whether the agent routing section is present, the effective auto_handover / max_handoff_repeats settings, and whether a legacy .amlog/agents/ tree still needs migrating. Run this first when something looks off after install.

amlog handoff <action>

The loop guard agents (or the orchestrating session) call before passing work to another agent. It's meant for agents to call, not people, so its output is plain KEY: value lines. See Handoff automation & loop guard.

| Action | What it does | |---|---| | check --issue <n> --from <agent>/<type> --to <agent>/<type> | Prints DECISION: PROCEED (auto handover on), CONFIRM (ask the user first) or ASK_HUMAN (loop limit reached), plus the earlier attempts for that pair | | record --issue <n> --from … --to … --reason "…" | Appends the handoff to .amlog/handoffs/<n>.log. Add --human-approved after a human OKs going past the loop limit; that restarts the count for the pair. | | reset --issue <n> [--from … --to …] | Restarts the count for one pair, or for every pair of the issue | | status [--issue <n>] | Shows the effective settings and, with --issue, the current count per pair |

Updating

# Update agents in this workspace to the latest definitions
amlog update

# Update the amlog CLI itself
amlog upgrade
amlog upgrade 1.2.0   # pin to a specific version

Uninstalling

# Remove agents and knowledge base from this workspace
amlog uninstall

# Remove agents only (keep the CodeGraph index)
amlog uninstall --keep-knowledge-base

Uninstall also strips the amlog routing section from CLAUDE.md / AGENTS.md, and deletes the file if that section was all it contained.

Diagnostics

If /agents (or your tool's equivalent) doesn't show what you expect after install, or CodeGraph doesn't seem to be wired up, run:

amlog doctor

and check amlog status for a full breakdown of what's actually recorded as installed. Both commands are read-only and safe to run anytime.

Multi-zone repos (frontend + backend in one repo)

amlog install creates .amlog/amlog-workflow.config.json for every install (existing values are kept; only missing keys are added). Edit its zones to tell amlog (and CodeGraph) how to index each zone independently:

{
  "adapter": "codegraph",
  "zones": {
    "frontend": "./frontend",
    "backend": "./backend",
    "database": "./database"
  },
  "businessDocs": "./docs/business",
  "output": "./.knowledge-graph"
}

A fresh install lists frontend, backend, database and qa under zones (qa defaults to ./e2e-full-cycle, the rest are null). Set a path (e.g. "frontend": "./frontend") to enable a zone; null zones are ignored, and with none set the repo root is indexed. When amlog install finds ≥2 candidate zone directories, it offers to fill zones in for you interactively.

Agent roster

| Name | Type | Stage | Has script | Skill | Human-in-the-loop | |---|---|---|---|---|---| | knowledge-base-setup | dev | platform | ✅ setup-knowledge-base.sh | — | — | | story-writer-amlog | ba | ba | — | — | ✅ BA must confirm AC + story | | github-manager-ba-amlog | ba | ba | — | — | — | | github-manager-amlog | dev | cross-cutting | ✅ commit-and-pr.sh | — | ✅ Always creates instructions.md; commits and PR branches need explicit approval | | researcher-amlog | dev | planning | — | — | — | | security-review-amlog | dev | build | — | — | — | | code-quality-amlog | dev | build | ✅ run-sonarqube.sh | — | — | | review-amlog | dev | build | — | — | — | | planner-amlog | fe | planning | — | angular, react | ✅ Developer must confirm the plan | | implementor-amlog | fe | build | — | angular, react | — | | browser-launcher-amlog | fe | build | — | webapp-testing | ✅ Human verifies the UI visually | | planner-amlog | be | planning | — | dotnet | ✅ Developer must confirm the plan | | implementor-amlog | be | build | — | dotnet | — | | test-runner-amlog | be | build | ✅ run-affected-tests.sh | — | — | | test-generator-amlog | qa | qa | — | qa-scope | ✅ Tester must add edge/corner cases | | test-executor-amlog | qa | qa | ✅ run-test-suite.sh | qa-scope | — | | api-contract-tester-amlog | qa | qa | ✅ run-contract-tests.sh | api-contract-testing, qa-scope | — (optional: runs only when the back end changed) | | e2e-tester-amlog | qa | qa | ✅ run-e2e.sh | e2e-testing, webapp-testing, qa-scope | — (optional: runs only when the front end changed) | | bug-triage-amlog | qa | qa | ✅ bug-index.js | bug-triage, qa-scope | ✅ Human approves filing the drafted bugs on GitHub |

Run amlog list anytime to see this same roster pulled live from the registry.

kb-updater-amlog and kb-curator-amlog (knowledge-base proposal/curation agents, both ba/dev platform-stage) are documented in AGENTS.md as part of the intended full roster but aren't built yet — the github-manager-amlog handoff that references kb-curator-amlog is a forward reference, not a broken one.

How agents work

Each agent is defined once in the shared registry (registry/agents/<type>/<agent-name>/agent.md) as a markdown file with YAML frontmatter (name, type, stage, description, tools, and optionally skills) — the source of truth amlog converts from. Example:

---
name: implementor-amlog
type: fe
stage: build
description: Implements the planned front-end changes.
tools: [Read, Write, Edit, Bash, mcp__codegraph__codegraph_explore]
skills: [angular]
---

Tool names must match the target CLI's exact spelling. For Claude Code, native tools are capitalized (Read, Write, Edit, Bash, WebSearch, WebFetch) — a lowercase read/write/etc. is silently invisible to the subagent. MCP tools use mcp__<server-id>__<tool-name> for one specific tool, or the bare mcp__<server-id> to grant every tool a server exposes (used for mcp__github on the GitHub-manager agents and mcp__figma on the frontend planner/implementor, both of which need many tools from those servers). <server-id> must match the id the MCP server is actually registered under in your workspace — adjust it if yours differs from github/figma.

amlog install converts that definition into each selected tool's own native format and folder (see the table in What is amlog?), so the tool discovers and can invoke it itself — no manual @-referencing needed. Exact invocation syntax is each tool's own (check its docs); roughly:

# Claude Code — auto-discovers .claude/agents/*.md as project subagents
claude "delegate this to implementor-amlog"

# Codex — auto-discovers .codex/agents/*.toml
codex "spawn implementor-amlog to build this"
# Claude Code — auto-discovers .claude/agents/*.md as project subagents
claude "delegate this to implementor-amlog"

# Codex — auto-discovers .codex/agents/*.toml
codex "spawn implementor-amlog to build this"

# OpenCode — auto-discovers .opencode/agent/*.md
opencode run --agent implementor-amlog "..."

# Antigravity — auto-discovers .agents/agents/<name>/AGENT.md
agy --agent implementor-amlog "..."

Any companion shell script an agent ships with (e.g. run-test-suite.sh) is copied to .amlog/scripts/<agent-name>/ once per workspace, and every native agent file references it there — regardless of which tool(s) you installed for.

Handoffs are explicit, not inferred. Every agent's ## Handoff section lists the exact next agent(s) per condition, and asks the model to act on it immediately rather than just describing it. Claude Code and OpenCode can invoke a project subagent directly, so on those tools the handoff usually just happens. Codex doesn't auto-chain subagents the same way — today, moving from one Codex agent to the next depends on a human (or the parent session) noticing the handoff and re-invoking (codex "spawn implementor-amlog to build this"). To make that impossible to miss, every agent ends its final message with a line like:

NEXT AGENT: implementor-amlog (fe) — implement confirmed plan docs/42/plan.md

If your tool doesn't auto-chain, watch for that line and act on it — that's the signal a handoff didn't happen automatically.

Whether that handoff then happens without asking you depends on auto_handover, and every handoff goes through a loop guard first. See Handoff automation & loop guard.

Automatic agent routing

You don't need to name an agent. amlog install / amlog update writes a marker-fenced routing section (<!-- amlog:router:start --> … <!-- amlog:router:end -->) into the instruction file each installed tool reads at the start of every session:

| Tool | File | |---|---| | Claude Code | CLAUDE.md. Skipped if CLAUDE.md already imports @AGENTS.md and AGENTS.md gets the section anyway. | | Codex, OpenCode, Antigravity | AGENTS.md |

The section tells the main session to match every request against a routing table built from the agents actually installed (each agent's triggers in registry/manifest.json) and delegate on its own. It also carries a few rules that go beyond the table:

• pick fe vs be from the paths, labels or code the task touches
• resume an issue from whatever its docs/<issue-number>/ files show is done
• always send a new feature to the planner before the implementor
• handle anything that doesn't match (questions, explanations, one-line tweaks) directly, without an agent

So "we need a CSV export on the orders page" goes to story-writer-amlog, "let's work with #42" goes to github-manager-amlog, and "run the tests for my change" goes to test-runner-amlog. The session announces each pick in one line (→ Routing to …).

Each agent's frontmatter description also ends with a "Use when…" clause. Tools that auto-delegate to subagents from their description (Claude Code, OpenCode) pick the right agent even outside the routing table.

The routing text itself lives in registry/router/ROUTER.md. Edit it there, never in a workspace's CLAUDE.md / AGENTS.md, because amlog update rewrites the section.

Handoff automation & loop guard

Two settings in .amlog/amlog-workflow.config.json control agent-to-agent handoffs:

{
  "auto_handover": false,
  "max_handoff_repeats": 3
}

| Key | Default | Effect | |---|---|---| | auto_handover | false | true: agents hand off to the next agent with no confirmation. false: you're asked Hand off to <agent>? (yes / no) before each handoff. | | max_handoff_repeats | 3 | When the same handoff (same from-agent, same to-agent, same issue) comes up for the 3rd time, the chain stops and a human is asked, whatever auto_handover says. |

amlog install asks for auto_handover once (or takes --auto-handover / --no-auto-handover). To change it later, edit the file; agents read it at every handoff.

auto_handover: true never skips a mandatory human gate. See Human-in-the-loop gates. The AC confirmation, the instructions file, the plan review, the visual UI check, tester edge cases, and commit/PR approval all still wait for you.

Loop guard. Every handoff is logged to .amlog/handoffs/<issue-number>.log (the story name is used before an issue exists). Before handing off, the agent or orchestrating session runs amlog handoff check. Agents without a shell count the log by hand using the same rules. Say implementor-amlog (be) → test-runner-amlog (be) is about to happen for the 3rd time on issue #42, meaning the tests failed twice already. Instead of looping, the agent stops with:

HUMAN INPUT REQUIRED: loop limit — implementor-amlog (be) -> test-runner-amlog (be) for issue 42 would be attempt 3. <what keeps failing>. Reply "continue" to hand off again, or say what to change.

It lists the earlier attempts alongside that line. Reply "continue" and the handoff is recorded as human-approved, which restarts the count for that pair. Or give different direction. amlog handoff status --issue 42 shows where each pair stands.

The shared rules every agent follows live in one skill, .amlog/skills/handoff-protocol/SKILL.md, and not in 15 copies. Agents signal the orchestrating session with two standard final lines: NEXT AGENT: … means a handoff is ready, and HUMAN INPUT REQUIRED: … means the agent is stopped at a gate or at the loop limit.

Skills

A skill is reusable knowledge factored out of individual agents so the same agent stays generic across frameworks and languages instead of hardcoding "Angular" or ".NET" into its own instructions. Skills live in registry/skills/<id>/SKILL.md and are copied into .amlog/skills/<id>/ once per workspace — shared by every agent that references it, the same way companion scripts are shared.

| Skill | Used by | What it covers | |---|---|---| | angular | planner-amlog (fe), implementor-amlog (fe) | Component/module structure, API data flow, NgRx/signals state, naming/barrel conventions, ng build/ng lint verification | | react | planner-amlog (fe), implementor-amlog (fe) | Component/hook structure, API data flow via existing data-fetching layer, Redux/Zustand/Context state, naming/folder conventions, build/lint/test verification | | dotnet | planner-amlog (be), implementor-amlog (be) | Layered architecture (Controllers/Services/Repositories/DTOs), API contract, FluentValidation, dotnet build/dotnet test verification | | handoff-protocol | every agent that hands off | Process skill, not codebase knowledge: the loop guard, auto_handover, the mandatory human gates, and the NEXT AGENT: / HUMAN INPUT REQUIRED: final lines. Agents never self-edit it. | | qa-scope | every qa agent | Process skill: which optional tester applies (detect-scope.js → .amlog/qa/scope.json), the QA chain order, and the standard .amlog/qa/<name>-report.json schema every tester writes. Agents never self-edit it. | | api-contract-testing | api-contract-tester-amlog (qa) | Finding the contract (OpenAPI → code → front-end consumer → AC), the per-endpoint checklist (status, schema, validation, auth/IDOR, boundaries, idempotency), .NET test conventions, breaking-change rules, fuzzing | | e2e-testing | e2e-tester-amlog (qa) | Choosing journeys from the AC, stable selectors, deterministic waits and test data, console/network + accessibility + responsive checks, flake control, failure evidence | | bug-triage | bug-triage-amlog (qa) | Failure classification (product bug / test bug / contract drift / environment / flaky), severity + priority rubric, root-cause localisation, minimal repro, de-duplication, the bug report template | | webapp-testing | browser-launcher-amlog (fe), e2e-tester-amlog (qa) | Playwright-driven headless browser verification — adapted from Anthropic's official webapp-testing skill (Apache-2.0; see registry/skills/webapp-testing/THIRD_PARTY_NOTICE.md) |

Both angular and react are installed for every fe agent, but only one is applied per run: planner-amlog/implementor-amlog detect the target codebase's framework (via package.json dependencies or file extensions) and load the matching skill, so the same agent works unmodified against either stack.

Skills are self-updating, not static. Before applying a skill's guidance, planner-amlog/implementor-amlog check what they actually observe in the codebase (via codegraph_explore) against what the selected skill file says, and correct that skill file in place — additively, never a full rewrite — when the team's conventions have drifted. A skill stays current without anyone having to maintain it by hand.

Agent flow: the full cycle

This is not a linear pipeline. Every build-stage gate can bounce work back to an implementor, and dev-side self-verification (browser/test-runner → security → quality → review) runs as a track parallel to QA (test-generator → optional api-contract-tester / e2e-tester → test-executor, with bug-triage catching every failure) — both converge on github-manager-amlog before merge. github-manager-amlog itself appears twice below because it's invoked at two different points in the cycle (kicking off work, and again at PR time) — it's one agent, not two.

The image above is a static render for viewers that don't support Mermaid (npmjs.com's package preview, some IDEs/editors). On GitHub, expand the block below to see and edit the live Mermaid source it was generated from — if you change the flow, regenerate the PNG from it (npx @mermaid-js/mermaid-cli -i <source>.mmd -o docs/images/agent-flow-full-cycle.png -b white -w 1600) so the two stay in sync.

flowchart TD
    SW["story-writer-amlog<br/>(BA writes story + AC)"]
    G1{"BA confirms<br/>AC + story?"}
    GHBA["github-manager-ba-amlog<br/>(creates GitHub issue)"]

    GHM0["github-manager-amlog<br/>(always creates instructions.md<br/>+ creates branch)"]

    RES["researcher-amlog<br/>(optional, fe only)"]
    PFE["planner-amlog (fe)"]
    PBE["planner-amlog (be)"]
    G2{"Developer confirms<br/>the plan?"}

    IFE["implementor-amlog (fe)"]
    IBE["implementor-amlog (be)"]

    BROWSER["browser-launcher-amlog<br/>(headless Playwright AC check)"]
    TRUN["test-runner-amlog<br/>(codegraph-affected tests)"]
    SEC["security-review-amlog"]
    CQ["code-quality-amlog<br/>(SonarQube gate)"]
    REV["review-amlog<br/>(pre-review vs AC + conventions)"]

    TGEN["test-generator-amlog"]
    G3{"Tester adds edge /<br/>corner cases?"}
    API["api-contract-tester-amlog<br/>(optional: back end changed)"]
    E2E["e2e-tester-amlog<br/>(optional: front end changed)"]
    TEXEC["test-executor-amlog<br/>(accepted / open-items / rejected)"]
    TRIAGE["bug-triage-amlog<br/>(classify, dedupe, route)"]
    G4{"Human approves<br/>bug filing?"}

    GHMPR["github-manager-amlog<br/>(PR + plan-as-comment<br/>+ corrections capture)"]
    KBCUR["kb-curator-amlog<br/>(planned, not yet built)"]

    SW --> G1
    G1 -- confirmed --> GHBA
    G1 -- changes requested --> SW
    GHBA --> GHM0

    GHM0 --> PFE
    GHM0 --> PBE
    PFE -. optional research .-> RES
    RES -.-> PFE
    PFE --> G2
    PBE --> G2
    G2 -- confirmed --> IFE
    G2 -- confirmed --> IBE
    G2 -- changes requested --> PFE
    G2 -- changes requested --> PBE

    IFE --> BROWSER
    IBE --> TRUN
    BROWSER -- AC pass --> SEC
    BROWSER -- AC fail --> IFE
    TRUN -- tests pass --> SEC
    TRUN -- tests fail --> IBE

    SEC -- pass / warn --> CQ
    SEC -- BLOCK --> IFE
    SEC -- BLOCK --> IBE
    CQ -- gate pass --> REV
    CQ -- gate fail --> IFE
    CQ -- gate fail --> IBE
    REV -- APPROVE --> GHMPR
    REV -- REQUEST CHANGES --> IFE
    REV -- REQUEST CHANGES --> IBE

    IFE -. parallel QA track .-> TGEN
    IBE -. parallel QA track .-> TGEN
    TGEN --> G3
    G3 -- back end changed --> API
    G3 -- front end only --> E2E
    G3 -- neither applies --> TEXEC
    API -- pass / skipped, front end changed --> E2E
    API -- pass / skipped, back end only --> TEXEC
    API -- fail --> TRIAGE
    E2E -- pass / flaky / skipped --> TEXEC
    E2E -- fail --> TRIAGE
    TEXEC -- accepted / accepted-with-open-items --> GHMPR
    TEXEC -- rejected: coverage only --> TGEN
    TEXEC -- rejected: hard failure --> TRIAGE
    TRIAGE --> G4
    G4 -- product bug, front end --> IFE
    G4 -- product bug, back end --> IBE
    G4 -- test bug / flaky --> TGEN

    GHMPR -- PR merged --> KBCUR

    classDef gate fill:#fff3cd,stroke:#d97757,color:#333;
    class G1,G2,G3,G4 gate;

The four diamonds (G1–G4) are the hard human-in-the-loop stops — see the next section. kb-curator-amlog is drawn dashed-in-concept because it's documented in AGENTS.md as part of the intended roster but isn't built yet; the handoff to it is a forward reference.

Human-in-the-loop gates

These points in the cycle are hard stops. The agent must get an explicit human response before continuing, not just ask and proceed regardless. They apply even when auto_handover is true, and each one ends the agent's message with a HUMAN INPUT REQUIRED: … line:

| Gate | Agent | What it waits for | |---|---|---| | BA approval | story-writer-amlog | Explicit confirmation of the AC and story description. A request for changes sends the agent back to revise and re-confirm — it never hands off on an unconfirmed story. | | Developer plan review | planner-amlog (fe/be) | The developer's review of the written plan, before implementor-amlog starts coding. Requested changes loop back into the plan; even "proceed as-is" requires an explicit response. | | Tester edge-case input | test-generator-amlog | The tester's own edge/corner cases, on top of whatever the agent identified autonomously, before any test is written. | | Bug filing | bug-triage-amlog | Before anything is filed on GitHub, the human sees the drafted bugs (severity, owner, repro) and approves filing, edits them, or skips. The local reports in .amlog/qa/bugs/<issue-number>/ are always written; only the outward-facing GitHub step waits. | | Visual verification | browser-launcher-amlog | Once the automated AC check passes, a human looks at the screenshots (desktop + mobile) or the running app and confirms the UI. A reported problem goes back to implementor-amlog (fe). | | Commit / PR approval | github-manager-amlog | Approval of the drafted commit message, and confirmation of the PR source and target branches. | | Loop limit | any agent | The same handoff for the same issue would happen for the max_handoff_repeats-th time. See Handoff automation & loop guard. |

A fourth item is a mandatory action, not a confirmation gate: github-manager-amlog always creates docs/<issue-number>/instructions.md when starting work on an issue — even if the user gives nothing beyond the issue itself — so there's always a concrete file for developer involvement instead of technical detail living only in chat history.

Self-improvement: agent history & retrospectives

planner-amlog and implementor-amlog (fe and be) each keep a running retrospective log at .amlog/history/<agent-name>-<type>.md (gitignored, per-machine):

• At the start of a run, the agent reads up to the 5 most recent entries' Lesson for next run line and applies it.
• At the end of a run, it appends a new entry — planned/attempted, what actually happened, a codebase pattern learned, and a lesson for next run — condensing anything past the most recent 20 entries into a single archived-lessons block.
• github-manager-amlog writes to the same logs. After every PR, it checks test-executor-amlog's verdict (see QA verdict model) and, on anything other than a clean accepted, appends a correction entry summarizing what QA or security-review flagged.
• A recurring lesson can graduate into a skill. If the same lesson shows up in 3+ entries, the agent proposes adding it as a bullet to the relevant .amlog/skills/<id>/SKILL.md — but only with your explicit confirmation; it never edits a shared skill file on a lesson alone.

This is a different mechanism from the self-updating skills above: skills track codebase conventions (verified via codegraph_explore, corrected automatically); history tracks lessons from doing the work (proposed, never auto-applied, when they'd touch a shared file).

QA verdict model

test-executor-amlog reports one of three verdicts — one spelling, everywhere it's written:

| Verdict | Meaning | Blocks merge? | |---|---|---| | accepted | Clean run: no failures, no flaky suites, no coverage regression, coverage at/above the 80% floor. | No | | accepted-with-open-items | No hard failures, but at least one of: a flaky suite or tester report, a coverage-regression warning, missing/failing security-tagged tests, an optional tester that errored or found no tests, or a required tester that wrote no report. | No — visible, not blocking | | rejected | Any hard test failure, coverage below the 80% floor, an API contract or E2E failure, or an open/regressed S1/S2 bug in the bug ledger. | Yes |

The underlying scripts/run-test-suite.sh retries each suite once before calling it flaky, extracts real coverage percentages, and ratchets a git-committed docs/qa/coverage-baseline.json forward only on a fully green run — so the regression check always compares against the last known-good number, and a partial run (e.g. only the backend) never nulls out the other stack's baseline.

QA chain: optional testers and bug triage

test-generator → api-contract-tester → e2e-tester → test-executor → github-manager
                        │                   │              │
                        └──── any failure ──┴──────────────┴──→ bug-triage → implementor (fe|be) / test-generator

Only the side that changed gets tested. .amlog/skills/qa-scope/scripts/detect-scope.js looks at the committed diff vs main plus the working tree under the front-end and back-end roots (FRONTEND_ROOT/BACKEND_ROOT, else zones in .amlog/amlog-workflow.config.json) and writes .amlog/qa/scope.json:

| Change | api-contract-tester-amlog | e2e-tester-amlog | |---|---|---| | Back end only | runs | skipped — "no front-end changes" | | Front end only | skipped — "no back-end changes" | runs | | Full stack | runs first | runs only if the API contract passed; otherwise skipped as "blocked by API contract failure" |

A skip is never silent: the skipped tester still writes a report with the reason, and test-executor-amlog lists it. Each tester also picks a depth — smoke when only internals changed, full when the API surface (controllers, DTOs, validators, OpenAPI) or UI surface (templates, routes, components, styles) changed.

What each new agent adds

| Agent | Beyond the unit tests | |---|---| | api-contract-tester-amlog | Per-endpoint checklist (success shape, 400 validation, 401/403/IDOR, 404/409, boundaries, error hygiene) as tagged xUnit tests that follow the repo's existing integration-test style; OpenAPI breaking-change diff against main (oasdiff); optional schema-driven fuzzing of the running API (schemathesis) | | e2e-tester-amlog | Durable journey specs derived from the AC (Playwright by default, or the repo's own Cypress/Playwright suite); fails on console errors and unexpected 4xx/5xx; axe accessibility check; desktop + mobile; one retry so flaky tests are reported as flaky, never pass; screenshots and traces as evidence | | bug-triage-amlog | Classifies every failure (product bug / test bug / contract drift / environment / flaky), rates severity S1–S4 and priority P1–P3, points at the likely code with codegraph_explore, writes a minimal repro, fingerprints and de-duplicates across runs (.amlog/qa/bugs.json), files approved bugs on GitHub, and routes each one to the right agent — environment problems go to a human, never to an implementor |

Standard report file. Every tester writes .amlog/qa/<name>-report.json (status: pass / fail / flaky / skipped / error / no-tests, totals, failures with category + AC + evidence). error and no-tests are never treated as a pass. test-executor-amlog and bug-triage-amlog read these instead of scraping console output.

Bug lifecycle. new → (filed, fixed) → verified-fixed when a later run no longer fails → regressed if it fails again. A repeat of a known bug raises its occurrence count instead of creating a duplicate issue.

Implementation plan as an issue comment

After github-manager-amlog creates a PR, it also posts the plan planner-amlog wrote (docs/<issue-number>/plan.md) as a comment on the originating GitHub issue — via whatever GitHub MCP tool the workflow already uses for issue operations, falling back to gh issue comment <issue-number> --body-file docs/<issue-number>/plan.md if that's unavailable. It posts once per issue per session, and skips silently (with a note in its summary) if no plan file exists yet — it never fails PR creation over a missing plan.

Status

amlog status

Shows:

• Which agents are installed, grouped by tool and then by role
• Whether CodeGraph is installed and wired for each installed tool
• Live index stats (files, symbols, edges) per zone

Requirements

| Tool | Required for | |---|---| | Node.js ≥ 18 | CLI runtime | | npm | Install path | | CodeGraph | Auto-installed by amlog install | | GitHub CLI (gh) | Optional — enables auto-PR + issue-comment fallback in github-manager-amlog | | SonarQube + sonar-scanner | Optional — required by code-quality-amlog | | oasdiff | Optional — enables the OpenAPI breaking-change diff in api-contract-tester-amlog (skipped, with a note, if missing) | | schemathesis | Optional — enables schema-driven fuzzing in api-contract-tester-amlog (CONTRACT_FUZZ=1) | | Playwright for Node (@playwright/test) or Cypress in the front-end repo | e2e-tester-amlog uses the suite the repo already has; if there is none it bootstraps Playwright | | Python 3 + Playwright (pip install playwright && python3 -m playwright install chromium) | Required by browser-launcher-amlog's webapp-testing skill — the one non-Node/bash dependency in the toolkit |

License

MIT © Selise

Contributing

Contributions are welcome! Here's the recommended workflow:

Option 1 — Fork and PR (preferred for external contributors)

1. Fork this repository on GitHub.
2. Clone your fork: git clone https://github.com/<your-username>/amlog-workflow.git
3. Create a feature branch: git checkout -b feat/my-improvement
4. Make your changes — add a new agent, improve the CLI, fix a bug.
5. Test locally: npm install && node bin/amlog.js list
6. Commit with gitmoji: git commit -m "✨ feat: add my-new-agent"
7. Push and open a Pull Request against main on this repo.
8. Describe what you changed and why in the PR body.

Option 2 — Open an issue first (for larger changes)

For significant new agents or CLI behaviour changes, please open an issue to discuss the design before writing code. This avoids wasted effort if the direction doesn't fit the roadmap.

Adding a new agent

1. Create a folder under registry/agents/<type>/<agent-name>/.
2. Write agent.md using the frontmatter schema from the spec.
3. Add a scripts/ subfolder only if the agent needs a shell script.
4. Add the agent entry to registry/manifest.json.
5. Submit a PR — include a short description of what the agent does and which role it targets.

Code style

• Node.js with CommonJS modules (require/module.exports).
• No build step — the CLI runs directly from source.
• Keep dependencies minimal.