Agentic SE Team

An autonomous, multi-agent software engineering factory. Describe an idea in chat — a team of specialist AI agents takes it from requirements → architecture → design → code → tests → security review → ship → maintenance, while you stay in control through a single dashboard.

---

Table of contents

• What this is
• Why it's different
• How it works
• The specialist team
• Safety & quality systems
• Tech stack
• Repository layout
• Getting started
• Command-line control
• Testing & quality gates
• Project state model
• Roadmap
• License

---

What this is

This is not a single chatbot. It is a controlled software factory in which nine specialist AI agents — each with its own written, version-controlled standard operating procedure (a SKILL.md) — collaborate to build, test, secure, ship, and maintain real software.

A human directs the whole thing from a single Next.js dashboard chat: the agents ask the questions they need, propose decisions, and request approval at the moments that matter. Everything else runs autonomously behind enforced safety rails.

The guiding principle is quality first: the strongest models are used wherever output quality matters; cheaper models are used only for safe, high-volume routine work.

Why it's different

	Typical "AI coder"	Agentic SE Team
Structure	One model, one prompt	9 specialists with explicit roles & SOPs
Safety	Prompt-based "please be careful"	A signed, mechanically-enforced Project Specification Contract (PSC) that blocks unsafe actions before they happen
Review	Self-grading	Real-time auto-review on every action + a unanimous 3-reviewer ship gate
Testing	A few example tests	Property-based tests, a mutation gate, a flaky-test classifier, and pass@k / pass^k benchmarking
Security	None	Gitleaks + Semgrep (OWASP) + Trivy gates wired into the pipeline
Cost	Unbounded	Per-project cost meter with a hard budget auto-freeze
Recovery	Lose the session, lose the work	Crash-safe: the project folder is the resumable state
After delivery	Done	A maintenance loop fixes bugs / adds features through the same chat

How it works

flowchart LR
    U([User / Client]) <-->|dashboard chat| O{{Orchestrator}}

    O --> R[Requirements Analyst]
    R --> A[Architect]
    A --> D[Designer]
    D --> BE[Backend Builder]
    D --> FE[Frontend Builder]
    BE --> T[Tester]
    FE --> T
    T --> FR[Final Reviewer]
    FR -->|ship| M[Maintenance Engineer]
    M -.->|bugs / features| O

    subgraph Continuous
      AR[[Auto-Reviewer + PSC]]
    end
    AR -. mediates every action .- BE
    AR -. mediates every action .- FE

Loading

1. Requirements — the analyst runs an adaptive interview, scores readiness, and produces executable acceptance criteria.
2. Architecture — C4 model, ADRs, locked API contracts, a file-ownership map, and a stack pick chosen by three independent "cognitive frames" judged by a cross-model reviewer.
3. Design (UI projects) — design tokens + components under one discipline, against a UI quality rubric.
4. Build — backend and frontend builders work in isolated git worktrees, types-first, with inline self-verification.
5. Test — property-based suites, a mutation gate, and a red-run protocol prove the tests actually discriminate.
6. Review — a continuous Auto-Reviewer mediates every worker action through the PSC; a Final Reviewer makes the unanimous ship/no-ship call.
7. Maintenance — post-delivery, the same chat handles bug reports and feature requests, each fix gated by a fail-to-pass regression test.

The specialist team

Every agent's behaviour is defined by a versioned SKILL.md in skills/, enriched with named, authoritative best-practice toolkits.

Agent	Phase	Responsibility	Highlights
Requirements Analyst	1	Elicit & specify	JTBD, 5 Whys, story mapping, INVEST, event storming
Architect	2	System design	C4 + ADRs, fitness functions, NFR scenarios, choose-boring-tech, 12-factor
Designer	3	UI/UX	Design tokens, Refactoring UI + Laws of UX, WCAG AA
Backend Builder	4	Server code	Types-first, make-illegal-states-unrepresentable, contract-first, idempotency
Frontend Builder	4	Client code	4-state components, Core Web Vitals budgets, WAI-ARIA APG, error boundaries
Tester	5	Verify	Property-based + metamorphic testing, mutation gate, deterministic isolation
Auto-Reviewer	continuous	Mediate every action	PSC step-1, tiered routing, doom-loop guard, review-priority order
Final Reviewer	6	Ship gate	3-reviewer unanimous vote, Definition of Done, industry-tool gates
Maintenance Engineer	post-ship	Keep it healthy	Reproduce-first, fail-to-pass regression gate, confidence-gated dispatch

Safety & quality systems

• Project Specification Contract (PSC) — a per-project, HMAC-signed contract of invariants (orchestrator/psc/). Every proposed action is verified mechanically (no LLM) before it runs; unsafe writes, out-of-ownership edits, and destructive operations are denied.
• Tamper-evident audit log — every decision is appended to an HMAC-signed JSONL log.
• Cost meter + budget auto-freeze — per-project SQLite ledger (orchestrator/llm/); the orchestrator freezes itself when a budget cap is hit.
• Security gates — Gitleaks (secrets), Semgrep (OWASP), and Trivy (dependency CVEs) wired through orchestrator/security/.
• Quality gates — property-based tests, a mutation gate, a flaky-test classifier, TTS@3 unanimous ship voting, and an internal pass@k / pass^k benchmark (orchestrator/quality/, orchestrator/evals/).
• Crash safety — a two-file ledger with a shared monotonic save sequence; the project folder is the single source of truth, so the orchestrator resumes after any crash.
• Emergency controls — freeze / resume / stop / budget from the CLI at any time.

