@aman_asmuei/aman-agent 0.33.9 → 0.39.0

package/README.md

@@ -17,7 +17,7 @@
    
   <a href="https://github.com/amanasmuei/aman-agent/actions"><img src="https://img.shields.io/github/actions/workflow/status/amanasmuei/aman-agent/ci.yml?style=for-the-badge&logo=github&label=CI" alt="CI status" /></a>
   &nbsp;
-  <img src="https://img.shields.io/badge/tests-531_passing-brightgreen?style=for-the-badge&logo=vitest&logoColor=white" alt="531 tests passing" />
+  <img src="https://img.shields.io/badge/tests-865_passing-brightgreen?style=for-the-badge&logo=vitest&logoColor=white" alt="865 tests passing" />
   &nbsp;
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="MIT License" /></a>
 </p>
@@ -39,7 +39,7 @@
 </p>
 
 <p align="center">
-  <a href="#whats-new-in-v0330"><kbd> What's New </kbd></a>
+  <a href="#whats-new-in-v0350"><kbd> What's New </kbd></a>
   <a href="#quick-start"><kbd> Quick Start </kbd></a>
   <a href="#project-dev-mode-recommended"><kbd> Dev Mode </kbd></a>
   <a href="#architecture-at-a-glance"><kbd> Architecture </kbd></a>
@@ -61,7 +61,7 @@
 <details>
 <summary><strong>Table of Contents</strong></summary>
 
