@aman_asmuei/aman-agent 0.41.0 → 0.43.0

package/README.md

@@ -19,6 +19,8 @@
    
   <img src="https://img.shields.io/badge/tests-917_passing-brightgreen?style=for-the-badge&logo=vitest&logoColor=white" alt="917 tests passing" />
   &nbsp;
+  <a href="https://github.com/amanasmuei/aman-claude-code"><img src="https://img.shields.io/badge/Claude_Code-plugin-8A2BE2?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude Code plugin" /></a>
+  &nbsp;
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="MIT License" /></a>
 </p>
 
@@ -39,8 +41,9 @@
 </p>
 
 <p align="center">
-  <a href="#whats-new-in-v0390"><kbd> What's New </kbd></a>
+  <a href="#whats-new-in-v0410"><kbd> What's New </kbd></a>
   <a href="#quick-start"><kbd> Quick Start </kbd></a>
+  <a href="#claude-code-plugin-recommended"><kbd> Plugin </kbd></a>
   <a href="#project-dev-mode-recommended"><kbd> Dev Mode </kbd></a>
   <a href="#architecture-at-a-glance"><kbd> Architecture </kbd></a>
   <a href="#features"><kbd> Features </kbd></a>
@@ -52,7 +55,12 @@
 
 <p align="center">
   <sub>
-    <b>Install in 10 seconds →</b>&nbsp;&nbsp;<code>curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-agent/main/install.sh | bash</code>
+    <b>Drop into Claude Code →</b>&nbsp;&nbsp;<code>claude plugin marketplace add amanasmuei/aman-claude-code</code>&nbsp;•&nbsp;<code>claude plugin install aman-claude-code@aman</code>
+  </sub>
+</p>
+<p align="center">
+  <sub>
+    Prefer a standalone CLI? See <a href="#standalone-cli-install">Standalone CLI install</a> below.
   </sub>
 </p>
 
@@ -61,11 +69,12 @@
 <details>
 <summary><strong>Table of Contents</strong></summary>
 
