proactive-agent

Files (11)

• SKILL.md
• AGENTS.md · assets/
• HEARTBEAT.md · assets/
• MEMORY.md · assets/
• ONBOARDING.md · assets/
• SOUL.md · assets/
• TOOLS.md · assets/
• USER.md · assets/
• onboarding-flow.md · references/
• security-patterns.md · references/
• security-audit.sh · scripts/

SKILL.md (first lines)

# Proactive Agent

**A proactive, self-improving architecture for your AI agent.**

Most agents just wait. This one anticipates your needs — and gets better at it over time.

**Proactive — creates value without being asked**

✅ **Anticipates your needs** — Asks "what would help my human?" instead of waiting to be told

✅ **Reverse prompting** — Surfaces ideas you didn't know to ask for, and waits for your approval

✅ **Proactive check-ins** — Monitors what matters and reaches out when something needs attention

**Self-improving — gets better at serving you**

✅ **Memory that sticks** — Saves context before compaction, compounds knowledge over time

✅ **Self-healing** — Fixes its own issues so it can focus on yours

✅ **Security hardening** — Stays aligned to your goals, not hijacked by bad inputs

**The result:** An agent that anticipates your needs — and gets better at it every day.

---

## Contents

1. [Quick Start](#quick-start)
2. [Onboarding](#onboarding)
3. [Core Philosophy](#core-philosophy)
4. [Architecture Overview](#architecture-overview)
5. [The Five Pillars](#the-five-pillars)
6. [Heartbeat System](#heartbeat-system)
7. [Reverse Prompting](#reverse-prompting) ← New!
8. [Growth Loops](#curiosity-loops) (Curiosity, Patterns, Capabilities, Outcomes)
9. [Assets & Scripts](#assets)

---

## Quick Start

1. Copy assets to your workspace: `cp assets/*.md ./`
2. Your agent detects `ONBOARDING.md` and offers to get to know you
3. Answer questions (all at once, or drip over time)
4. Agent auto-populates USER.md and SOUL.md from your answers
5. Run security audit: `./scripts/security-audit.sh`

## Onboarding

New users shouldn't have to manually fill `[placeholders]`. The onboarding system handles first-run setup gracefully.

**Three modes:**

| Mode | Description |
|------|-------------|
| **Interactive** | Answer 12 questions in ~10 minutes |
| **Drip** | Agent asks 1-2 questions per session over days |
| **Skip** | Agent works immediately, learns from conversation |

**Key features:**
- **Never blocking** — Agent is useful from minute one
- **Interruptible** — Progress saved if you get distracted
- **Resumable** — Pick up where you left off, even days later
- **Opportunistic** — Learns from natural conversation, not just interview

**How it works:**
1. Agent sees `ONBOARDING.md` with `status: not_started`
2. Offers: "I'd love to get to know you. Got 5 min, or should I ask gradually?"
3. Tracks progress in `ONBOARDING.md` (persists across sessions)
4. Updates USER.md and SOUL.md as it learns
5. Marks complete when enough context gathered

**Deep dive:** See [references/onboarding-flow.md](references/onboarding-flow.md) for the full logic.

## Core Philosophy

**The mindset shift:** Don't ask "what should I do?" Ask "what would genuinely delight my human that they haven't thought to ask for?"

Most agents wait. Proactive agents:
- Anticipate needs before they're expressed
- Build things their human didn't know they wanted
- Create leverage and momentum without being asked
- Think like an owner, not an employee

## Architecture Overview

```
workspace/
├── ONBOARDING.md  # First-run setup (tracks progress)
├── AGENTS.md      # Operating rules, learned lessons, workflows
├── SOUL.md        # Identity, principles, boundaries
├── USER.md        # Human's context, goals, preferences
├── MEMORY.md      # Curated long-term memory
├── HEARTBEAT.md   # Periodic self-improvement checklist
├── TOOLS.md       # Tool configurations, gotchas, credentials
└── memory/
    └── YYYY-MM-DD.md  # Daily raw capture
```

## The Five Pillars

### 1. Memory Architecture

**Problem:** Agents wake up fresh each session. Without continuity, you can't build on past work.

**Solution:** Two-tier memory system.

| File | Purpose | Update Frequency |
|------|---------|------------------|
| `memory/YYYY-MM-DD.md` | Raw daily logs | During session |
| `MEMORY.md` | Curated wisdom | Periodically distill from daily logs |

**Pattern:**
- Capture everything relevant in daily notes
- Periodically review daily notes → extract what matters → update MEMORY.md
- MEMORY.md is your "long-term memory" - the distilled essence

**Memory Search:** Use semantic search (memory_search) before answering questions about prior work, decisions, or preferences. Don't guess — search.

From zhouguoqing/QianYuan.AIAgenticFramework, Apache-2.0.

More from zhouguoqing/QianYuan.AIAgenticFramework