@aman_asmuei/aman-agent 0.8.0 → 0.17.0

package/README.md

@@ -43,23 +43,26 @@
 
 ---
 
-## What's New in v0.6.0
+## What's New in v0.16.0
 
-> **Zero to Wow** — the first 60 seconds are now magical.
+> **Multi-agent AI companion with teams, delegation, and profiles.**
 
-| Feature | Before | After |
-|:---|:---|:---|
-| **Onboarding** | 3-4 prompts for API key/model | Auto-detects from env vars |
-| **Ecosystem setup** | Manual, separate CLI | `aman-agent init` wizard with persona presets |
-| **First session** | Empty prompt | Agent introduces itself, asks your name |
-| **Returning session** | Raw context dump | "Welcome back. Last time we talked about..." |
-| **Memory storage** | "Remember X? (y/N)" interruptions | Silent auto-store, undo with `/memory clear` |
-| **Output** | Raw text | Markdown rendering with response framing |
-| **Errors** | "401 Unauthorized" | "API key invalid. Run /reconfig to fix." |
-| **Feature discovery** | Read the README | Progressive hints at the right moment |
-| **New commands** | — | `/memory timeline`, upgraded `/doctor` |
-
-<a href="https://github.com/amanasmuei/aman-agent/releases/tag/v0.6.0">Full release notes</a>
+| Feature | What it does |
+|:---|:---|
+| **Agent profiles** | Multiple AI identities: `--profile coder`, `--profile writer`, `--profile researcher` |
+| **Agent delegation** | Delegate tasks to sub-agents: `/delegate writer Write a blog post` |
+| **Agent teams** | Named teams with pipeline, parallel, and coordinator modes |
+| **Auto-delegation** | AI suggests delegation/teams when appropriate — asks permission first |
+| **Image support** | Reference local images or URLs — auto base64-encoded and sent as vision content |
+| **Personality engine** | Adaptive tone based on time, sentiment, and energy curve |
+| **Skill engine** | Skills auto-trigger, level up (Lv.1→Lv.5), self-improve from your patterns |
+| **Persistent plans** | Multi-step plans with checkboxes that survive session resets |
+| **Background tasks** | Long-running tools execute concurrently without blocking conversation |
+| **Project-aware sessions** | Auto-detects project, scoped memory, context persistence on exit |
+| **Social media posting** | Post to Bluesky, X, Threads, Facebook, Instagram via aman-social |
+| **Docker deployment** | `aman deploy` — deploy anywhere with Docker, Ollama, or systemd |
+
+<a href="https://github.com/amanasmuei/aman-agent/releases">Full release history</a>
 
 ---
 
@@ -128,6 +131,402 @@ aman-agent --budget 12000
 
 ---
 
