Русский · English

agentic-workflow

Multi-agent framework for Claude Code: 60 agents, 47 methodology skills, 26 + 3 Python orchestration scripts, 3 Workflow orchestration engines + 2 LangGraph human-gate engines, tier-aware acceptance (S/M/L), filesystem-isolated adversary review, cross-family second opinion via Codex MCP, human as supreme judge at critical transitions.

Version history: CHANGELOG.md.

Why this exists

Multi-agent pipelines on a single model family suffer from three systemic failure modes:

Problem	What goes wrong	How the system handles it
Framing contamination	The same Claude across multiple roles shares the same blind spots	Adversary runs in a fresh subprocess with a filesystem-curated view — sees only what an external process places there
Goodhart on validators	Validators degenerate into format-gates, checking fields instead of thinking	Tier-aware dispatch + cross-family second opinion via Codex (different model lineage = different blind spots)
Undifferentiated rigour	A button tweak and a landing redesign go through the same pipeline	S — light human-glance; M — adversary + judge; L — consilium of 5 reviewers + cross-family adjudication

Architecture — five layers

flowchart TB
    H["Human layer<br/>Trigger phrase + supreme judge on M/L acceptance + SkillOpt commons-maintainer"]
    A["Agents layer · 60 agents<br/>managers / directors / leads / specialists / validators"]
    S["Skills layer · 47 skills<br/>methodologies, protocols, tool guides"]
    O["Orchestration layer · 26 + 3 Python scripts<br/>mechanical gates, adversary, consilium, archival, event ledger"]
    St["State layer<br/>engagement/ directory · whitelist · append-only logs"]

    H <--> A
    A <--> S
    A <--> O
    O <--> St
    A <--> St

    classDef human fill:#fef3c7,stroke:#d97706,color:#000
    classDef agents fill:#dbeafe,stroke:#2563eb,color:#000
    classDef skills fill:#dcfce7,stroke:#16a34a,color:#000
    classDef orch fill:#fce7f3,stroke:#db2777,color:#000
    classDef state fill:#e9d5ff,stroke:#9333ea,color:#000

    class H human
    class A agents
    class S skills
    class O orch
    class St state

Loading

Each layer has a clear scope of responsibility. Layers don't substitute for each other: agents don't write scripts, scripts don't make judgments, humans don't do routine validation.

Detailed description of each layer and their interactions — ARCHITECTURE.md.

Key mechanisms

Tier-aware acceptance. Each engagement is classified at intake into one of three tiers:

Tier	Use case	Adversary	Manager (acceptor)	Mechanical checks
S	Hotfix, button tweak, single deliverable	None — human glance	None	8
M	Feature, landing, dashboard, multi-specialist	1× peer-opus	Judge mode	18
L	Rebrand, multi-wave, cross-domain	5× consilium	Judge + adjudication	26

Adversary in filesystem-isolated subprocess. Two-pass design against framing contamination:

• Pass 1 (Blind). Adversary sees a curated copy of engagement/ without handoff.md, without acceptance-log, without other reviewers. Forms preliminary findings without contamination.
• Pass 2 (Informed). Adversary receives full state plus its own preliminary findings injected via prompt. Confirms, refines, or retracts findings. Delta preliminary→final is a contamination signal.

L-tier consilium. 5 reviewers in parallel: Claude Opus 5.5 + 2× OpenAI Codex (GPT-6-Astra, read-only sandbox) + Claude Sonnet 5.5 + Claude Haiku 5.5. Cross-family disagreements are detected automatically and flagged for manual review.

Manager as judge, not sweep-runner. On M/L the manager (per-engagement acceptor — *-manager agent, ex-director) issues a verdict per directive with explicit adjudication on every disagreement between adversary and author. Doesn't dispatch, doesn't edit content, doesn't re-run validators. Adjudication completeness is enforced mechanically — every finding must have a decision marker.

