myagents

Multi-agent orchestration framework using the BMAD methodology (Business, Market, Architecture, Development). From a project description to working code — fully automated, with QA validation and human escalation when needed.

How it works

Mary (analyst)     → product_brief.md + market_research.md
John (product)     → prd.md + epics.md + stories.md
Winston (architect)→ architecture.md
        ↓
Rex (security)     → security_audit.md          ← Phase 2.5 (read-only)
   PASS/WARN → continue
   BLOCK → Winston gets one auto-fix attempt → Rex re-audits
           still BLOCK → pipeline pauses (fix architecture manually)
        ↓
   [story loop]
        ↓
Amelia (developer) → src/ + tests
        ↓
Rex (security)     → security_scan_result.md    ← per story (read-only)
   PASS/WARN → continue (WARN visible to Tess)
   BLOCK → pipeline pauses (fix code/story first)
        ↓
    git commit + GitHub PR or GitLab MR  (base: myagents branch)
        ↓
    npm test
        ↓
Tess (QA)          → qa_result.md  (PASS / FAIL + fix criteria)
        ↓
Bob (scrum)        → stories.md updated
   PASS → auto-merge PR into myagents → next story
   FAIL → fix-story created → back to Amelia (max 3 retries)
        ↓
   needs_human_review.md → you

you                → review myagents branch → merge into main

Branch strategy:

• story/xxx — one branch per story (Amelia)
• myagents — integration branch, auto-merged after Tess PASS (Bob)
• main — stable, merged by you only

All agents run on gpt-5.3-codex via the Codex CLI. No Python SDK dependencies.

Project structure

myagents/
├── src/                   # Framework scripts
│   ├── orchestrator.py    # Atlas — BMAD state machine
│   ├── mlops_orchestrator.py  # MLOps documentary pipeline (separate from BMAD)
│   ├── audit.py           # Rex standalone security audit
│   ├── codex_office.py    # Live dashboard (pixel-art, port 7700)
│   ├── init.py            # Project initializer
│   └── install.py         # Agent prompt installer
│
├── bin/
│   └── myagents.js        # CLI dispatcher
│
├── agents/                # System prompts (BMAD + MLOps agents)
│   ├── mary.md, john.md, winston.md
│   ├── amelia.md          # Developer — writes src/ code + structured logs
│   ├── tess.md, bob.md
│   ├── rex.md             # Security auditor (OWASP Top 10 + observability checks)
│   └── mlops_*.md         # 15 MLOps specialist agents
│
├── config.json            # Agent routing (model, provider per agent)
│
├── knowledge/             # Phase 0-2 artifacts (generated)
│   ├── product_brief.md, market_research.md
│   ├── prd.md
│   ├── architecture.md    # Includes ## Observability section (logging strategy)
│   └── security_audit.md  # Rex — architecture audit result
│
├── planning/              # Stories and epics (generated)
│   ├── epics.md
│   └── stories.md
│
└── implementation/        # Runtime state (generated)
    ├── tasks.md
    ├── security_scan_result.md  # Rex — per-story code scan
    └── needs_human_review.md    # Written on max retries

knowledge/, planning/, and implementation/ in this repo are demo output from running myagents on itself. They are replaced by npx myagents init.

Requirements

• codex CLI — OpenAI Codex CLI
• gh CLI — GitHub CLI (PR creation on GitHub)
• glab CLI — GitLab CLI (MR creation on GitLab)
• git with a configured remote (GitHub or GitLab — auto-detected)
• lsof — used by the dashboard to manage port 7700 (pre-installed on most Linux/macOS)
• pillow (Python) — pip install pillow (used by the dashboard for image rendering)

Quick start

# 1. Install
npm install -g myagents
# or use directly with npx

# 2. Start your project (init + pipeline in one command)
cd /your/project
npx myagents new "Your project name" "What you want to build, in 1-2 sentences"

init wipes knowledge/, planning/, implementation/ and writes myagents.config.json. Agents and scripts are untouched.

Commands

npx myagents new <name> <description>          Init + run in one shot (new project)
npx myagents run                               Resume or start the BMAD pipeline
npx myagents run new <name> <description>      Alias for: new
npx myagents run mlops <description>           Run the MLOps documentary pipeline
npx myagents install                           Sync agent prompts to current project
npx myagents dashboard                         Live dashboard at http://localhost:7700
npx myagents audit [all|arch|code]             Rex security audit (default: all)
npx myagents init <name> <description>         Init only, no pipeline (advanced)
npx myagents mlops <description>               Alias for: run mlops
npx myagents help                              Show this help

When to use what

| Situation | Command | |-----------|---------| | New project | npx myagents new "Name" "Description" | | New complex project | npx myagents init "Name" "" then /project "..." in Claude Code | | Add a feature | /feature "description" in Claude Code | | Resume after escalation | rm implementation/needs_human_review.md then npx myagents run | | Start over from scratch | npx myagents init again | | Security audit on demand | npx myagents audit (or audit arch / audit code) | | MLOps architecture decision | npx myagents run mlops "description" |

Change models per agent

Edit myagents.config.json (or config.json for direct clone usage):

{
  "project_name": "your-project",
  "project_description": "Describe your project here — Mary reads this first.",
  "agents": {
    "mary":    { "model": "gpt-5.3-codex", "provider": "openai" },
    "john":    { "model": "gpt-5.3-codex", "provider": "openai" },
    "winston": { "model": "gpt-5.3-codex", "provider": "openai" },
    "amelia":  { "model": "gpt-5.3-codex", "provider": "openai" },
    "tess":    { "model": "gpt-5.3-codex", "provider": "openai" },
    "bob":     { "model": "gpt-5.3-codex", "provider": "openai" },
    "rex":     { "model": "gpt-5.3-codex", "provider": "openai" }
  }
}