-- [What's New](#whats-new-in-v0330)
+- [What's New](#whats-new-in-v0350)
 - [The Problem](#the-problem)
 - [The Solution](#the-solution)
 - [Architecture at a Glance](#architecture-at-a-glance)
@@ -97,6 +97,129 @@
 
 ---
 
+## What's New in v0.35.0
+
+> **From companion to orchestrator.**
+
+### DAG-Based Task Orchestration Engine
+
+aman-agent can now decompose complex requirements into parallel task graphs and execute them with multiple specialized agents:
+
+```bash
+/orchestrate Build a REST API with auth, CRUD endpoints, input validation, and tests
+```
+
+```
+Decomposing requirement into task DAG...
+
+## REST API with Auth
+**Goal:** Build authenticated REST API with full test coverage
+**Tasks:** 5 | **Gates:** 1
+
+- **Design API schema** → architect [advanced] (root)
+- **Implement auth middleware** → coder [standard] (after: design)
+- **Implement CRUD endpoints** → coder [standard] (after: design)
+- **Write test suite** → tester [standard] (after: auth, crud)
+- **Security review** → security [standard] (after: tests)
+- 🔒 **Human approval before deploy** [approval]
+```
+
+| Feature | Details |
+|:---|:---|
+| **DAG scheduler** | Parallel execution of independent tasks, respects dependency ordering |
+| **Multi-tier model routing** | Routes tasks to fast/standard/advanced LLM tiers by complexity |
+| **Human approval gates** | Pauses orchestration at critical points for human review |
+| **Structured audit trail** | Every state transition logged with timestamps and context |
+| **LLM decomposition** | Natural language requirements → validated task DAGs via your LLM |
+| **Immutable state machine** | Correctness-critical orchestration lifecycle with 40+ transition tests |
+
+New module: `src/orchestrator/` (8 files, 114 tests).
+
+### GitHub-Native Automation (Phase 2)
+
+aman-agent now speaks GitHub natively. Issues become orchestration plans, CI status gates your workflow, and PRs get created automatically:
+
+```bash
+/github plan 42        # Decompose issue #42 into a task DAG
+/github issues         # List open issues
+/github prs            # List open PRs
+/github ci main        # Check CI status for a branch
+```
+
+| Feature | Details |
+|:---|:---|
+| **Issue-to-DAG pipeline** | Fetch any GitHub issue and decompose it into an orchestrator task DAG via your LLM |
+| **PR automation** | Create branches, open PRs, post review comments — all via `gh` CLI |
+| **CI gate polling** | Poll workflow run status, wait for CI to pass before proceeding |
+| **Safe CLI wrapper** | All `gh` commands use `execFile` (no shell) — immune to command injection |
+| **Repo-aware config** | Optional `github` config block for default repo, branch, and auto-PR settings |
+
+New module: `src/github/` (6 files, 64 tests).
+
+### Agent Factory Profiles & Templates (Phase 3)
+
+Specialized agent profiles power the orchestrator's multi-agent delegation. Each profile is tuned for its role:
+
+| Profile | Tier | Role |
+|:---|:---|:---|
+| **Architect** | advanced | System design, module decomposition, interface planning |
+| **Security** | standard | OWASP review, CVE audit, secrets detection, vulnerability triage |
+| **Tester** | standard | Test generation, edge case identification, coverage analysis |
+| **Reviewer** | standard | Code review with confidence-scored findings (critical/important/suggestion) |
+
+Pre-built orchestration templates for common workflows:
+
+```bash
+# Available templates:
+fullFeatureTemplate   # architect → parallel coders → review + test → finalize
+bugFixTemplate        # reproduce → fix → test → review
+securityAuditTemplate # scan → triage → [approval gate] → fix → rescan → review
+```
+
+Self-review loop: after orchestration completes, reviewer + tester agents automatically evaluate the output before marking success.
+
+New modules: `src/profiles/` (1 file), `src/orchestrator/templates/` (1 file), `src/orchestrator/review-loop.ts`. 49 new tests.
+
+### Universal Project Manager (Phase 4)
+
+aman-agent now understands your project type and structures orchestration accordingly:
+
+| Feature | Details |
+|:---|:---|
+| **Project classification** | Auto-detects project type (web-frontend, api-backend, mobile, ml-data, monorepo, etc.) from stack profile |
+| **Template mapping** | Maps project type → recommended orchestration template and agent profiles |
+| **Module boundary mapping** | Analyzes directory structure to assign non-overlapping file regions for parallel agents |
+| **Orchestration monitoring** | Structured metrics: phase timing, per-agent performance, approval gate tracking, formatted summaries |
+
+New module: `src/project/` (4 files, 33 tests).
+
+### Enterprise Hardening (Phase 5)
+
+Production-grade reliability and governance for orchestration at scale:
+
+| Feature | Details |
+|:---|:---|
+| **Circuit breaker** | Per-agent failure tracking with closed/open/half-open states. Prevents cascade failures when an agent is consistently failing. Auto-recovers after cooldown. |
+| **Checkpoint/resume** | Serialize full orchestration state to disk. Resume from crash — no lost progress on long-running orchestrations. |
+| **Cost tracker** | Token counting per LLM tier with budget enforcement. Tracks input/output tokens, estimates cost using tier-specific rates, blocks over-budget orchestrations. |
+| **Policy engine** | 7 built-in rules: max task count, requires review/testing, no orphan nodes, approval before deploy, advanced tier awareness, max depth. Custom rules supported. |
+
+All Phase 5 modules integrated into the orchestrator public API. 60 new tests. The [Universal Master Orchestrator](docs/superpowers/plans/2026-04-12-master-orchestrator-architecture.md) vision is now complete.
+
+---
+
+<details>
+<summary><strong>v0.34.0 — Multi-editor dev mode</strong></summary>
+
+- `aman-agent dev --copilot` targets GitHub Copilot (writes `.github/copilot-instructions.md`)
+- `aman-agent dev --cursor` targets Cursor (writes `.cursorrules`)
+- Multi-project simultaneous sessions sharing the same memory database
+
+</details>
+
+<details>
+<summary><strong>v0.33.0 — Project Dev Mode</strong></summary>
+
 ## What's New in v0.33.0
 
 > **One command. Full context. Zero setup.**
@@ -121,15 +244,17 @@ $ aman-agent dev ~/projects/amantrade
 
 | Flag | What it does |
 |:---|:---|
-| `--smart` | Use your configured LLM to synthesize a smarter CLAUDE.md |
-| `--yolo` | Launch Claude Code with `--dangerously-skip-permissions` (full autonomous mode) |
-| `--no-launch` | Generate CLAUDE.md only, don't start Claude Code |
+| `--smart` | Use your configured LLM to synthesize a smarter context file |
+| `--yolo` | Launch with skip-permissions (Claude Code only) |
+| `--copilot` | Target GitHub Copilot — writes `.github/copilot-instructions.md`, opens VS Code |
+| `--cursor` | Target Cursor — writes `.cursorrules`, opens Cursor |
+| `--no-launch` | Generate context file only, don't launch editor |
 | `--diff` | Preview what would change without writing |
-| `--force` | Regenerate even if CLAUDE.md is fresh |
+| `--force` | Regenerate even if context file is fresh |
 
 Works with **multiple projects** simultaneously — each terminal gets its own `aman-agent dev`, all sharing the same memory database. Decisions from one project flow into the next.
 
----
+</details>
 
 <details>
 <summary><strong>v0.32.0 — Install anywhere, zero prerequisites</strong></summary>
@@ -235,7 +360,7 @@ npx @aman_asmuei/aman-agent
 
 ## Architecture at a Glance
 
-aman-agent is the **runtime** at the center of the aman ecosystem — 38 focused TypeScript modules that stitch together 7 portable memory/identity/skill layers with any LLM you want.
+aman-agent is the **runtime** at the center of the aman ecosystem — 52 focused TypeScript modules that stitch together 7 portable memory/identity/skill layers with any LLM you want.
 
 ```mermaid
 flowchart LR
@@ -243,6 +368,7 @@ flowchart LR
 
     CLI --> Agent[agent.ts<br/>message orchestration]
     Agent --> Hooks[hooks.ts<br/>lifecycle events]
+    Agent --> Orch[orchestrator/<br/>DAG scheduler]
 
     Agent -->|recall &amp; extract| Memory[(amem-core<br/>SQLite + vectors)]
     Agent -->|who &amp; prefs| Identity[(acore-core<br/>identity)]
@@ -250,6 +376,9 @@ flowchart LR
     Agent -->|auto-trigger| Skills[skill-engine<br/>+ crystallization]
     Agent -->|telemetry| Obs[observation<br/>+ postmortem]
 
+    Orch -->|delegate tasks| Delegate[delegate.ts<br/>+ teams.ts]
+    Orch -->|tier routing| LLM
+
     Agent --> LLM{LLM Router}
     LLM --> Claude[Anthropic]
     LLM --> GPT[OpenAI]
@@ -261,9 +390,11 @@ flowchart LR
     classDef core fill:#58a6ff22,stroke:#58a6ff,color:#e6edf3,stroke-width:2px;
     classDef store fill:#3fb95022,stroke:#3fb950,color:#e6edf3,stroke-width:2px;
     classDef llm fill:#d29f2222,stroke:#d29f22,color:#e6edf3,stroke-width:1px;
+    classDef orch fill:#a371f722,stroke:#a371f7,color:#e6edf3,stroke-width:2px;
     class CLI,Agent,Hooks,Skills,Obs core
     class Memory,Identity,Rules store
     class Claude,GPT,Copilot,Ollama,LLM llm
+    class Orch,Delegate orch
 ```
 
 <details>
@@ -272,7 +403,11 @@ flowchart LR
 | Piece | What it does | Where it lives |
 |:---|:---|:---|
 | `agent.ts` | The main event loop — reads your message, recalls memories, streams the LLM response, executes tools, extracts new memories | `src/agent.ts` (40 KB) |
-| `commands.ts` | 58+ slash commands (`/memory`, `/skills`, `/plan`, `/delegate`, `/eval`, `/observe`, `/postmortem`, …) | `src/commands.ts` (98 KB) |
+| `commands.ts` | 60+ slash commands (`/memory`, `/skills`, `/plan`, `/delegate`, `/orchestrate`, `/eval`, `/observe`, `/postmortem`, …) | `src/commands.ts` (100 KB) |
+| `orchestrator/` | DAG-based task decomposition, parallel scheduling, multi-tier model routing, approval gates, audit trails | `src/orchestrator/` (8 files) |
+| `github/` | GitHub-native automation — issue planning, PR management, CI gates, safe `gh` CLI wrapper | `src/github/` (6 files) |
+| `profiles/` | Specialized agent profiles for orchestrator delegation (architect, security, tester, reviewer) | `src/profiles/` |
+| `orchestrator/templates/` | Pre-built DAG templates for common workflows (full-feature, bug-fix, security-audit) | `src/orchestrator/templates/` |
 | `hooks.ts` | 5 lifecycle hooks that fire at startup, before/after tools, on workflow match, on session end | `src/hooks.ts` (26 KB) |
 | `memory.ts` + `memory-extractor.ts` | Per-message recall and silent, non-blocking extraction of preferences, decisions, patterns, corrections | delegates to `@aman_asmuei/amem-core@0.5` |
 | `skill-engine.ts` + `crystallization.ts` | Auto-triggers domain skills from context; promotes post-mortem lessons into reusable, versioned skills | `src/skill-engine.ts`, `src/crystallization.ts` |
@@ -407,14 +542,22 @@ aman-agent dev --smart
 
 The LLM merges related corrections into single convention statements and removes redundancy. Falls back to template mode automatically if the LLM call fails.
 
-**Yolo mode** — Full autonomous, no permission prompts:
+**Multi-editor support** — Same memory, any editor:
 
 ```bash
-aman-agent dev --yolo          # skip permissions
-aman-agent dev --yolo --smart  # skip permissions + LLM-generated CLAUDE.md
+aman-agent dev                 # Claude Code (default) → CLAUDE.md
+aman-agent dev --copilot       # VS Code + Copilot → .github/copilot-instructions.md
+aman-agent dev --cursor        # Cursor → .cursorrules
 ```
 
-Launches Claude Code with `--dangerously-skip-permissions`. Use when you trust the project and want zero friction.
+All three use the same pipeline: stack detection → amem recall → context assembly. Only the output file and launcher differ.
+
+**Yolo mode** — Full autonomous, no permission prompts (Claude Code only):
+
+```bash
+aman-agent dev --yolo          # skip permissions
+aman-agent dev --yolo --smart  # skip permissions + LLM-generated context
+```
 
 **Multi-project workflow** — Each terminal is independent:
 
@@ -1367,7 +1510,7 @@ sequenceDiagram
 | Command | Description |
 |:---|:---|
 | `aman-agent` | Start interactive chat session |
-| `aman-agent dev [path]` | Scan project, generate CLAUDE.md, launch Claude Code `[--smart\|--yolo\|--no-launch\|--force\|--diff]` |
+| `aman-agent dev [path]` | Scan project, generate context, launch editor `[--smart\|--yolo\|--copilot\|--cursor\|--no-launch\|--force\|--diff]` |
 | `aman-agent init` | Set up your AI companion with a guided wizard |
 | `aman-agent serve` | Run as a local MCP server for agent delegation `[--name\|--profile]` |
 | `aman-agent setup` | Full reconfiguration wizard |
@@ -1381,6 +1524,8 @@ sequenceDiagram
 | `/help` | Show available commands |
 | `/plan` | Show active plan `[create\|done\|undo\|list\|switch\|show]` |
 | `/profile` | Your profile + agent profiles `[me\|edit\|setup\|create\|list\|show\|delete]` |
+| `/orchestrate` | Decompose requirement into task DAG and execute with parallel agents `[<requirement>]` |
+| `/github` | GitHub operations `[issues\|prs\|plan <number>\|ci <branch>]` |
 | `/delegate` | Delegate task to a profile `[<profile> <task>\|pipeline]` |
 | `/agents` | Multi-agent A2A `[list\|info <name>\|ping <name>]` |
 | `/team` | Manage agent teams `[create\|run\|list\|show\|delete]` |