@aman_asmuei/aman-agent 0.34.0 → 0.40.0

package/README.md

@@ -8,8 +8,8 @@
 <h1 align="center">aman-agent</h1>
 
 <p align="center">
-  <strong>The AI companion that actually remembers you.</strong><br/>
-  <sub>Learns from every conversation. Recalls what matters. Runs locally. Works with any LLM.</sub>
+  <strong>The AI companion that remembers you — and orchestrates your entire dev workflow.</strong><br/>
+  <sub>Per-message memory. Multi-agent orchestration. GitHub-native. Runs locally. Any LLM.</sub>
 </p>
 
 <p align="center">
@@ -17,7 +17,7 @@
   &nbsp;
   <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-912_passing-brightgreen?style=for-the-badge&logo=vitest&logoColor=white" alt="912 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>
@@ -27,7 +27,7 @@
   &nbsp;
   <img src="https://img.shields.io/badge/typescript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="Strict TypeScript" />
   &nbsp;
-  <img src="https://img.shields.io/badge/bundle-384_KB-informational?style=flat-square" alt="Bundle size: 384 KB" />
+  <img src="https://img.shields.io/badge/bundle-388_KB-informational?style=flat-square" alt="Bundle size: 388 KB" />
   &nbsp;
   <img src="https://img.shields.io/badge/LLMs-6_providers-8a2be2?style=flat-square" alt="6 LLM providers" />
   &nbsp;
