README_A2Dev.md

Agile ADDIE Dev Framework (A2Dev)

Overview

• Purpose: a lightweight agent‑to‑agent (A2A) scaffold where a PM role orchestrates planning and delivery. It favors tools with typed IO and repo‑persisted artifacts over opaque nested agents.
• Roles: PM coordinator (planning, routing), UX (flows/specs), Eng (scaffold/impl stubs). All outputs are stored under docs/ and state under .a2dev/.

Key Features

• PM‑led pipeline: assess → develop → sustain with clear gates.
• One‑shot prepare: generates UX, ADR, deep plan, QA, security, DevOps, data, trace, and shard per story.
• File‑first: human‑readable artifacts under docs/*; repeatable, reviewable, and VCS‑friendly.
• Local‑first and dependency‑light: no network calls by default; optional scans (semgrep/gitleaks).
• Python CLI first: python3 a2dev_cli.py drives all flows.
• Node wrapper available: run via npx a2dev <cmd> (wraps the Python CLI under the hood).

Optimized for Codex

• Stdio tools: all commands print human‑first output; easy to wire in Codex via tool definitions (see .a2dev/codex/tools.*.json generated by the CLI) or invoke directly (e.g., python3 a2dev_cli.py route "@pm develop 2").
• Conversational router: messages starting with @analyst/@pm/@dev/@spm or *command route through a2dev route for role‑aware actions and status lines.
• Deterministic artifacts: outputs live under docs/*, enabling Codex to reason over concrete files instead of volatile context.
• Minimal deps: avoids network calls by default; suitable for local/offline development.
• Handoff: after assessment, the CLI prints “Handoff to Codex” with suggested next chat commands (e.g., @pm develop <id>). Route chat by calling python3 a2dev_cli.py route "<message>" from your Codex harness.
• Role persistence: the example router reads .a2dev/state.json and forwards un‑prefixed messages to the active role for a smooth dialogue (e.g., type @analyst, then assess fresh).
• Integration guide: see docs/integrations/Codex.md for tool registration and system prompt.

Quick Start

• Node (npx): npx -y -p github:<your-repo>/A2Dev a2dev install
• Python: python3 a2dev_cli.py install --dest .
• Meet the Analyst: a2dev route "@analyst" (or python3 a2dev_cli.py route "@analyst")
• Continue: a2dev pm story 1 or a2dev route "@pm next"
• .env.local is loaded automatically; copy .env.example if needed.

Readiness

• Doctor: a2dev doctor — checks tools (rg/ctags/semgrep/gitleaks), runs a code quality audit, and prints next steps.
• One-button install: a2dev doctor --fix — attempts to install missing tools (macOS: Homebrew; Debian/Ubuntu: apt + pipx; Windows: Chocolatey/Winget if available).
• Setup menu (optional): a2dev quickstart — interactive helper, but installation is uniform. Choose paths here only if you prefer menus; otherwise use @analyst to select Fresh/Prepared/Codebase conversationally.
• Dry-run mode: add --dry-run to any command (e.g., a2dev --dry-run pm story 1) to list planned writes and skip file changes.

Python CLI

• Use the Python CLI directly:
  • python3 a2dev_cli.py install --dest .
  • python3 a2dev_cli.py plan docs/PRD.md
  • python3 a2dev_cli.py pm story 1

Modes: Greenfield vs Brownfield

• Greenfield (new app)
  • Author docs/PRD.md (use the template if needed).
  • a2dev assess docs/PRD.md → backlog + epics.
  • a2dev pm story 1 (add --scaffold to create stubs).
  • Iterate: update PRD/backlog, re-run assess, continue PM pipeline.
• Brownfield (existing app with users)
  • Inventory: a2dev brownfield-inventory → writes docs/analyst/brownfield-inventory.{json,md} (languages, manifests, infra, deps).
  • Architecture snapshot: a2dev arch-brownfield --name "Your App" → docs/architecture/brownfield-architecture.md.
  • Assessment: a2dev assess-brownfield --name "Your App" → docs/analyst/brownfield-assessment.md.
  • Update PRD: integrate findings into docs/PRD.md (Current State, Constraints, Risks) then run a2dev assess docs/PRD.md.
  • Continue with PM pipeline: a2dev pm next or a2dev pm story <id>.

What You Get

• docs/backlog.json — epics/stories parsed from the PRD.
• docs/epics.md — human‑readable outline.
• docs/ux/story-<id>.md — UX document per story.
• features/story-<id>/ — Eng scaffold for implementation (placeholder files).
• .a2dev/state.json — coordinator state and pointers.

Design Principles

• PM as coordinator: a single orchestrator plans, gates, and delegates.
• Tools over agents: each role is a tool with clear contracts and artifacts.
• Traceability: every decision/artifact is file‑based and reviewable.
• Idempotence: steps can be re‑run safely; the PM resumes from state.

Model Selection

• The scaffold includes a2dev/models.py and a2dev/llm.py to route tasks by task type. Edit REGISTRY and select_model as needed.
• Tier control: set A2A_MODEL_TIER=high|medium|low (falls back to CODEX_MODEL_TIER/MODEL_TIER). Example: A2A_MODEL_TIER=medium python3 a2dev_cli.py sm-prepare 2.
• By default, LLM calls are stubbed; wire real SDKs and keys to enable generation.

Extending With LLMs

• The scaffold intentionally avoids network/deps. To use an LLM, implement the llm_summarize() and llm_backlog() hooks in a2a/llm.py and set OPENAI_API_KEY (or your provider of choice). Keep role outputs in the same schemas.

Slash Commands (optional)

• If you use a router in your harness, map:
  • /plan docs/PRD.md → python3 a2dev_cli.py plan docs/PRD.md
  • /ux <ids> → python3 a2dev_cli.py ux <ids>
  • /arch <id> → python3 a2dev_cli.py arch <id>
  • /plan-deep <id> → python3 a2dev_cli.py plan-deep <id>
  • /qa <id> → python3 a2dev_cli.py qa-plan <id>
  • /threat <id> → python3 a2dev_cli.py threat <id>
  • /devops <id> → python3 a2dev_cli.py devops-plan <id>
  • /data <id> → python3 a2dev_cli.py data-plan <id>
  • /trace <id> → python3 a2dev_cli.py trace <id>
  • /shard <id> → python3 a2dev_cli.py shard <id>
  • /gate <id> → python3 a2dev_cli.py gate <id>
  • /prepare <id> → python3 a2dev_cli.py prepare-story <id>

Structure

• .a2dev/ — state, policies, semgrep rules
• a2a/ — code (schemas, PM, roles, CLI)
• a2dev_cli.py — primary CLI entry
• docs/ — PRD, backlog, UX docs
• features/ — code scaffold per story
• See CONTRIBUTING.md and SECURITY.md for project policies.

Requirements

• Python 3.10+
• Recommended tools: ripgrep (rg), universal-ctags (ctags), semgrep, gitleaks.
• Optional env: A2A_MODEL_TIER=high|medium|low (Codex tier hint).

Secrets (.env.local)

• Copy .env.example to .env.local and fill in values.
• Supported keys: GITHUB_TOKEN, OPENAI_API_KEY, ANTHROPIC_API_KEY, OLLAMA_HOST.
• .env.local is ignored by git; loader is built-in (no extra deps).

Pre-commit Hook (optional)

• Copy .a2dev/hooks/pre-commit.sample to .git/hooks/pre-commit and chmod +x .git/hooks/pre-commit.
• This runs gitleaks (secrets) and semgrep (static analysis) before each commit.

Installation

• Option A — Script (recommended for existing repos)
  • python3 a2dev_cli.py install --dest /path/to/project
  • Creates .a2dev/ (policies, semgrep), copies a2dev_cli.py, PR template, and a sample docs/PRD.md if missing.
• Option B — Manual
  • Copy .a2dev/, a2dev_cli.py, AGENTS.md, and docs/PRD_SAMPLE.md into your repo.
  • Rename docs/PRD_SAMPLE.md → docs/PRD.md and customize.
• Bootstrap
  • python3 a2dev_cli.py bootstrap (checks tools and prints install hints).

Uninstallation (conservative)

• Dry run: python3 a2dev_cli.py uninstall (lists A2Dev files that would be removed)
• Remove: python3 a2dev_cli.py uninstall --force
• Note: This removes A2Dev scaffolding (e.g., .a2dev/, CLI shims, AGENTS.md, examples, tools). It does not remove your project docs or code under docs/* or features/.

NPX-like one-liners (Node/npm)

• Using npx from GitHub (public repo):
  • Prefer Python CLI directly (no Node wrapper required).
  • Optional: build a single-file runner a2dev.pyz if you choose to package one.
  • Private repos: use the Python CLI locally; no npm distribution required.

Using In Different Surfaces

• CLI
  • Open Analyst: python3 a2dev_cli.py route "@analyst"
  • Assess: python3 a2dev_cli.py route "@analyst assess docs/PRD.md"
  • Develop (PM): python3 a2dev_cli.py route "@pm develop 2" or python3 a2dev_cli.py pm next
  • Sustain (sPM): python3 a2dev_cli.py route "@spm sustain 2"
  • Timeline: python3 a2dev_cli.py timeline <assess|id>
• IDE (Codex)
  • Ensure a2dev_cli.py is at repo root.
  • Route @analyst/@pm/@dev/@spm or *develop messages to the route command.
  • Interact with a single persona (Analyst/PM/sPM) — PM coordinates sub‑agents.
• Web (Codex)
  • Commit .a2dev/, a2dev_cli.py, AGENTS.md.
  • Use the same conversational commands in chat, or run CLI commands in the terminal pane.

Codex Harness Example

• Register the route tool and forward @analyst/@pm/@spm/@dev or *command messages to python3 a2dev_cli.py route "<message>". Optionally mirror other tools (pm next, pm story, assess, develop, sustain, gate, timeline).

PM‑Driven Commands (minimal set)

• pm next — pick next story and prepare (UX→ADR→Plan→QA→Sec→DevOps→Data→Trace→Shard→Gate)
• pm continue — resume current story or pick next
• pm story <id> — prepare a specific story; add --scaffold to create code scaffolding
• assess <PRD.md> — Analyst creates brief + backlog and advances to Develop
• sustain <id> — sPM runs sustainment gate
• timeline <assess|id> — show timeline

Status & Journal

• A short status line prints after each action (phase, persona, agents used, docs created, refs, gate result).
• Human timeline: docs/timeline/assess.md, docs/timeline/story-<id>.md
• Structured journal: .a2dev/journal/*.jsonl

Security & Quality (local‑first)

• Gates:
  • Semgrep: rules in .a2dev/semgrep/rules.yml; results saved under docs/security/semgrep/; gate fails if high severity > 0.
  • Secrets: gitleaks results saved under docs/security/secrets/; gate fails on any finding.
• Policies: .a2dev/policies/ (Coding Standards, Code Review, Secure Coding, DoR, DoD)
• PR template: .github/pull_request_template.md references the policies.

Gate Criteria (what must exist per story)

• Acceptance criteria in docs/backlog.json and/or docs/stories/story-<id>.md.
• Required artifacts: UX, ADR, Deep Plan, QA Plan, Threat Model, DevOps Plan, Analytics Spec, Trace, and Story Shard.
• Static analysis: if docs/security/semgrep/story-<id>.json exists — no high severity findings.
• Secrets: if docs/security/secrets/story-<id>.json exists — zero findings.

README Best Practices (for your projects)

• Title: clear, concise project name.
• One‑liner: what it does in one sentence and who it’s for.
• Badges (optional): version, license, Python/Node version, etc.
• Table of Contents (for long READMEs).
• Requirements: languages, runtimes, OS caveats.
• Installation: copy‑paste commands for CLI, IDE, and Web usage.
• Quick Start: 3–5 commands from zero to demo.
• Usage: common workflows and minimal command list.
• Configuration: env vars, config files, secrets handling.
• Development: repo structure, how to run tests/lint, local debugging.
• Security: data classification, threat model location, scanning tools.
• Troubleshooting: common errors and quick fixes.
• License & Credits: clear licensing and attribution.

Troubleshooting

• Missing tools reported by bootstrap: install via Homebrew (macOS) or apt/pipx (Linux) per hints.
• Gate fails “Acceptance criteria missing”: add ACs in docs/PRD.md (then plan) or directly in docs/backlog.json.
• Semgrep high findings: open docs/security/semgrep/story-<id>.json and adjust code/policies.
• Secrets findings: rotate and remove secrets; re‑scan.
• If python3 a2dev_cli.py cannot import a2a, run from this repo (which contains a2a/) or set A2DEV_PY_PKG_PATH=/path/to/repo.

Publish (npm) Checklist (optional)

• Update package.json name/scope if publishing to npm (e.g., @your-scope/a2dev).
• Remove private: true and choose a license.
• Build a portable runner: npm run build:pyz (optional).
• Publish: npm publish (consider --access public for scoped packages).
• After publishing:
  • npx @your-scope/a2dev pm next (public)
  • or npm i -D @your-scope/a2dev to use the postinstall initializer in consuming repos.

One-liner install (npx style)

• Current (from GitHub): npx -y -p github:<your-user>/agile-addie-dev-framework a2dev install
• After publishing to npm: npx @your-scope/a2dev install

Installation Guide (CLI, IDE, Web)

• CLI
  • Prereqs: Python 3.10+, optional tools: ripgrep, ctags, semgrep, gitleaks.
  • Install: git clone <this repo> then python3 a2dev_cli.py install --dest /path/to/project.
  • Use: in your project root run A2Dev commands, e.g., python3 a2dev_cli.py route "@analyst assess docs/PRD.md".
• IDE (Codex)
  • Open your project in Codex IDE. Ensure a2dev_cli.py is at project root.
  • Route @analyst/@pm/@dev/@spm or *develop messages to python3 a2dev_cli.py route "<message>".
  • Interact: @analyst assess docs/PRD.md, @pm develop 2, @spm sustain 2.
• Web (Codex)
  • Commit .a2dev/ and a2dev_cli.py.
  • Configure your Codex Web project to run the router for chat messages or use the terminal.
  • Rely on status lines and docs/* artifacts as shared context.

Timeline Viewer

• Show assess timeline: python3 a2dev_cli.py timeline assess
• Show story timeline: python3 a2dev_cli.py timeline <id>

Security Gates

• Semgrep: rules under .a2dev/semgrep/rules.yml. Results: docs/security/semgrep/story-<id>.json. Gate fails if high severity > 0.
• Secrets: install gitleaks. Results: docs/security/secrets/story-<id>.json. Gate fails if any findings exist.

Proposals & Sprints Overview

• Proposals (PM planning aid):
  • Generate: python3 a2dev_cli.py story-proposals gen --capacity 20 --sprints all
  • Refine: python3 a2dev_cli.py story-proposals refine --accept 2,3 --estimate 6=3.0 --priority 2=must --capacity 20 --sprints all
  • Accept into backlog: python3 a2dev_cli.py story-proposals accept [--accept 2,3]
  • Outputs:
    • docs/proposals/proposed-backlog.json and .md
    • docs/proposals/sprint-<n>.md (one per sprint)
    • docs/proposals/plan.md (index of proposed sprints)
    • docs/proposals/summary.md (must/should/could counts and total points)
• PM Sprints (from current backlog):
  • Plan: python3 a2dev_cli.py pm-sprints --capacity 20 --weeks 2
  • Outputs:
    • docs/sprints/sprint-<n>.md and overall docs/sprints/plan.md

Command Summary

• a2dev install — initialize A2Dev files into the current project.
• a2dev bootstrap — check environment and suggest installs for rg, ctags, semgrep, gitleaks.
• a2dev assess docs/PRD.md — parse PRD and generate backlog + epics.
• a2dev pm story <id> — orchestrate artifacts and run gate; --scaffold to create code stub.
• a2dev pm next|continue — pick/continue a story by heuristic and prepare it.
• a2dev story-proposals gen|refine|accept — enrich backlog, plan sprints, and merge accepted estimates/priorities.
• a2dev pm-sprints --capacity 20 --weeks 2 — plan sprints from current backlog.
• a2dev gate <id> — check gate criteria for a story.
• a2dev timeline <assess|id> — show assess/story timeline.
• a2dev smoke — minimal end‑to‑end smoke.
• a2dev uninstall [--force] — conservative removal of installed files.
• a2dev doctor — environment + project readiness checks with audit summary.

Brownfield Wizard & Audit

• One‑shot wizard: a2dev brownfield --name "Your App" --append-prd --assess (inventory → architecture snapshot → assessment → PRD update → assess).
• Interactive menu: a2dev setup (Greenfield, Brownfield, Audit, Proposals/Sprints, Env, Bootstrap, Pre‑commit).
• Audit: a2dev audit writes docs/analyst/quality-audit.md (Semgrep/Gitleaks summary + hotspots) to guide stabilization vs. feature work.

Credits & Influences

• BMAD Method — Build‑Measure‑Analyze‑Decide (link to be added by maintainers).
• Agile ADDIE Framework — foundations and phases used by A2Dev (this project).
• Agile Manifesto — https://agilemanifesto.org/