Tech stack

Orchestrator (Python 3.10+) — anthropic, litellm (cost calc only), pydantic, hypothesis, PyYAML, python-dotenv, pytest.

Dashboard — Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS v4, Framer Motion, WebGL/Three.js + OGL for animated backgrounds.

Models — Claude Opus (thinking/quality roles), Claude Haiku (fast routine review), OpenAI Codex / GPT (tester + cross-model judge). Subscription-based CLI auth — no API keys required at runtime.

External tooling — Gitleaks, Semgrep, Trivy, Serena MCP (symbol graph), Context7 MCP.

Repository layout

.
├── orchestrator/        # The engine (Python)
│   ├── memory/          #   crash-safe two-file ledger
│   ├── control/         #   freeze / resume / stop / budget CLI
│   ├── psc/             #   Project Specification Contract (sign / verify / invariants)
│   ├── llm/             #   cost meter + budget auto-freeze
│   ├── cache/           #   prompt-cache wiring
│   ├── chat/            #   file-backed chat thread (JSONL, lock-guarded)
│   ├── dispatch/        #   task scoring, context budget, memory pointer
│   ├── workers/         #   worktrees, Claude Code / Codex workers, hook bridge
│   ├── checkpoints/     #   git-tag checkpoints + rollback
│   ├── design/          #   DTCG token validation + UI quality rubric
│   ├── quality/         #   TTS voting, mutation gate, flaky classifier
│   ├── security/        #   Gitleaks / Semgrep / Trivy wrappers
│   ├── replay/          #   deterministic state reconstruction + branch-vote
│   ├── review/          #   final ship report
│   ├── maintenance/     #   post-delivery fix loop + fail-to-pass gate
│   ├── skills/          #   skill loader (frontmatter + cache)
│   ├── smoke_test.py    #   end-to-end self-test
│   └── settings.py      #   env-driven settings (no hardcoded secrets)
├── skills/              # 9 agent SKILL.md SOPs (+ per-stack security defaults)
├── dashboard/           # Next.js 15 dashboard + chat UI
├── evals/               # doc-consistency gate, promptfoo stubs, internal benchmark
├── tests/               # 614 tests (property-based + integration)
├── templates/           # per-project artifact templates
├── scripts/             # demos and utilities
├── docs/                # research notes + UI component attribution
├── boss-report/         # progress-report generator + outputs
└── files/               # design specs + the session build checklist

Getting started

Prerequisites

• Python 3.10+
• Node.js 20+ (for the dashboard)
• Optional (graceful-skip if absent): gitleaks, semgrep, trivy

1. Clone

git clone https://github.com/maowiz/Agentic_SE_Team.git
cd Agentic_SE_Team

2. Python environment

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

3. Configure (optional)

Copy the example env and fill in only what you need. Every key is optional — modules that don't need a key won't ask for one.

cp .env.example .env   # then edit

4. Run the checks

python -m pytest -q                 # full test suite (614 tests)
python -m evals.doc_consistency     # documentation gate
python -m orchestrator.smoke_test   # end-to-end smoke (9 subsystems)

5. Run the dashboard

cd dashboard
npm install
npm run dev      # http://localhost:3000

Command-line control

The orchestrator can be steered at any time without touching its process:

python -m orchestrator.control status <project_id>   # phase, turn, blocked-on
python -m orchestrator.control freeze <project_id>    # pause all work
python -m orchestrator.control resume <project_id>    # resume
python -m orchestrator.control stop   <project_id>    # graceful stop
python -m orchestrator.control budget <project_id>    # spend vs caps + cache-hit rate
python -m orchestrator.control list                   # all projects

Testing & quality gates

Check	Command	What it proves
Unit + property tests	python -m pytest -q	614 tests green / 0 failing
Documentation gate	python -m evals.doc_consistency	no banned/stale terms in active docs
Smoke test	python -m orchestrator.smoke_test	ledger, control, PSC, cost, chat, replay, design, quality, maintenance all wire up end-to-end
Mutation gate	(per project, via Tester)	tests fail when the code is broken
Internal benchmark	python -m orchestrator.evals.run_internal_benchmark ...	capability (pass@k) and consistency (pass^k)

CI runs the Python gates on every push and pull request (see .github/workflows/ci.yml).

Project state model

Each project lives in a single self-contained folder and is its own resumable state — code, ledgers, chat history (thread.jsonl), the signed psc.yaml, the cost meter, and the audit log all in one place. If the orchestrator crashes, restart it: it reads the folder and resumes. There is no external database to fall out of sync.

Roadmap

The build plan runs in focused sessions (see files/10_session_checklist.md). Sessions 1–14 are complete; the remaining work is:

• Dogfood — build one complete real project end-to-end as final proof.
• Live CLI wiring — connect the dashboard to Claude Code + Codex subscriptions end-to-end.
• Observability — per-agent trace dashboards (Langfuse).
• CI browser matrix — automated Chromium / WebKit / Firefox smoke for the dashboard.
• Live extras — public tunnel + a real-time cost meter in the header.

License

Proprietary — All Rights Reserved. See LICENSE. This source code is not open source; no permission is granted to use, copy, modify, or distribute it without the copyright holder's prior written consent.