+## Usage Guide
+
+A step-by-step walkthrough of how to use aman-agent day-to-day.
+
+### Your First Conversation
+
+On first run, the agent introduces itself and asks your name. Just talk naturally:
+
+```
+$ aman-agent
+
+  aman agent — your AI companion
+  ✓ Auto-detected Anthropic API key. Using Claude Sonnet 4.6.
+  ✓ Ecosystem ready: identity, guardrails (1,204 tokens)
+  ✓ Connected 30 MCP tools
+  ✓ Personality: morning session, high-drive energy
+  Aman is ready.
+
+You > Hey, I'm working on a Node.js API
+
+ Aman ──────────────────────────────────────────────
+
+  Nice to meet you! I'm Aman, your AI companion. I'll remember
+  what matters across our conversations — your preferences,
+  decisions, and patterns.
+
+  What kind of API are you building? I can help with architecture,
+  auth, database design, or whatever you need.
+
+ ────────────────────────────────────── [1 memory stored]
+```
+
+That's it. No setup required. The agent remembers your stack from this point forward.
+
+### How Memory Works
+
+Memory is automatic. You don't need to do anything — the agent silently extracts important information from every conversation:
+
+- **Preferences** — "I prefer Vitest over Jest" → remembered
+- **Decisions** — "Let's use PostgreSQL" → remembered
+- **Patterns** — "User always writes tests first" → remembered
+- **Facts** — "The auth service is in /services/auth" → remembered
+
+Memory shows up naturally in responses:
+
+```
+You > Let's add a new endpoint
+
+ Aman ──────────────────────────────────────────────
+
+  Based on your previous decisions, I'll set it up with:
+  - PostgreSQL (your preference)
+  - JWT auth (decided last session)
+  - Vitest for tests
+
+ ──────────────────────────────── memories: ~47 tokens
+```
+
+**Useful memory commands:**
+
+```
+/memory search auth      Search your memories
+/memory timeline         See memory growth over time
+/decisions               View your decision log
+```
+
+### Working with Files & Images
+
+Reference any file path in your message — it gets attached automatically:
+
+```
+You > Review this code ~/projects/api/src/auth.ts
+
+  [attached: auth.ts (3.2KB)]
+
+ Aman ──────────────────────────────────────────────
+  Looking at your auth middleware...
+```
+
+**Images** work the same way — the agent can see them:
+
+```
+You > What's wrong with this schema? ~/Desktop/schema.png
+
+  [attached image: schema.png (142.7KB)]
+
+ Aman ──────────────────────────────────────────────
+  I see a few issues with your schema...
+```
+
+**Supported files:**
+- **Code/text:** `.ts`, `.js`, `.py`, `.go`, `.rs`, `.md`, `.json`, `.yaml`, and 30+ more
+- **Images:** `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp` (also URLs)
+- **Documents:** `.pdf`, `.docx`, `.xlsx`, `.pptx` (via Docling)
+
+Multiple files in one message work too.
+
+### Working with Plans
+
+Plans help you track multi-step work that spans sessions.
+
+**Create a plan:**
+
+```
+You > /plan create Auth API | Ship JWT auth | Design schema, Build endpoints, Write tests, Deploy
+
+  Plan created!
+
+  Plan: Auth API (active)
+  Goal: Ship JWT auth
+  Progress: [░░░░░░░░░░░░░░░░░░░░] 0/4 (0%)
+
+     1. [ ] Design schema
+     2. [ ] Build endpoints
+     3. [ ] Write tests
+     4. [ ] Deploy
+
+  Next: Step 1 — Design schema
+```
+
+**Mark progress as you work:**
+
+```
+You > /plan done
+
+  Step 1 done!
+
+  Plan: Auth API (active)
+  Progress: [█████░░░░░░░░░░░░░░░] 1/4 (25%)
+
+     1. [✓] Design schema
+     2. [ ] Build endpoints      ← Next
+     3. [ ] Write tests
+     4. [ ] Deploy
+```
+
+**The AI knows your plan.** Every turn, the active plan is injected into context. The AI knows which step you're on and reminds you to commit after completing steps.
+
+**Resume across sessions.** Close the terminal, come back tomorrow — your plan is still there:
+
+```
+$ aman-agent
+
+  Welcome back. You're on step 2 of Auth API — Build endpoints.
+```
+
+**All plan commands:**
+
+```
+/plan                Show active plan
+/plan done [step#]   Mark step complete (next if no number)
+/plan undo <step#>   Unmark a step
+/plan list           Show all plans
+/plan switch <name>  Switch active plan
+/plan show <name>    View a specific plan
+```
+
+Plans are stored as markdown in `.acore/plans/` — they're git-trackable.
+
+### Skills in Action
+
+Skills activate automatically based on what you're talking about. No commands needed.
+
+```
+You > How should I handle SQL injection in this query?
+
+  [skill: security Lv.3 activated]
+  [skill: database Lv.2 activated]
+
+ Aman ──────────────────────────────────────────────
+  Use parameterized queries — never interpolate user input...
+```
+
+**Skills level up as you use them:**
+
+| Level | Label | What changes |
+|:---|:---|:---|
+| Lv.1 | Learning | Detailed explanations, examples |
+| Lv.2 | Familiar | Brief reasoning, show patterns |
+| Lv.3 | Proficient | Task-focused, skip basics |
+| Lv.4 | Advanced | Edge cases, proactive suggestions |
+| Lv.5 | Expert | Just execute, no hand-holding |
+
+Skills also self-improve — when the agent learns your patterns (e.g., "user prefers Prisma over raw SQL"), it enriches the skill with your preferences.
+
+**12 built-in skill domains:** testing, api-design, security, performance, code-review, documentation, git-workflow, debugging, refactoring, database, typescript, accessibility
+
+**10 knowledge library items** auto-suggested when relevant: security-headers, docker-node, github-actions, env-config, error-handling, rate-limiter, prisma-setup, zod-validation, testing-patterns, git-hooks
+
+### Project Workflow
+
+aman-agent is project-aware. When you run it in a project directory, it loads project-specific context.
+
+**Set up a project:**
+
+```bash
+cd ~/my-project
+npx @aman_asmuei/acore        # Creates .acore/context.md with detected stack
+aman-agent                     # Loads project context automatically
+```
+
+**What gets scoped to your project:**
+- Decisions and topology (stored in amem with `project:my-project` scope)
+- Session state (saved to `.acore/context.md` on exit)
+- Plans (stored in `.acore/plans/`)
+
+**Switch projects naturally:**
+
+```bash
+cd ~/project-a && aman-agent   # Loads project-a context + memories
+cd ~/project-b && aman-agent   # Loads project-b context + memories
+```
+
+Global preferences (coding style, tool choices) carry across all projects.
+
+### Personality & Wellbeing
+
+The agent adapts its tone based on time of day and how you're doing:
+
+- **Morning:** energetic, direct
+- **Afternoon:** steady, focused
+- **Evening:** warm, winding down
+- **Late night:** gentle, reflective
+
+It also reads your messages for frustration, confusion, or fatigue — and adapts:
+
+```
+You > ugh nothing works, tried everything!!
+
+  [sentiment: frustrated]
+
+ Aman ──────────────────────────────────────────────
+  That sounds frustrating. Let's step back and try a different
+  angle — what changed since it last worked?
+```
+
+**Wellbeing nudges** appear when needed:
+- Long late-night session → gentle suggestion to rest
+- 90+ minutes of frustration → suggest a break
+- User seems tired → concise responses, support wrapping up
+
+These are one-time nudges — the agent won't nag.
+
+### Customization
+
+**Persona presets** for different work styles:
+
+```bash
+aman-agent init
+# Choose: Coding Partner, Creative Collaborator,
+#          Personal Assistant, Learning Buddy, or Minimal
+```
+
+**Guardrails** control what the AI should and shouldn't do:
+
+```
+/rules add Coding Always write tests before merging
+/rules add Never Delete production data without confirmation
+```
+
+**Workflows** teach the AI multi-step processes:
+
+```
+/workflows add code-review
+```
+
+**Hook toggles** in `~/.aman-agent/config.json`:
+
+```json
+{
+  "hooks": {
+    "memoryRecall": true,
+    "personalityAdapt": true,
+    "extractMemories": true,
+    "featureHints": true
+  }
+}
+```
+
+Set any to `false` to disable.
+
+### Agent Profiles
+
+Run different AI personalities for different tasks:
+
+```bash
+aman-agent --profile coder      # direct, code-first
+aman-agent --profile writer     # creative, story-driven
+aman-agent --profile researcher # analytical, citation-focused
+```
+
+Each profile has its own identity, rules, and skills — but shares the same memory. Create profiles:
+
+```
+/profile create coder       Install built-in template
+/profile create mybot       Create custom profile
+/profile list               Show all profiles
+```
+
+### Agent Delegation
+
+Delegate tasks to sub-agents with specialist profiles:
+
+```
+/delegate writer Write a blog post about AI companions
+
+  [delegating to writer...]
+
+  [writer] ✓ (2 tool turns)
+  # Building AI Companions That Actually Remember You
+  ...
+```
+
+**Pipeline delegation** — chain agents sequentially:
+
+```
+/delegate pipeline writer,researcher Write and fact-check an article
+
+  [writer] ✓ — drafted article
+  [researcher] ✓ — verified claims, added citations
+```
+
+The AI also **auto-suggests delegation** when it recognizes a task matches a specialist profile — always asks for your permission first.
+
+### Agent Teams
+
+Named teams of agents that collaborate on complex tasks:
+
+```
+/team create content-team        Install built-in team
+/team run content-team Write a blog post about AI
+
+  Team: content-team (pipeline)
+  Members: writer → researcher
+
+  [writer: drafting...] ✓
+  [researcher: fact-checking...] ✓
+
+  Final output with verified claims.
+```
+
+**3 execution modes:**
+
+| Mode | How it works |
+|:---|:---|
+| `pipeline` | Sequential: agent1 → agent2 → agent3 |
+| `parallel` | All agents work concurrently, coordinator merges |
+| `coordinator` | AI plans how to split the task, assigns to members |
+
+**Built-in teams:**
+
+| Team | Mode | Members |
+|:---|:---|:---|
+| `content-team` | pipeline | writer → researcher |
+| `dev-team` | pipeline | coder → researcher |
+| `research-team` | pipeline | researcher → writer |
+
+Create custom teams:
+
+```
+/team create review-squad pipeline coder:implement,researcher:review
+/team run review-squad Build a rate limiter in TypeScript
+```
+
+The AI auto-suggests teams when appropriate — always asks permission first.
+
+### Daily Workflow Summary
+
+Here's what a typical day looks like with aman-agent:
+
+```
+Morning:
+  $ cd ~/project && aman-agent
+  → Loads project context, active plan, memories
+  → "Welcome back. You're on step 3 of Auth API."
+  → Work on your plan, skills auto-activate as needed
+  → /plan done after each step, commit your work
+
+Afternoon:
+  → Personality shifts to steady pace
+  → Skills level up as you demonstrate mastery
+  → Knowledge library suggests snippets when relevant
+
+Evening:
+  → /quit or Ctrl+C
+  → Session auto-saved to memory
+  → Project context.md updated
+  → Plan progress persisted
+  → Optional quick session rating
+
+Next morning:
+  → Everything picks up where you left off
+```
+
+---
+
 ## Intelligent Companion Features
 
 ### Per-Message Memory Recall with Progressive Disclosure
