myagents

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 tmp/*.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