A finding cannot vanish on the way to the human. Three checks close the paths by which a real finding could disappear. The engine's adversarial verify drops a finding only on a confident refutation (confidence ≥ 0.8); doubt, or a verifier that returned nothing, keeps it, and refuted findings move to an advisory list instead of being deleted. findings-dispositioned (M/L) refuses a handoff while any Medium+ finding of the current iteration lacks a recorded ruling — fixed, out of scope, waived or false positive — in validation-log.md or scope-sync.md. consilium-fidelity (M/L) checks that the summary the human judges is the one consilium-synth.py computes from the reviewers' finals on disk.

Tool grants that bind. Every agent declares its tools under tools: (the key Claude Code honours for subagents), and check-agent-models.py fails the corpus if any agent falls back to allowed-tools:. Validators that need one narrow shell command — a contrast calculator, read-only git, a dependency audit — get it through an agent-scoped PreToolUse hook that refuses everything else.

Director as system-optimizer (out-of-band). The *-director role (repurposed in v0.2) runs a SkillOpt-style skill-evolution loop on accumulated REJECT / rework signals from skill-evolution-log.md. Fires only at ≥3 same-class signals clustered by target × class (rule_missing / rule_wrong / rule_ignored). Cycle:

1. Reflect — director clusters manager-emitted signals by target + class, reads skill-rejected-edits.md (negative memory) and the optimizer memory left by the previous cycle. A second, conservative channel reads - worked: reflections — behaviours that carried an engagement — so a cycle can reinforce as well as forbid. Success never opens a cycle on its own; a corrective edit beats a reinforcement one on every conflict.
2. Codex proposes bounded edits — cross-family (kills defend-bias), budget L: 4–6 patches per cycle, ≤10 lines each.
3. Golden-set gate — director verifies the edit doesn't regress any scenario in system-optimization-protocol/golden/{domain}/ (7 dev + 4 design + 4 marketing = 15 total). Each domain includes a non-rejection scenario the gate must also pass, so an edit cannot buy a catch by making the corpus more suspicious.
4. Promote or reject — passing edits land in the corpus behind a pre-edit snapshot; rejected edits append to skill-rejected-edits.md with reason (read before next cycle).
5. Verify what landed — a diff guard checks the cycle wrote only where it declared, slow-update re-reads the golden set over every promotion, and a regression restores the snapshot and blocks the draft MR. A check that could not run counts as failed, not passed.
6. Record — signals a promotion closed get resolved:; a cycle that produced no edit writes adjudicated:, so the trigger clears either way and never fires forever on a cluster nobody can close.

Judge-only — never authors edits itself. Never per-engagement. The human is commons-maintainer for cross-domain promotions.

Authority invariant. When sources of behavior disagree, a written 7-rule precedence resolves it (CLAUDE.md > judge decision > criteria.md > PROTOCOL > METHODOLOGY > agent body > frontmatter). Unresolved conflicts become blocking authority_conflict events.

Event ledger. Every M/L engagement appends lifecycle events to engagement/events.jsonl (append-only, per-engagement). Schema v1 captures phase transitions, validator runs, interrupts, verdicts, reflections, authority conflicts. Read at any time via scripts/lib/ledger.py.

Human as supreme judge. Between consilium synthesis and director verdict the human gets a chat-ready summary (≤2 minutes to read) and responds in one of three forms: PROCEED / REJECT: <reason> / DIRECTED: <what to change>. No 200 lines of markdown — the system formats and expands it.

Mechanical safety baseline. Exit-code gates run at every transition: danger-scan (DROP / force-push / prod-deploy registry), handoff-precheck (tier-aware structural verification), handoff-paths-check (phantom path detection), director-verdict-check (adjudication completeness), preflight (tools availability).