@@ -231,9 +630,52 @@ Every memory recall shows how many tokens it costs, so you always know the overh
   [memories: ~47 tokens]
 ```
 
-### Time-Aware Greetings
+### Personality Engine
+
+The agent adapts its personality in real-time based on signals:
+
+- **Time of day**: morning (high-drive) → afternoon (steady) → night (reflective)
+- **Session duration**: gradually shifts from energetic to mellow
+- **User sentiment**: detects frustration, excitement, confusion, fatigue from keywords
+- **Wellbeing nudges**: suggests breaks when you've been at it too long, gently mentions sleep during late-night sessions
+
+All state syncs to acore's Dynamics section — works across aman-agent, achannel, and aman-plugin.
+
+### Auto-Triggered Skills
+
+When you talk about security, the security skill activates. Debugging? The debugging skill loads. No commands needed.
+
+- 12 skill domains with keyword matching
+- **Skill leveling** (Lv.1→Lv.5): adapts explanation depth to your demonstrated mastery
+- **Self-improving**: memory extraction enriches skills with your specific patterns over time
+- **Knowledge library**: 10 curated reference items auto-suggested when relevant
+
+### Persistent Plans
+
+Create multi-step plans that survive session resets:
+
+```
+/plan create Auth | Add JWT auth | Design schema, Implement middleware, Add tests, Deploy
+
+Plan: Auth (active)
+Goal: Add JWT auth
+Progress: [████████░░░░░░░░░░░░] 2/5 (40%)
+
+   1. [✓] Design schema
+   2. [✓] Implement middleware
+   3. [ ] Add tests         ← Next
+   4. [ ] Deploy
+```
+
+Plans stored as markdown in `.acore/plans/` — git-trackable, project-local.
+
+### Background Task Execution
+
+Long-running tools (tests, builds, Docker) run in the background while the conversation continues. Results appear when ready.
+
+### Project-Aware Sessions
 
-The agent knows the time of day and day of week. It adapts its tone naturally — you'll notice the difference between a morning and a late-night session.
+The agent detects your project from the current directory. On exit, it auto-updates `.acore/context.md` with session state. Next time you open the same project, the AI picks up where you left off.
 
 ### Reminders
 
@@ -324,10 +766,11 @@ Every operation that can fail logs to `~/.aman-agent/debug.log` with structured
 
 | Phase | What happens |
 |:---|:---|
-| **Start** | Load ecosystem, connect MCP, consolidate memory, check reminders, inject time context |
-| **Each turn** | Recall relevant memories, stream response, execute tools in parallel, extract new memories |
+| **Start** | Load ecosystem, connect MCP, consolidate memory, check reminders, compute personality state, load active plan |
+| **Each turn** | Recall memories, auto-trigger skills, inject active plan, detect sentiment, stream response, execute tools (parallel + background), extract memories, enrich skills |
+| **Every 5 turns** | Refresh personality state, check wellbeing, sync to acore |
 | **Auto-trim** | LLM-powered summarization when approaching 80K tokens |
-| **Exit** | Save conversation to amem, update session resume, optional session rating |
+| **Exit** | Save conversation to amem, update session resume, persist personality state, update project context.md, optional session rating |
 
 ---
 
@@ -336,6 +779,10 @@ Every operation that can fail logs to `~/.aman-agent/debug.log` with structured
 | Command | Description |
 |:---|:---|
 | `/help` | Show available commands |
+| `/plan` | Show active plan `[create\|done\|undo\|list\|switch\|show]` |
+| `/profile` | Manage agent profiles `[create\|list\|show\|delete]` |
+| `/delegate` | Delegate task to a profile `[<profile> <task>\|pipeline]` |
+| `/team` | Manage agent teams `[create\|run\|list\|show\|delete]` |
 | `/identity` | View identity `[update <section>]` |
 | `/rules` | View guardrails `[add\|remove\|toggle ...]` |
 | `/workflows` | View workflows `[add\|remove ...]` |
@@ -370,7 +817,9 @@ On every session start, aman-agent assembles your full AI context:
 | **Workflows** | `~/.aflow/flow.md` | Multi-step processes (code review, bug fix) |
 | **Guardrails** | `~/.arules/rules.md` | Safety boundaries and permissions |
 | **Skills** | `~/.askill/skills.md` | Deep domain expertise |
-| **Time** | System clock | Time of day, day of week for tone adaptation |
+| **Plans** | `.acore/plans/` | Active plan with progress and next step |
+| **Project** | `.acore/context.md` | Project-specific tech stack, session state, patterns |
+| **Time** | System clock | Time of day, day of week for tone and personality adaptation |
 
 All layers are optional — the agent works with whatever you've set up.
 
@@ -463,6 +912,7 @@ All hooks are on by default. Disable any in `config.json`:
 | `autoSessionSave` | Save conversation to amem on exit |
 | `extractMemories` | Auto-extract memories from conversation |
 | `featureHints` | Show progressive feature discovery tips |
+| `personalityAdapt` | Adapt tone based on time, sentiment, and session signals |
 
 > Treat the config file like a credential — it contains your API key.
 
@@ -511,14 +961,19 @@ aman
 | Identity system | 7 portable layers | None | None |
 | Memory | amem (SQLite + embeddings + graph) | Postgres + embeddings | None |
 | Per-message recall | Progressive disclosure (~10x token savings) | Yes | No |
-| Learns from conversation | Auto-extract (silent) | Requires configuration | No |
+| Learns from conversation | Auto-extract (silent) + skill enrichment | Requires configuration | No |
+| Personality adaptation | Sentiment-aware, time-based, energy curve | None | None |
+| Wellbeing awareness | 6 nudge types (sleep, breaks, frustration) | None | None |
+| Skill leveling | Lv.1→Lv.5, auto-triggered by context | None | None |
+| Plan tracking | Persistent checkboxes, survives resets | None | None |
+| Vision / multimodal | Images via base64 (local + URL) | None | None |
+| Background tasks | Long-running tools run concurrently | None | None |
 | Guardrail enforcement | Runtime tool blocking | None | None |
 | Reminders | Persistent, deadline-aware | None | None |
 | Context compression | LLM-powered summarization | Archival system | Truncation |
-| Tool observation capture | Passive logging of all tool calls | None | None |
-| Token cost visibility | Shows memory injection cost per turn | None | None |
-| Multi-LLM | Anthropic, OpenAI, Ollama | OpenAI-focused | Single provider |
-| Tool execution | Parallel with guardrails | Sequential | None |
+| Multi-LLM | Anthropic, OpenAI, Ollama (all with tools) | OpenAI-focused | Single provider |
+| Tool execution | Parallel + background with guardrails | Sequential | None |
+| Project awareness | Auto-detect project, scoped memory, context.md | None | None |
 
 ### amem vs other memory layers