diff --git a/README.md b/README.md index 8f0e91d..d3f2ea7 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,8 @@ Solving the bottleneck of OpenClaw adaptation: Not ~~skills~~, but finding **way | Name | Description | |------|-------------| +| [Autonomous Project Management](usecases/autonomous-project-management.md) | Coordinate multi-agent projects using STATE.yaml pattern — subagents work in parallel without orchestrator overhead. | +| [Multi-Channel AI Customer Service](usecases/multi-channel-customer-service.md) | Unify WhatsApp, Instagram, Email, and Google Reviews in one AI-powered inbox with 24/7 auto-responses. | | [Phone-Based Personal Assistant](usecases/phone-based-personal-assistant.md) | Access your AI agent via phone calls, hands-free voice assistance for any phone. | | [Inbox De-clutter](usecases/inbox-declutter.md) | Summarize Newsletters and send you a digest as an email. | | [Personal CRM](usecases/personal-crm.md) | Automatically discover and track contacts from your email and calendar, with natural language queries. | diff --git a/usecases/autonomous-project-management.md b/usecases/autonomous-project-management.md new file mode 100644 index 0000000..7f45f94 --- /dev/null +++ b/usecases/autonomous-project-management.md @@ -0,0 +1,121 @@ +# Autonomous Project Management with Subagents + +Managing complex projects with multiple parallel workstreams is exhausting. You end up context-switching constantly, tracking status across tools, and manually coordinating handoffs. + +This use case implements a decentralized project management pattern where subagents work autonomously on tasks, coordinating through shared state files rather than a central orchestrator. + +## Pain Point + +Traditional orchestrator patterns create bottlenecks—the main agent becomes a traffic cop. For complex projects (multi-repo refactors, research sprints, content pipelines), you need agents that can work in parallel without constant supervision. + +## What It Does + +- **Decentralized coordination**: Agents read/write to a shared `STATE.yaml` file +- **Parallel execution**: Multiple subagents work on independent tasks simultaneously +- **No orchestrator overhead**: Main session stays thin (CEO pattern—strategy only) +- **Self-documenting**: All task state persists in version-controlled files + +## Core Pattern: STATE.yaml + +Each project maintains a `STATE.yaml` file that serves as the single source of truth: + +```yaml +# STATE.yaml - Project coordination file +project: website-redesign +updated: 2026-02-10T14:30:00Z + +tasks: + - id: homepage-hero + status: in_progress + owner: pm-frontend + started: 2026-02-10T12:00:00Z + notes: "Working on responsive layout" + + - id: api-auth + status: done + owner: pm-backend + completed: 2026-02-10T14:00:00Z + output: "src/api/auth.ts" + + - id: content-migration + status: blocked + owner: pm-content + blocked_by: api-auth + notes: "Waiting for new endpoint schema" + +next_actions: + - "pm-content: Resume migration now that api-auth is done" + - "pm-frontend: Review hero with design team" +``` + +## How It Works + +1. **Main agent receives task** → spawns subagent with specific scope +2. **Subagent reads STATE.yaml** → finds its assigned tasks +3. **Subagent works autonomously** → updates STATE.yaml on progress +4. **Other agents poll STATE.yaml** → pick up unblocked work +5. **Main agent checks in periodically** → reviews state, adjusts priorities + +## Skills You Need + +- `sessions_spawn` / `sessions_send` for subagent management +- File system access for STATE.yaml +- Git for state versioning (optional but recommended) + +## Setup: AGENTS.md Configuration + +```text +## PM Delegation Pattern + +Main session = coordinator ONLY. All execution goes to subagents. + +Workflow: +1. New task arrives +2. Check PROJECT_REGISTRY.md for existing PM +3. If PM exists → sessions_send(label="pm-xxx", message="[task]") +4. If new project → sessions_spawn(label="pm-xxx", task="[task]") +5. PM executes, updates STATE.yaml, reports back +6. Main agent summarizes to user + +Rules: +- Main session: 0-2 tool calls max (spawn/send only) +- PMs own their STATE.yaml files +- PMs can spawn sub-subagents for parallel subtasks +- All state changes committed to git +``` + +## Example: Spawning a PM + +```text +User: "Refactor the auth module and update the docs" + +Main agent: +1. Checks registry → no active pm-auth +2. Spawns: sessions_spawn( + label="pm-auth-refactor", + task="Refactor auth module, update docs. Track in STATE.yaml" + ) +3. Responds: "Spawned pm-auth-refactor. I'll report back when done." + +PM subagent: +1. Creates STATE.yaml with task breakdown +2. Works through tasks, updating status +3. Commits changes +4. Reports completion to main +``` + +## Key Insights + +- **STATE.yaml > orchestrator**: File-based coordination scales better than message-passing +- **Git as audit log**: Commit STATE.yaml changes for full history +- **Label conventions matter**: Use `pm-{project}-{scope}` for easy tracking +- **Thin main session**: The less the main agent does, the faster it responds + +## Based On + +This pattern is inspired by [Nicholas Carlini's approach](https://nicholas.carlini.com/) to autonomous coding agents—let agents self-organize rather than micromanaging them. + +## Related Links + +- [OpenClaw Subagent Docs](https://github.com/openclaw/openclaw) +- [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) diff --git a/usecases/multi-channel-customer-service.md b/usecases/multi-channel-customer-service.md new file mode 100644 index 0000000..1fa20fe --- /dev/null +++ b/usecases/multi-channel-customer-service.md @@ -0,0 +1,89 @@ +# Multi-Channel AI Customer Service Platform + +Small businesses juggle WhatsApp, Instagram DMs, emails, and Google Reviews across multiple apps. Customers expect instant responses 24/7, but hiring staff for round-the-clock coverage is expensive. + +This use case consolidates all customer touchpoints into a single AI-powered inbox that responds intelligently on your behalf. + +## What It Does + +- **Unified inbox**: WhatsApp Business, Instagram DMs, Gmail, and Google Reviews in one place +- **AI auto-responses**: Handles FAQs, appointment requests, and common inquiries automatically +- **Human handoff**: Escalates complex issues or flags them for review +- **Test mode**: Demo the system to clients without affecting real customers +- **Business context**: Trained on your services, pricing, and policies + +## Real Business Example + +At Futurist Systems, we deploy this for local service businesses (restaurants, clinics, salons). One restaurant reduced response time from 4+ hours to under 2 minutes, handling 80% of inquiries automatically. + +## Skills You Need + +- WhatsApp Business API integration +- Instagram Graph API (via Meta Business) +- `gog` CLI for Gmail +- Google Business Profile API for reviews +- Message routing logic in AGENTS.md + +## How to Set It Up + +1. **Connect channels** via OpenClaw config: + - WhatsApp Business API (through 360dialog or official API) + - Instagram via Meta Business Suite + - Gmail via `gog` OAuth + - Google Business Profile API token + +2. **Create business knowledge base**: + - Services and pricing + - Business hours and location + - FAQ responses + - Escalation triggers (e.g., complaints, refund requests) + +3. **Configure AGENTS.md** with routing logic: + +```text +## Customer Service Mode + +When receiving customer messages: + +1. Identify channel (WhatsApp/Instagram/Email/Review) +2. Check if test mode is enabled for this client +3. Classify intent: + - FAQ → respond from knowledge base + - Appointment → check availability, confirm booking + - Complaint → flag for human review, acknowledge receipt + - Review → thank for feedback, address concerns + +Response style: +- Friendly, professional, concise +- Match the customer's language (ES/EN/UA) +- Never invent information not in knowledge base +- Sign off with business name + +Test mode: +- Prefix responses with [TEST] +- Log but don't send to real channels +``` + +4. **Set up heartbeat checks** for response monitoring: + +```text +## Heartbeat: Customer Service Check + +Every 30 minutes: +- Check for unanswered messages > 5 min old +- Alert if response queue is backing up +- Log daily response metrics +``` + +## Key Insights + +- **Language detection matters**: Auto-detect and respond in customer's language +- **Test mode is essential**: Clients need to see it work before going live +- **Handoff rules**: Define clear escalation triggers to avoid AI overreach +- **Response templates**: Pre-approved templates for sensitive topics (refunds, complaints) + +## Related Links + +- [WhatsApp Business API](https://developers.facebook.com/docs/whatsapp) +- [Instagram Messaging API](https://developers.facebook.com/docs/instagram-api/guides/messaging) +- [Google Business Profile API](https://developers.google.com/my-business)