Swap any "model" value — the orchestrator routes automatically.

Security audit (Rex)

Rex is a read-only security agent that runs at two points in the pipeline:

Phase 2.5 — Architecture audit (once per project, before the story loop)

• Input: knowledge/architecture.md + knowledge/prd.md
• Output: knowledge/security_audit.md
• Checks: auth/authz design, data exposure, injection vectors, secrets management, CORS/headers, cryptography, observability gaps
• Status: PASS / WARN (continue with notes) / BLOCK

On BLOCK: Winston automatically gets one fix attempt — he reads Rex's findings and patches architecture.md. Rex then re-audits. If still BLOCK, the pipeline pauses for human review.

Per-story code scan (after Amelia, before PR)

• Input: files written by Amelia in src/ + story + architecture reference
• Output: implementation/security_scan_result.md
• Checks: OWASP Top 10, hardcoded credentials, XSS, SQLi, path traversal, missing auth middleware, missing structured logs on critical paths
• Status: PASS / WARN (Tess receives the report for context) / BLOCK (pipeline pauses)

On-demand audit (independent from the pipeline):

npx myagents audit         # architecture + full code scan
npx myagents audit arch    # architecture only
npx myagents audit code    # src/ only

Rex is read-only in all cases. Exit code 1 on BLOCK (useful in CI).

Resuming after a BLOCK:

| Block type | Fix | Resume | |-----------|-----|--------| | Architecture (BLOCK) after Winston auto-fix | Fix knowledge/architecture.md manually, delete security_audit.md | npx myagents run | | Architecture (accept risk) | Edit security_audit.md → set **Audit-Status**: WARN | npx myagents run | | Code (BLOCK) | Add security criteria to the story in planning/stories.md | npx myagents run — Amelia re-implements | | Code (accept risk) | Edit security_scan_result.md → set **Scan-Status**: WARN | npx myagents run |

Rex is non-fatal on error: if Rex itself crashes, the pipeline continues with a warning.

Observability in generated code

Winston's architecture design always includes an ## Observability section that defines:

• Logging library choice and rationale
• JSON log format (mandatory fields: ts, level, event, module)
• Instrumented events: HTTP in/out, DB queries, auth events, key business transitions
• Log levels: error (unhandled), warn (degraded), info (business events), debug (disabled in prod)
• What NOT to log: passwords, tokens, API keys, PII

Amelia follows this spec on every story — every I/O call, error path, and business-critical transition emits a structured log. Rex validates that critical paths are not silent.

Dashboard

npx myagents dashboard

Pixel-art isometric office at http://localhost:7700. Each agent has a desk. Click an agent to inspect their current task, status, and PR/MR link.

Multi-project on the same machine: starting the dashboard from a new project directory automatically kills the previous instance and takes over port 7700.

| Colour | Role | |--------|------| | Gold crown | Atlas (orchestrator) | | Orange antenna | Claude Code sessions | | Violet | Tess (QA) | | Cyan | Bob (Scrum) | | Red | Rex (Security) — lights up on BLOCK | | Green ring | Active worker |

MLOps documentary pipeline

A separate pipeline for on-premise LLM deployment decisions. Runs 15 specialist agents in two waves, with devil's advocates and a Rex security audit, producing a final ADR decision document.

# In any project with myagents.config.json
npx myagents run mlops "On-premise LLM deployment for production"
# or equivalently:
npx myagents mlops "On-premise LLM deployment for production"

Optional: place reference documents in bibliography/*.md for shared context (architecture docs, prod feedback, security policies).

Wave 1 (architecture foundation):

• mlops_architect → knowledge/mlops_architecture.md
• mlops_devil_tech → challenges the architecture
• mlops_devops → knowledge/mlops_infra.md
• mlops_ciso → knowledge/mlops_security.md
• Rex → knowledge/mlops_security_audit.md (BLOCK stops the pipeline)
• mlops_devil_security → security challenge

Wave 2 (full coverage, each with access to all Wave 1 output):

• mlops_legal, mlops_procurement, mlops_controller, mlops_pm, mlops_engineer, mlops_amoa
• Devil's advocates interleaved on finance, project, and strategy angles

Final: Atlas (mlops_atlas_decision) → knowledge/mlops_decision.md — the ADR.

Claude Code skills

/project — new project with interactive discovery

/project "Prospector — LinkedIn automation SaaS for sales teams"

Claude Code asks the right questions before writing a single line (architecture choices, MVP scope, existing constraints). Produces all knowledge/ artifacts, then launches the pipeline from phase 1.

/feature — add a feature to an existing project

/feature "Export CSV of workflow runs"

Reads the codebase, identifies impacted modules, asks clarifying questions, writes a precise story for Amelia.

| | Script (npx myagents run) | Skill (/project, /feature) | |---|---|---| | Input | 2-sentence description | Interactive discovery | | Stories | Generated blindly | Based on your real constraints | | Human in the loop | Only on escalation | Before the pipeline starts | | Cost of mistakes | Caught at retry 3 | Caught before phase 1 |

Rule of thumb: use the script for known, well-defined projects. Use the skill when the scope is complex or ambiguous.

Human escalation

If Tess fails a story 3 times, the orchestrator stops and writes implementation/needs_human_review.md with the failing story, the last QA result, and exact steps to resume. The dashboard shows Atlas in red.

# After fixing the issue:
rm implementation/needs_human_review.md
npx myagents run