@@ -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-v0390"><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-v0390)
 - [The Problem](#the-problem)
 - [The Solution](#the-solution)
 - [Architecture at a Glance](#architecture-at-a-glance)
@@ -78,6 +78,8 @@
   - [Customization](#customization)
   - [Showcase Templates](#showcase-templates)
   - [Profiles](#your-profile-vs-agent-profiles)
+  - [Task Orchestration](#task-orchestration)
+  - [GitHub Automation](#github-automation)
   - [Delegation](#agent-delegation)
   - [Teams](#agent-teams)
   - [Multi-agent (A2A)](#multi-agent-a2a)
@@ -97,11 +99,70 @@
 
 ---
 
-## What's New in v0.33.0
+## What's New in v0.39.0
 
-> **One command. Full context. Zero setup.**
+> **From companion to orchestrator.** Describe what you want to build — aman-agent decomposes it, delegates to specialized agents, and delivers reviewed results.
 
-### `aman-agent dev` — Your New Way to Start Coding
+```bash
+/orchestrate Build a REST API with auth, CRUD endpoints, input validation, and tests
+```
+
+```
+## REST API with Auth
+**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]
+```
+
+Five new modules shipped as the Universal Master Orchestrator:
+
+| Phase | What it adds |
+|:---|:---|
+| **1. Orchestrator Engine** | DAG scheduler, multi-tier LLM routing (fast/standard/advanced), approval gates, audit trails |
+| **2. GitHub-Native** | `/github plan 42` turns issues into DAGs, auto PRs, CI gate polling, safe `gh` CLI wrapper |
+| **3. Agent Factory** | 4 profiles (architect, security, tester, reviewer), 3 workflow templates, self-review loop |
+| **4. Project Manager** | Auto-classifies project type, maps module boundaries for parallel agents, orchestration monitoring |
+| **5. Enterprise** | Circuit breakers, checkpoint/resume, cost tracking with budget enforcement, 7-rule policy engine |
+
+**+334 tests** (867 total) across 25 new source files. [Full release notes →](https://github.com/amanasmuei/aman-agent/releases/tag/v0.39.0)
+
+<details>
+<summary><strong>Phase-by-phase details</strong></summary>
+
+**Orchestrator Engine** — Decomposes requirements into a validated DAG (directed acyclic graph) via your LLM. Scheduler runs parallel branches respecting dependencies, pauses at human approval gates, routes each task to the right LLM tier. Immutable state machine prevents invalid transitions. Structured audit trail logs every event.
+
+**GitHub-Native Automation** — `/github plan <issue#>` fetches an issue and decomposes it. `/github ci <branch>` polls workflow status. PR manager creates branches, opens PRs, and posts review comments. All commands use `execFile` (no shell injection).
+
+**Agent Factory** — Four specialized profiles: **Architect** (system design, tier: advanced), **Security** (OWASP, CVE audit), **Tester** (test generation, edge cases), **Reviewer** (confidence-scored findings). Three DAG templates: `fullFeatureTemplate` (architect → coders → review + test → finalize), `bugFixTemplate`, `securityAuditTemplate`. Self-review loop runs reviewer + tester on completed output.
+
+**Project Manager** — Classifies projects as web-frontend, api-backend, mobile, ml-data, monorepo, etc. Maps project type to recommended template and profiles. Module boundary mapper assigns non-overlapping file regions for parallel agents. Monitoring tracks phase timing, per-agent performance, and approval gates.
+
+**Enterprise Hardening** — Circuit breaker per agent (closed/open/half-open with auto-recovery). Checkpoint/resume serializes orchestration state to disk. Cost tracker counts tokens per tier with budget enforcement. Policy engine enforces 7 built-in rules (max tasks, requires review/testing, approval before deploy, etc.) with custom rule support.
+
+</details>
+
+---
+
+<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>
+
+**One command. Full context. Zero setup.**
+
+**`aman-agent dev` — Your New Way to Start Coding**
 
 ```bash
 cd ~/projects/amantrade && aman-agent dev
@@ -131,7 +192,7 @@ $ aman-agent dev ~/projects/amantrade
 
 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>
@@ -225,7 +286,7 @@ Other "memory" solutions are just markdown files the AI reads on startup — the
 
 ## The Solution
 
-**aman-agent** is the first open-source AI companion that genuinely learns from conversation. It doesn't just store memories — it recalls them per-message, extracts new knowledge automatically, and uses your LLM to intelligently compress context instead of truncating it.
+**aman-agent** is the first open-source AI companion that genuinely learns from conversation and orchestrates multi-agent workflows. It recalls memories per-message, extracts new knowledge automatically, decomposes complex requirements into parallel task graphs, and delegates to specialized agents — all running locally with any LLM.
 
 ```bash
 npx @aman_asmuei/aman-agent
@@ -237,35 +298,76 @@ 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 — 78 TypeScript modules that stitch together memory, identity, orchestration, and any LLM into one coherent system.
 
 ```mermaid
-flowchart LR
-    User([You]) <--> CLI[aman-agent CLI<br/>chat loop]
+flowchart TB
+    User([You]) <--> CLI[aman-agent CLI]
+
+    subgraph core [" Agent Core "]
+        Agent[agent.ts<br/>message loop]
+        Hooks[hooks.ts<br/>lifecycle]
+        Skills[skill-engine<br/>+ crystallization]
+        Obs[observation<br/>+ postmortem]
+        Personality[user-model<br/>+ personality]
+    end
+
+    subgraph orchestrator [" Orchestrator Engine "]
+        DAG[DAG scheduler<br/>parallel execution]
+        Decompose[LLM decompose<br/>requirement → DAG]
+        Templates[workflow templates<br/>feature · bugfix · audit]
+        ReviewLoop[self-review loop<br/>reviewer + tester]
+        Gate[approval gates<br/>+ CI gates]
+        CB[circuit breaker<br/>+ checkpoint]
+        Policy[policy engine<br/>+ cost tracker]
+    end
 
-    CLI --> Agent[agent.ts<br/>message orchestration]
-    Agent --> Hooks[hooks.ts<br/>lifecycle events]
+    subgraph github [" GitHub-Native "]
+        GH[gh CLI wrapper]
+        Issues[issue → DAG<br/>planner]
+        PRs[PR manager<br/>+ CI polling]
+    end
+
+    subgraph project [" Project Manager "]
+        Detect[project classifier<br/>stack → type]
+        ModMap[module boundary<br/>mapper]
+        Monitor[orchestration<br/>monitoring]
+    end
 
+    CLI --> Agent
+    Agent --> Hooks
+    Agent --> orchestrator
     Agent -->|recall &amp; extract| Memory[(amem-core<br/>SQLite + vectors)]
-    Agent -->|who &amp; prefs| Identity[(acore-core<br/>identity)]
-    Agent -->|boundaries| Rules[(arules-core<br/>guardrails)]
-    Agent -->|auto-trigger| Skills[skill-engine<br/>+ crystallization]
-    Agent -->|telemetry| Obs[observation<br/>+ postmortem]
+    Agent -->|identity| Identity[(acore-core)]
+    Agent -->|guardrails| Rules[(arules-core)]
+
+    orchestrator --> Delegate[delegate.ts<br/>+ teams.ts]
+    orchestrator --> Profiles[agent profiles<br/>architect · security<br/>tester · reviewer]
+    orchestrator --> github
+    orchestrator --> project
 
     Agent --> LLM{LLM Router}
     LLM --> Claude[Anthropic]
     LLM --> GPT[OpenAI]
     LLM --> Copilot[GH Copilot]
-    LLM --> Ollama[Ollama local]
+    LLM --> Ollama[Ollama]
 
-    Agent <--> MCP[MCP tools<br/>aman-mcp · amem]
+    Agent <-->|MCP| MCP[aman-mcp · amem]
 
-    classDef core fill:#58a6ff22,stroke:#58a6ff,color:#e6edf3,stroke-width:2px;
-    classDef store fill:#3fb95022,stroke:#3fb950,color:#e6edf3,stroke-width:2px;
+    classDef core fill:#58a6ff15,stroke:#58a6ff,color:#e6edf3,stroke-width:2px;
+    classDef orch fill:#a371f715,stroke:#a371f7,color:#e6edf3,stroke-width:2px;
+    classDef gh fill:#3fb95015,stroke:#3fb950,color:#e6edf3,stroke-width:2px;
+    classDef proj fill:#d29f2215,stroke:#d29f22,color:#e6edf3,stroke-width:2px;
+    classDef store fill:#3fb95022,stroke:#3fb950,color:#e6edf3,stroke-width:1px;
     classDef llm fill:#d29f2222,stroke:#d29f22,color:#e6edf3,stroke-width:1px;
-    class CLI,Agent,Hooks,Skills,Obs core
+
+    class Agent,Hooks,Skills,Obs,Personality core
+    class DAG,Decompose,Templates,ReviewLoop,Gate,CB,Policy orch
+    class GH,Issues,PRs gh
+    class Detect,ModMap,Monitor proj
     class Memory,Identity,Rules store
     class Claude,GPT,Copilot,Ollama,LLM llm
+    class Delegate,Profiles,MCP core
 ```
 
 <details>
@@ -274,7 +376,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` |
@@ -836,6 +942,99 @@ Each agent profile has its own identity, rules, and skills — but shares the sa
 
 </details>
 
+<details>
+<summary><strong>Task Orchestration</strong> (new in v0.39)</summary>
+
+### Task Orchestration
+
+Describe what you want to build — aman-agent decomposes it into a DAG of tasks, assigns each to the right specialist agent, and executes them in parallel:
+
+```
+You > /orchestrate Add user authentication with JWT, password hashing, and rate limiting
+
+  Decomposing requirement into task DAG...
+
+  ## User Authentication
+  **Goal:** JWT auth with security hardening
+  **Tasks:** 5 | **Gates:** 1
+
+  - **Design auth architecture** → architect [advanced] (root)
+  - **Implement JWT middleware** → coder [standard] (after: design)
+  - **Add rate limiting** → coder [standard] (after: design)
+  - **Write test suite** → tester [standard] (after: jwt, rate-limit)
+  - **Security review** → security [standard] (after: tests)
+  - 🔒 **Human approval** [approval]
+```
+
+**How it works:**
+1. Your LLM decomposes the requirement into a validated DAG (no cycles, valid refs)
+2. The scheduler runs independent tasks in parallel (configurable concurrency)
+3. Each task is routed to the right LLM tier — Haiku for simple, Sonnet for coding, Opus for architecture
+4. Approval gates pause execution for human review at critical points
+5. After completion, the self-review loop runs reviewer + tester agents on the output
+6. Circuit breakers prevent cascade failures; checkpoints enable crash recovery
+
+**Pre-built templates:**
+
+```
+/orchestrate --template full-feature   # architect → coders → review + test
+/orchestrate --template bug-fix        # reproduce → fix → test → review
+/orchestrate --template security-audit # scan → triage → fix → rescan
+```
+
+**Cost awareness:** The cost tracker monitors token usage per tier. Set a budget limit in config to prevent runaway costs.
+
+</details>
+
+<details>
+<summary><strong>GitHub Automation</strong> (new in v0.39)</summary>
+
+### GitHub Automation
+
+aman-agent speaks GitHub natively via the `gh` CLI:
+
+```
+You > /github
+
+  Repo: amanasmuei/aman-agent (authenticated)
+  Branch: main
+
+You > /github issues --limit 5
+
+  #42  Add user auth          feature, security    alice
+  #41  Fix login redirect     bug                  bob
+  #40  Update dependencies    chore                unassigned
+  ...
+
+You > /github plan 42
+
+  Fetching issue #42: "Add user auth"...
+  Decomposing into task DAG...
+
+  ## Add user auth
+  **Tasks:** 4 | **Gates:** 1
+  - **Design auth flow** → architect [advanced] (root)
+  - **Implement JWT** → coder [standard] (after: design)
+  - **Write tests** → tester [standard] (after: implement)
+  - **Security review** → security [standard] (after: tests)
+
+You > /github ci main
+
+  CI Status: ✓ passing (workflow: ci.yml, 2m ago)
+```
+
+**Available commands:**
+
+| Command | Description |
+|:---|:---|
+| `/github` | Show current repo info and auth status |
+| `/github issues` | List open issues |
+| `/github prs` | List open pull requests |
+| `/github plan <number>` | Decompose issue into orchestrator task DAG |
+| `/github ci <branch>` | Check CI status for a branch |
+
+</details>
+
 <details>
 <summary><strong>Agent Delegation</strong></summary>
 
@@ -1391,6 +1590,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]` |