-- [What's New](#whats-new-in-v0390)
+- [What's New](#whats-new-in-v0410)
 - [The Problem](#the-problem)
 - [The Solution](#the-solution)
 - [Architecture at a Glance](#architecture-at-a-glance)
 - [Quick Start](#quick-start)
+- [Standalone CLI install](#standalone-cli-install)
 - [Usage Guide](#usage-guide)
   - [Project Dev Mode](#project-dev-mode-recommended)
   - [Your First Conversation](#your-first-conversation)
@@ -99,50 +108,88 @@
 
 ---
 
-## What's New in v0.39.0
+## What's New in v0.42.0
 
-> **From companion to orchestrator.** Describe what you want to build — aman-agent decomposes it, delegates to specialized agents, and delivers reviewed results.
+> **Your memory, as plain Markdown.** Every memory is now mirrored to `~/.aman-agent/memories/` as a `.md` file you can read, edit, git-commit, or sync via Dropbox/iCloud.
 
 ```bash
-/orchestrate Build a REST API with auth, CRUD endpoints, input validation, and tests
+# snapshot your memory to any dir
+aman-agent  # then: /memory export --to ~/backups/amem
+
+# see mirror status
+/memory mirror status
+
+# rebuild if you lose the DB but have the files
+/memory mirror rebuild
+
+# pull edits from a synced folder (multi-device)
+/memory sync --from ~/Dropbox/aman-memories
 ```
 
+**What you get:**
+
+- Round-trip contract — files round-trip cleanly through amem-core's existing sync parser.
+- Multi-device sync — on every `aman-agent` startup, edits in the mirror dir are imported back into the DB (disable via `config.mirror.autoSyncOnStartup = false`).
+- No lock-in — plain YAML-frontmatter Markdown. If you ever stop using aman-agent, the memories stay useful anywhere.
+- Opt-out with one flag: `config.mirror.enabled = false` disables all mirror I/O.
+
+Requires `@aman_asmuei/amem-core@0.6.0` (shipped simultaneously).
+
+---
+
+## What's New in v0.41.0
+
+> **From companion to orchestrator — fully wired.** One command decomposes, delegates, reviews, and tracks cost.
+
+```bash
+/orchestrate Build user auth with JWT, password hashing, rate limiting, 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]
 ```
+Project type: api-backend (auto-detected)
+Template: full-feature
 
-Five new modules shipped as the Universal Master Orchestrator:
+## User Authentication
+**Tasks:** 5 | **Gates:** 1
 
-| 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 |
+- **Design auth architecture** → architect [advanced] (root)
+- **Implement JWT middleware** → coder [standard] (after: design)
+- **Add rate limiting** → coder [standard] (after: design)       ← parallel
+- **Write test suite** → tester [standard] (after: jwt, rate-limit)
+- **Security review** → security [standard] (after: tests)
+- 🔒 **Human approval** [approval gate]
 
-**+334 tests** (867 total) across 25 new source files. [Full release notes →](https://github.com/amanasmuei/aman-agent/releases/tag/v0.39.0)
+Status: completed (34.2s)
+Cost: ~$0.12 (3 standard + 1 advanced)
+Policy: passed (0 errors, 2 warnings)
+```
 
-<details>
-<summary><strong>Phase-by-phase details</strong></summary>
+**What happens in that one command:**
+
+1. Auto-detects project type from your cwd (web-frontend, api-backend, mobile, etc.)
+2. Selects the best orchestration template (or decomposes via LLM)
+3. Runs policy check (7 built-in rules — requires review, testing, approval gates)
+4. Executes DAG with parallel agent scheduling and circuit breakers
+5. Tracks LLM cost per tier with budget enforcement
+6. Self-review loop: reviewer + tester evaluate output before completion
 
-**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.
+**Flags:** `--template bug-fix`, `--no-review`, `--no-policy`
 
-**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).
+**GitHub-native:** `/github plan 42` does the same thing, starting from a GitHub issue.
 
-**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.
+<details>
+<summary><strong>The full stack (5 modules, 917 tests)</strong></summary>
 
-**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.
+| Module | What it does |
+|:---|:---|
+| **Orchestrator Engine** | DAG scheduler, multi-tier LLM routing (fast/standard/advanced), approval gates, structured audit trails, immutable state machine |
+| **GitHub-Native** | Safe `gh` CLI wrapper, issue-to-DAG planner, PR manager, CI gate polling |
+| **Agent Factory** | 4 profiles (architect, security, tester, reviewer), 3 workflow templates (full-feature, bug-fix, security-audit), self-review loop |
+| **Project Manager** | Project type classifier, module boundary mapper for parallel agents, orchestration monitoring |
+| **Enterprise** | Circuit breakers (closed/open/half-open), checkpoint/resume, cost tracking + budget enforcement, 7-rule policy engine |
+| **Integration** | Unified runner (`runOrchestrationFull`), smart orchestrate (`smartOrchestrate`), profile auto-install |
 
-**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.
+28 new source files, 32 new test files. [Full release notes →](https://github.com/amanasmuei/aman-agent/releases/tag/v0.41.0)
 
 </details>
 
@@ -296,6 +343,8 @@ npx @aman_asmuei/aman-agent
 
 ---
 
+> **New to the ecosystem?** See [docs/ecosystem.md](docs/ecosystem.md) for "which package do I install, and when" + the full package relationship diagram.
+
 ## Architecture at a Glance
 
 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.
@@ -396,22 +445,70 @@ flowchart TB
 
 ---
 
-## Quick Start
+## Install tiers — pick what you need
 
-### 1. Install
+The aman ecosystem is ~10 packages. You don't need them all. Pick a tier:
+
+### Minimal (2 packages, 2 minutes)
+
+Just `aman-agent` + persistent memory. Standalone CLI, works with any LLM provider. Best for "does this feel useful?" evaluation.
 
 ```bash
-# One-liner install (no Node.js required) — Linux, macOS, Raspberry Pi
-curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-agent/main/install.sh | bash
+npm install -g @aman_asmuei/aman-agent @aman_asmuei/amem-core
+# or, once you have Node 18+:
+curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-agent/main/bin/aman-setup.sh | bash
+```
 
-# Or via npm (if you already have Node.js 18+)
-npm install -g @aman_asmuei/aman-agent
+What you get: `aman-agent` CLI, per-message memory recall, memory extraction, `/memory` commands.
 
-# Or via Docker
-docker run -it -e ANTHROPIC_API_KEY=sk-... ghcr.io/amanasmuei/aman-agent
+### Productive (5 packages, 10 minutes)
+
+Minimal + identity + guardrails + Claude Code integration. Adds your AI's personality, rules the LLM must respect, and first-class Claude Code plugin support.
+
+```bash
+npm install -g @aman_asmuei/aman-agent @aman_asmuei/amem-core \
+  @aman_asmuei/acore-core @aman_asmuei/arules-core @aman_asmuei/aman-mcp
+# + install the Claude Code plugin:
+# see aman-claude-code repo README
 ```
 
-### 2. Run
+What you get (on top of Minimal): named companion ("Aman" by default), rule enforcement via `/rules`, auto-loaded ecosystem context at session start, MCP tools for memory/identity/rules from inside Claude Code.
+
+### Complete (all packages, 30 minutes)
+
+Everything: orchestration, multi-agent delegation, showcase personalities, tool installer, skill manager, VS Code Copilot integration.
+
+```bash
+# After Productive, add:
+npm install -g @aman_asmuei/aman-copilot @aman_asmuei/akit @aman_asmuei/askill @aman_asmuei/aman-showcase
+```
+
+What you get (on top of Productive): `/orchestrate` DAG task decomposition, `/delegate` + `/team` multi-agent workflows, `/showcase` 13 personality templates, `/akit` CLI tool manager, `/askill` skill library. VS Code Copilot users also get `aman-copilot` for inline Copilot Chat memory.
+
+**Not sure which tier?** Start with Minimal. You can layer Productive or Complete on top whenever you want — nothing gets overwritten, just extended.
+
+---
+
+## Quick Start
+
+### Claude Code plugin (recommended)
+
+If you already use Claude Code, this is the fastest path — no new CLI to install, no Node.js, no API key to paste. Install the plugin once and your full aman ecosystem (identity, rules, memory, skills, live tools) auto-loads every session.
+
+```bash
+claude plugin marketplace add amanasmuei/aman-claude-code
+claude plugin install aman-claude-code@aman
+```
+
+Then reload Claude Code (`/reload-plugins` or restart). That's it — type anything and aman-agent is already remembering you.
+
+> **Also on VS Code Copilot Chat or the Copilot CLI?** The [`aman-copilot`](https://github.com/amanasmuei/aman-copilot) sibling gives you the same identity, rules, and memory on those surfaces.
+
+### Run
+
+Inside Claude Code with the plugin installed, you don't run anything — just start chatting. Skip to [First Launch](#first-launch--youll-be-asked-about-you) for the one-time setup prompt.
+
+If you went with the [standalone CLI](#standalone-cli-install) instead:
 
 ```bash
 # Start a conversation
@@ -448,7 +545,7 @@ No env var? First run prompts for your LLM provider and model:
 
 **Ollama** — local models, no account needed.
 
-### 2. First Launch — You'll Be Asked About You
+### First Launch — You'll Be Asked About You
 
 On first run, a quick interactive setup captures who you are:
 
@@ -463,10 +560,10 @@ On first run, a quick interactive setup captures who you are:
 
 Takes ~30 seconds. Update anytime with `/profile edit`.
 
-### 3. Talk
+### Talk
 
 ```bash
-# Override model per session
+# Override model per session (standalone CLI)
 aman-agent --model claude-opus-4-6
 
 # Adjust system prompt token budget
@@ -475,6 +572,25 @@ aman-agent --budget 12000
 
 ---
 
+## Standalone CLI install
+
+For automation, CI, VPS, Raspberry Pi, or anyone who prefers the CLI directly — install the `aman-agent` binary. Everything above in Quick Start still applies once it's installed.
+
+```bash
+# One-liner install (no Node.js required) — Linux, macOS, Raspberry Pi
+curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-agent/main/install.sh | bash
+
+# Or via npm (if you already have Node.js 18+)
+npm install -g @aman_asmuei/aman-agent
+
+# Or via Docker
+docker run -it -e ANTHROPIC_API_KEY=sk-... ghcr.io/amanasmuei/aman-agent
+```
+
+Works on **Linux** (x64, arm64, armv7l), **macOS** (x64, Apple Silicon), **Raspberry Pi**, **VPS**, and **servers**. The installer vendors Node.js 22 LTS invisibly — no sudo, no prerequisites.
+
+---
+
 ## Usage Guide
 
 A step-by-step walkthrough of how to use aman-agent day-to-day. Click any section below to expand.
@@ -631,6 +747,27 @@ You > Let's add a new endpoint
 /decisions               View your decision log
 ```
 
+### Memory mirror (markdown)
+
+Your memory DB is great for the agent, but sometimes you want memories as **plain Markdown files** you can `grep`, edit in any editor, commit to git, or sync with Dropbox/iCloud across devices. The mirror gives you exactly that — a human-readable copy of every memory that round-trips cleanly back into the DB.
+
+```
+/memory export --to <dir>     One-shot snapshot of all memories as .md files
+/memory mirror status         Show live mirror path, file count, last sync
+/memory mirror rebuild        Re-materialise the mirror from the DB
+/memory sync --from <dir>     Reconstitute the DB from a directory of .md files
+```
+
+**When you want this:**
+
+- **Human-readable backup** — `grep -r "postgres" ~/.aman-agent/memories/` to see every memory that mentions Postgres.
+- **Edit outside the agent** — fix a typo or retire a stale decision in your favourite editor, then run `/memory sync --from ...` (or just restart — startup auto-syncs).
+- **Version-control your memory** — `git init ~/.aman-agent/memories/` and you get a full history of every memory the agent has ever learned.
+- **Multi-device sync** — point the mirror dir at a synced folder (Dropbox, iCloud, Syncthing) and your memories follow you.
+- **No lock-in** — YAML-frontmatter Markdown is readable without aman-agent ever being installed again.
+
+Opt-out: `config.mirror.enabled = false` disables all mirror I/O. Disable auto-sync on startup only with `config.mirror.autoSyncOnStartup = false`.
+
 </details>
 
 <details>

package/bin/aman-setup.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# aman-setup: non-interactive Minimal install.
+# Installs aman-agent + amem-core globally via npm. Requires Node 18+.
+#
+# Advanced tiers (Productive, Complete) require more choices — see
+# the README for the relevant package lists.
+
+set -euo pipefail
+
+echo "=== aman Minimal install ==="
+echo "Installs: aman-agent + amem-core"
+echo ""
+
+if ! command -v node >/dev/null 2>&1; then
+    echo "ERROR: node not found. Install Node 18+ first: https://nodejs.org" >&2
+    exit 1
+fi
+
+NODE_VERSION_MAJOR=$(node -p "process.versions.node.split('.')[0]")
+if [ "$NODE_VERSION_MAJOR" -lt 18 ]; then
+    echo "ERROR: Node 18+ required (you have $(node --version))" >&2
+    exit 1
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+    echo "ERROR: npm not found. Reinstall Node from https://nodejs.org" >&2
+    exit 1
+fi
+
+echo "Installing @aman_asmuei/aman-agent + @aman_asmuei/amem-core..."
+npm install -g @aman_asmuei/aman-agent @aman_asmuei/amem-core
+
+echo ""
+echo "=== Done ==="
+echo "Run: aman-agent"
+echo "See the README's 'Install tiers' section for Productive / Complete upgrades."

package/dist/delegate.js

@@ -544,7 +544,9 @@ import {
   syncFromClaude,
   exportForTeam,
   importFromTeam,
-  syncToCopilot
+  syncToCopilot,
+  MirrorEngine,
+  parseFrontmatter
 } from "@aman_asmuei/amem-core";
 import path5 from "path";
 import os4 from "os";