Audit trail by FS state. Engagement = directory. State is read from files: iteration, validation-log.md, validation-outputs/*.json, consilium-summary.md, human-directive.md, acceptance-log.md. No databases, no external logs — cat reconstructs the picture completely.

Engagement flow

sequenceDiagram
    autonumber
    participant U as Human
    participant ML as Main loop · agency-intake
    participant WF as engagement-workflow · Workflow
    participant SP as Specialists · waves
    participant V as Validators
    participant SC as LangGraph + scripts
    participant M as Manager · acceptor

    U->>ML: trigger phrase
    ML->>ML: classify → criteria.md (S/M/L)
    ML->>WF: invoke engagement-workflow
    WF->>WF: discovery · lead:plan → tasks / waves / validators
    WF->>SP: deliver — specialist waves in git worktrees (per-task review→rework)
    SP-->>WF: executor-reports/ + consolidated work
    WF->>V: validate — validators in parallel + adversarial-verify
    V-->>WF: validation-outputs/*.json (canonical envelope)
    WF->>WF: handoff.md + handoff-precheck (gate)
    WF-->>ML: readyForAcceptance — handoff seam
    Note over ML,SC: seam · pre-gate = Workflow | human-gate = LangGraph
    alt M/L tier
        ML->>SC: adversary_lg.py --consilium {M|L} --interrupt
        SC->>U: consilium summary (chat, ≤2 min)
        U->>SC: PROCEED / REJECT / DIRECTED → human-directive.md
        ML->>M: invoke {domain}-manager (judge mode)
        M->>M: acceptance-log.md + 0–3 reflections
    else S tier
        Note over U: human glance — accept directly
    end
    ML->>SC: engagement-archive.py (on ACCEPT)

Loading

S-tier skips adversary, consilium and manager phase: producer self-attests, mechanical checks gate, human accepts directly.

Engine activation flags

The pre-gate engagement-workflow engine ships a set of opt-in activation flags, passed in the Workflow's args.A object. Every flag defaults OFF, and with all flags off the engine renders byte-for-byte identically to the unflagged path — so a flag is adopted per engagement, not globally. They let an operator dial the cascade's rigour up to match a specific engagement without changing the default behaviour for everyone else.

Flag (args.A.*)	Default	What it adds
consGuard	off (guard-class)	Hard-stops a wave whose consolidation didn't land — a null consolidator, merge_ok:false, or a code-mode merge that landed but failed repo tests — with the same error contract as the pre-consolidation hard-stop, so dependent waves never branch off a missing/broken integration HEAD. Asymmetric: a merge that never landed is replan-compatible; a merge that landed but failed tests hard-stops without auto-replan. A bug-fix, so it may be enabled earlier than the feature flags.
repoPortable	off	Adds one discovery-phase detect:repo agent that detects the repo's integration branch + test runner instead of hardcoding main / python -m unittest; a non-git repoDir hard-stops early in code mode.
contracts	off (M/L)	Per-task contract handshake: the owner proposes ≥1 checkable assertion per cited criterion in-band, a neutral reviewer co-signs and writes tasks/{id}.md → ## Contract (co-signed), the owner may contest. Binds the per-task review rubric only — never waives criteria.md.
replan	off	One bounded replan per run when a wave hard-stops: lock completed waves, re-plan the remaining work (ids suffixed -r{n}), re-validate, continue.
renderEval	off (artefact)	After manifest-verify, renders the wave's HTML artefacts in a real browser and checks the OBSERVED values against the co-signed assertions / criteria — not just that the file exists.
cheapTiers	off	Routes mechanical engine steps (manifest-verify + gate-runner → haiku; adversarial-verify → sonnet) to cheaper models; judgement steps stay on the inherited model.
inPlaceSerial	off (mode-changing)	For a containerized runner that bind-mounts the repo root (where git-worktree isolation is void), runs tasks serially against the repo with an in-place wave barrier instead of worktree + octopus merge. Conductor-activated.
infraRetry	off (guard-class)	Retries a null (transient) review / validator / verify result up to twice before the pre-existing substantive handling, so a transient API error isn't misread as a negative verdict.
engBranch	off	In code mode, consolidates onto an eng/<slug> branch off the origin integration branch (not the local checkout) and diffs the handoff against the merge-base, so a stale local checkout can't pollute the delta.
contractsCodex	off (child of contracts)	For an exercisable-surface task (HTTP / CLI / rendered screen), a cross-family Codex reviewer challenges the proposed done-when before co-sign; the existing reviewer reconciles it — Codex never authors or judges the contract.

A backslash-repoDir guard (validation-only, no flag) rejects Windows-style paths that would nest worktrees inside the repo.

What's inside

Agents (60)

Category	Count	Roles
Managers	3	dev-manager, design-manager, marketing-manager — per-engagement acceptor (judge between producer + adversary)
Directors	4	dev-director, design-director, marketing-director, harness-director — out-of-band system-optimizers (the SkillOpt skill/agent loop + the harness-evolution script/engine loop)
Leads	3	dev-lead, design-lead, marketing-lead — planning-only (the engagement-workflow's lead:plan step; they plan waves, the Workflow dispatches specialists)
Specialists	20	backend, frontend, fullstack, devops, qa, tech-architect, product-analyst, technical-writer; ux, ui, visual, brand-strategist, presentation; copywriter, banner-designer, seo, ppc, keyword-researcher, web-analyst, ai-visibility
Validators	30	code-reviewer, security-auditor, accessibility, performance, migration, test-reviewer, reality-checker, skeptic, completeness, task/tech-spec/user-spec validators, infra/deploy reviewers, pre/post-deploy QA, anti-pattern detector, ux-review, render-eval, skill-checker, 3 researchers (code/brand/design-system), product-context-validator, etc.

Skills (47)

Category	Count	What's in it
Agency protocol	9	agency-intake, engagement-protocol, engagement-contract (specialist subset), acceptance-protocol (per-engagement acceptor methodology), system-optimization-protocol (SkillOpt loop), validation-pipeline, docs-pipeline, codex-bridge, human-voice (rules for Russian text a person reads, with a hit-counting detector)
Dev methodology	16	TDD, code review, spec planning (user/tech), task decomposition, deploy, security, infrastructure, prompt engineering, persistent tasks, pre/post-deploy QA
Design methodology	8	brand, design system, UI/UX, presentation, banner, design tokens
Marketing methodology	5	SEO auditing, semantic drift, AI visibility, task decomposition, benchmark research (industry reverse-engineering, standalone entry-point)
Regional SEO/PPC stack	6	API integrations for Russian-market analytics platforms (Webmaster, Metrika, Direct, Wordstat, Search)
Skill development	3	skill authoring, test design, testing

Frontmatter tags for the router: [PROTOCOL], [METHODOLOGY], [TOOL].

Scripts (26 main + 3 optional)

Three Workflow orchestration engines (workflows/):

• engagement-workflow.js — the pre-gate cascade the main loop conducts: discovery (lead:plan) → decompose (gated) → deliver (specialist waves in isolated git worktrees, per-task review→rework, per-wave consolidation: code = octopus-merge / artefact = manifest-verify) → validate (validators in parallel + adversarial-verify each finding; only a confident refutation removes one) → handoff → gate. Stops at the handoff seam; a wave hard-stops if a task is blocked / fails review / the plan is malformed (no silent proceed). Resumes via the Workflow run journal (resumeFromRunId). Opt-in activation flags (args.A, all default-OFF) add the per-task contract handshake, bounded replan, repo detection, consolidation guard, artefact render-eval, and cheap-model tiering — see Engine activation flags.
• skillopt-workflow.js — the director SkillOpt cycle as a Workflow (harvest due signals → Codex proposes bounded edits → golden-set gate → promote / reject → diff guard, which also rolls back an edit that removed a load-bearing prompt clause).
• harnessopt-workflow.js — the harness-evolution cycle as a Workflow (harvest harness-ready signals → Codex authors patch-bundles → executable gate → promote / escalate / reject); the script/engine-layer peer of skillopt-workflow.js.

Two LangGraph engines (the human-gate, after the seam):

• adversary_lg.py — LangGraph adversary bridge: 5 reviewer roles, two-pass curated-view isolation, Send-based parallel fan-out, SQLite-checkpointed --resume, native HITL via interrupt(), event ledger wired
• validator_lg.py — LangGraph atomic-validator fan-out via Send; retry edge, auto-plan from criteria.md predicates, --resume, native HITL via --interrupt-on-critical, canonical validator envelope, event ledger wired

Mechanical gates and synthesis:

• consilium-synth.py — adversary output aggregation, two-stage dedup
• consilium-present.py — chat-ready format with decision menu
• director-verdict-check.py — mechanical adjudication completeness (legacy name; targets manager verdict in v0.2)
• handoff-precheck.py — hard-gate tier dispatch (S=8 / M=18 / L=26 checks), event ledger wired
• human-directive.py — scaffold human-directive.md from CLI args
• preflight.py — tools availability check
• danger-scan.py — registry of dangerous operations
• handoff-paths-check.py — phantom path detection
• cross-val-check.py — verbatim quote verification
• trace-schema-check.py — trace JSON schema + staleness
• size-detect.py — tier detection at intake / runtime, with --auto-promote
• engagement-archive.py — idempotent archival
• contrast.py — deterministic WCAG contrast ratio (the accessibility validator's only shell command)

Readiness and observability:

• skillopt-ready.py — SkillOpt readiness: clusters log signals, orphan reflections and - worked: success patterns; reports what is DUE
• harness-ready.py — the script/engine-layer peer, clustering by (script × class) at ≥2
• metrics.py — agreement / override / false-positive rates and per-phase deltas off the event ledger
• ledger-emit.py, ledger-emit-phases.py — append lifecycle events from a shell one-liner
• reflect-emit.py — append one reflection (--kind gap or --kind worked) mid-flight
• handoff-digest.py — print the handoff digest an acceptance log must record
• outcome-due.py — surface engagements whose outcome hypothesis is due for a check
• check-agent-models.py — model tier and tools: grant lint across the agent corpus
• memory-doctor.py — validates the auto-memory directory: index links, frontmatter, duplicates, secret-shaped strings (reported, never printed)
• worktree-gc.py — classifies git worktrees and removes only merged, clean ones; never touches unmerged, uncommitted or ignored work

Shared libraries:

• lib/ledger.py — append-only event ledger (engagement/events.jsonl); 28 known payload types; thin shim; smoke-tested
• lib/precheck/ — modular precheck package: topic modules (common, criteria, handoff, iteration, validators, acceptance, danger, consilium_fidelity + __init__ re-exports). handoff-precheck.py (1264 → 423 lines, CLI/dispatch only) imports from this package. Byte-identical JSON output to the pre-refactor monolith.

Plus optional/ — opt-in utilities outside the core protocol (engagement-doctor.py, engagement-migrate.py, token-budget.py; see scripts/optional/README.md).

Hooks

hooks/ holds the session and tool hooks; settings.hooks.example.json shows how they are wired into ~/.claude/settings.json.

Hook	Event	What it does
pre-commit-check.sh + git_bypass_guard.py	PreToolUse (Bash)	On git commit: scans the staged index for secrets (file and line only, never the value); refuses --no-verify, -n and hooks-path overrides
verification-gate.sh	PreToolUse (Bash)	On git commit: runs the repository's tests from its root, once per committed repository
lint-on-edit.sh + lint_on_edit.py	PostToolUse (Edit/Write)	Applies only the safe autofixes that land on lines the edit wrote; reports findings on those lines
post-compact-restore.sh, post-compact-context.sh	SessionStart (compact)	Restores working context after compaction, fenced as history rather than instructions
session-start-project.sh	SessionStart	Surfaces an active engagement or project knowledge in the working directory
agent-bash-guard.py	Agent-scoped PreToolUse	Narrows a validator's shell to one profile (contrast, git-read, audit)

The SessionStart entries in the example also run the readiness and health checks (skillopt-ready, harness-ready, metrics, check-agent-models, outcome-due, memory-doctor), each silent when nothing is due. Hook output reaches the model through hookSpecificOutput.additionalContext.

Tests

scripts/tests/ — 33 Python and 2 JavaScript regression suites, runnable standalone or under pytest, stdlib only (the JavaScript suites need node). They read the installed tree under ~/.claude/. The live-consilium cases skip when the optional LangGraph venv is absent.

SkillOpt golden sets

The director-optimizer uses golden scenarios as a regression gate before promoting any Codex-proposed edit. One set per domain, each covering the three failure classes plus a non-rejection scenario. That last one matters: every other scenario rewards catching a defect, so without it each accepted edit ratchets the corpus toward suspicion and nothing ratchets back. An edit that closes its target but trips the non-rejection scenario is a reject.

Domain	Scenarios	Failure classes
golden/dev/	spec-code-drift / flaky-test-masking / security-gap / mis-rendered-consilium / http-endpoint-on-unit-green (+ clean-work-must-not-be-rejected, escalation-quality)	rule_ignored / rule_missing / rule_wrong + non-rejection
golden/design/	design-token-drift / accessibility-aria-missing / dark-mode-contrast-fail (+ documented-exception-must-not-be-flagged)	rule_ignored / rule_missing / rule_wrong + non-rejection
golden/marketing/	keyword-count-underdelivery / seo-claim-unsupported / brand-voice-pronoun-violation (+ sourced-claim-must-not-be-flagged)	rule_ignored / rule_missing / rule_wrong + non-rejection

The gate is a regression detector, not a measure of improvement: it shows an edit breaks nothing the set guards. The proposer never reads the golden set (it is the gate's held-out set). After any change to a gate prompt, a scenario or the judge model, the known-bad edits in golden/known-bad.md must still fail and its control must pass. Two design scenarios also have executable fixtures under golden/exec/: golden_exec.py runs the real validator on them, baseline vs edited agent, and grades the output in code. The eval guidance behind this is included under references/anthropic-evals/ (from anthropics/skills, Apache-2.0).

A real SkillOpt cycle fires only when ≥3 real same-class signals from ≥3 distinct engagements accumulate in skill-evolution-log.md. A synthetic dry-run on the dev domain (Codex proposed 3 edits, the judge accepted 2, 1 entered skill-rejected-edits.md) is documented in v0.2 and validates the loop mechanics end-to-end.

Setup

Requirements

• Claude Code
• Codex
• Python 3.10+
• Node.js — for the JavaScript regression suites
• jq and a POSIX shell (Git Bash on Windows) — for the hooks
• (Optional) Yandex API tokens — for marketing skills (Webmaster, Metrika, Direct, Wordstat, Search)

Installation

1. Clone the repository:

   git clone https://github.com/AgentShekel/agentic-workflow.git
   cd agentic-workflow

2. Copy contents to ~/.claude/. Agents are grouped by role in this repository; Claude Code and the lint read them flat from ~/.claude/agents/:

   mkdir -p ~/.claude/agents
   cp agents/*/*.md ~/.claude/agents/
   cp -r skills scripts workflows hooks ~/.claude/

   (On Windows — corresponding paths in %USERPROFILE%\.claude\.)

3. Wire the hooks: merge the hooks block of settings.hooks.example.json into ~/.claude/settings.json.

4. Configure Codex MCP:

   cp .mcp.json.example .mcp.json

   Set the absolute path to the codex CLI.

5. (Optional) Configure Yandex API:

   cp .env.example .env

   Fill in tokens if you use marketing skills.

6. Restart Claude Code — verify that MCP tools are visible.

Quickstart

Entry point — trigger phrase in chat. Both English and Russian are recognized out of the box:

agency task: <description>

or

мне надо агенси задачу <description>

Standalone capabilities have separate triggers:

• мне надо провести исследование / benchmark research — invokes benchmark-research skill (industry reverse-engineering).
• прогнать skill-evolution / skill evolution cycle — invokes the matching domain director to run the SkillOpt cycle on accumulated signals.

Add or adjust phrasings in the agency-intake skill's Use when: list to match your team's vocabulary.

The system then autonomously runs the engagement through all layers. On M/L you get a chat summary with a decision menu — respond with a short verdict.

Detailed flow and role of each layer — ARCHITECTURE.md.

License

MIT (see LICENSE)