@deimoscloud/coreai 0.1.0

package/PRODUCT.md

@@ -0,0 +1,473 @@
+# CoreAI - Multi-Agent Development System
+
+> **Product Vision:** A reusable, template-based system for orchestrating AI agents that simulate a software development team.
+
+---
+
+## Executive Summary
+
+CoreAI is a framework for setting up AI agent teams that work together on software development tasks. It provides:
+
+- **Agent definitions** with clear roles and responsibilities
+- **Workflow state machines** for ticket lifecycle management
+- **Inbox-based communication** for async agent collaboration
+- **Standardized message templates** for consistent handoffs
+- **Knowledge library structure** for shared context and state
+
+The system is designed to be cloned and customized for any software project.
+
+---
+
+## Problem Statement
+
+### The Challenge
+
+When using AI agents for software development:
+
+1. **Inconsistent behavior** - Agents forget instructions or ignore workflow rules
+2. **Lost context** - Each conversation starts fresh with no memory
+3. **MCP access issues** - Subagents lose access to external tools (Jira, GitHub)
+4. **Manual overhead** - Too much human intervention required
+5. **No standard patterns** - Each project reinvents agent workflows
+
+### Our Solution
+
+A template-based system that:
+
+- Embeds critical instructions in commands (not just agent files)
+- Maintains persistent context via file-based knowledge library
+- Uses direct agent invocation to preserve MCP access
+- Provides explicit validation checkpoints
+- Can be cloned and customized for any project
+
+---
+
+## Goals
+
+### Primary Goals
+
+1. **Reusability** - Clone this template for any new project
+2. **Consistency** - Agents follow workflows reliably
+3. **Minimal overhead** - Reduce human intervention in agent orchestration
+4. **Clear ownership** - Engineers own ticket lifecycle, EM validates
+
+### Success Metrics
+
+- Agents follow ticket workflow correctly (status transitions)
+- PRs have proper reviews posted to GitHub (not just inbox)
+- Completion reports include valid workflow checkpoints
+- New project setup time < 30 minutes
+
+---
+
+## Architecture
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         User                                     │
+│         (invokes agents via @agent-name or /command)            │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                    Claude Code + MCP                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
+│  │  Atlassian  │  │   GitHub    │  │   Other     │              │
+│  │  (Jira/     │  │   (gh CLI)  │  │   MCPs      │              │
+│  │  Confluence)│  │             │  │             │              │
+│  └─────────────┘  └─────────────┘  └─────────────┘              │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                       Agent Layer                                │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
+│  │    EM    │  │ Engineer │  │ Reviewer │  │    PM    │        │
+│  │(delegate,│  │(implement│  │(review,  │  │(require- │        │
+│  │ validate)│  │ own life-│  │ approve) │  │  ments)  │        │
+│  │          │  │  cycle)  │  │          │  │          │        │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                   Knowledge Library                              │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │  Shared Context: context.txt, architecture.txt, prd.txt │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │  Agent Directories: inbox/, outbox/, context/, control/ │    │
+│  └─────────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| Agent Specs | `coreai/AGENT_SPEC.md` | Master behavior specification |
+| Workflows | `coreai/WORKFLOWS.md` | State machines for ticket/review |
+| Agent Files | `coreai/agents/*.md` | Individual agent definitions |
+| Commands | `coreai/commands/*.md` | User-invocable slash commands |
+| Templates | `coreai/templates/*.md` | Inbox message formats |
+| Knowledge Library | `coreai/knowledge-library/` | Shared context & communication |
+
+---
+
+## Agent Roles & Responsibilities
+
+### Engineering Manager (EM)
+
+**Role:** Coordination and validation (NOT implementation)
+
+| Does | Does NOT |
+|------|----------|
+| Delegate tasks via inbox | Write code |
+| Validate completion reports | Create PRs |
+| Assign reviewers | Move tickets to In Progress |
+| Track sprint progress | Move tickets to In Review |
+| Remove blockers | Use Task tool for agents |
+
+### IC Engineers (wearos, android, backend, devops)
+
+**Role:** Implementation with full lifecycle ownership
+
+| Responsibility | When |
+|----------------|------|
+| Move ticket to In Progress | On task start |
+| Create feature branch | After status update |
+| Implement with tests | During development |
+| Run quality checks | Before PR |
+| Create PR | After tests pass |
+| Move ticket to In Review | After PR created |
+| Send completion report | After all above |
+
+### Reviewers (solutions-architect, security-engineer, qa-engineer)
+
+**Role:** Code review and specialized guidance
+
+| Responsibility | Where |
+|----------------|-------|
+| Review PR thoroughly | GitHub |
+| Post review comment | On the PR (not just inbox) |
+| State APPROVED or CHANGES_REQUESTED | In PR comment |
+| Send summary to EM | Via inbox |
+
+### Product Manager
+
+**Role:** Requirements and prioritization
+
+---
+
+## Workflow Design
+
+### Ticket Implementation Workflow
+
+```
+BACKLOG → IN_PROGRESS → PR_CREATED → IN_REVIEW → APPROVED → MERGED → DONE
+   │           │             │            │           │          │       │
+   │           │             │            │           │          │       │
+   ▼           ▼             ▼            ▼           ▼          ▼       ▼
+  EM        Engineer     Engineer    Engineer→   Reviewer    User      EM
+delegates  moves tkt,   creates PR  EM→Reviewer  approves   merges  validates
+           branches                                                   & closes
+```
+
+### Key Design Decisions
+
+1. **Engineers own ticket lifecycle** - Reduces EM overhead, clearer ownership
+2. **EM validates, doesn't execute** - Separation of concerns
+3. **Reviews on GitHub PR** - Visible to everyone, not hidden in inbox
+4. **Standardized messages** - YAML frontmatter + workflow checkpoint
+
+---
+
+## Lessons Learned
+
+### From SurfTrack Development (3 weeks)
+
+#### What Worked Well
+
+1. **Custom commands** - Embedding instructions in `/delegate`, `/review` prevented agents from ignoring workflow rules
+2. **Inbox-based communication** - Persistent async messaging survived context resets
+3. **Direct @agent invocation** - Full MCP access without workarounds
+4. **Workflow checkpoints** - Explicit validation gates caught issues early
+5. **Processed folder pattern** - Moving messages to `processed/` prevented duplicate work
+
+#### What Didn't Work
+
+1. **Long agent files** - 400+ line agent files were hard to maintain and often ignored
+2. **Implicit validation** - EM wasn't checking if tickets were in correct status
+3. **Freeform messages** - Inconsistent formats led to missed information
+4. **EM doing too much** - EM was moving tickets, should have been engineers
+5. **Task tool for agents** - Lost MCP access, required workarounds
+
+#### Key Insights
+
+1. **Shorter is better** - Lean agent files that reference specs work better than verbose ones
+2. **Commands > Agent files** - Critical instructions in commands get followed more reliably
+3. **Explicit > Implicit** - Validation checklists catch what assumptions miss
+4. **Ownership matters** - Clear ownership of ticket lifecycle reduces back-and-forth
+
+### Common Failure Modes
+
+| Failure | Cause | Solution |
+|---------|-------|----------|
+| Agent uses Task tool | Default behavior, ignores instructions | FORBIDDEN ACTIONS section + commands |
+| Review not posted to PR | Agent only sends to inbox | Explicit requirement in reviewer template |
+| Ticket stuck in wrong status | Engineer didn't move it | Engineer responsibility in workflow |
+| Missing workflow checkpoint | Agent forgot | Required in completion report template |
+| Duplicate work | Inbox message processed twice | Move to `processed/` folder |
+
+---
+
+## Agent Autonomy Roadmap
+
+### Phase 1: Task Tool Subagents (Deprecated)
+
+**Status:** Superseded
+
+- Agents invoked via Task tool as subagents
+- No MCP access - required workarounds
+- User/parent executed MCP operations on agent's behalf
+
+**User effort:** High
+
+### Phase 2: Direct Agent Invocation (Current)
+
+**Status:** Active
+
+```
+@engineering-manager /delegate SUR-XX to wearos-engineer
+@wearos-engineer /check-inbox
+```
+
+**Benefits:**
+- Full MCP access (Atlassian, GitHub)
+- No workarounds needed
+- Agents can update Jira/GitHub directly
+
+**Limitations:**
+- Can't approve own PRs (GitHub restriction)
+- User must invoke each agent manually
+- No automatic agent-to-agent handoffs
+
+**User effort:** Low-Medium
+
+### Phase 3: Agent-to-Agent Orchestration (Future)
+
+EM can directly invoke other agents with full MCP access.
+
+**Requirements:**
+- Agent invocation that preserves MCP context
+- Or: Each agent as separate root conversation
+- Possibly: Claude Code hooks
+
+**User effort:** Low
+
+### Phase 4: Event-Driven Automation (Future)
+
+Agents triggered by events:
+
+| Event | Trigger | Action |
+|-------|---------|--------|
+| PR created | GitHub webhook | QA runs tests |
+| CI passes | GitHub Actions | SA reviews |
+| Review approved | PR comment | EM notified |
+
+**Requirements:**
+- Webhook infrastructure
+- Agent persistence
+- Event routing
+
+**User effort:** Minimal
+
+### Phase 5: Full Autonomy (Vision)
+
+- Agents collaborate without intervention
+- Self-healing and self-improving
+- Human-in-the-loop only for strategic decisions
+
+---
+
+## Implementation Approaches
+
+### Option A: Shared Knowledge Base (Current)
+
+```
+┌─────────────────────────────────┐
+│       Knowledge Library          │
+│  ├── context.txt                 │
+│  └── [agent]/inbox/              │
+└─────────────────────────────────┘
+      ↑           ↑           ↑
+   Agent 1     Agent 2     Agent 3
+   (root)      (root)      (root)
+```
+
+- Agents communicate via inbox files
+- User invokes agents as needed
+- Each has full MCP access
+
+### Option B: Custom Orchestration Layer
+
+External service manages agent invocation:
+
+```
+┌────────────────────────────┐
+│   Orchestration Service     │
+│  - Event listeners          │
+│  - Agent invocation API     │
+└────────────────────────────┘
+         ↓ invokes
+    Claude Agents (via API)
+```
+
+### Option C: Claude Code Hooks
+
+Use hooks for event-driven automation:
+
+```javascript
+// .claude/hooks/pr-created.js
+module.exports = async (context) => {
+  await context.invokeAgent('solutions-architect', {
+    task: `Review PR #${context.pr.number}`
+  });
+};
+```
+
+---
+
+## Directory Structure
+
+```
+coreai/
+├── PRODUCT.md             # This file - vision, goals, lessons
+├── README.md              # Setup instructions
+├── AGENT_SPEC.md          # Master agent specification
+├── WORKFLOWS.md           # Workflow state machines
+├── ARCHITECTURE.md        # Technical architecture
+│
+├── scripts/
+│   ├── install.sh         # Main installer
+│   └── add-agent.sh       # Add new agent
+│
+├── agents/
+│   ├── _templates/               # Agent templates for add-agent.sh
+│   │   ├── ic-engineer.md
+│   │   └── reviewer.md
+│   └── examples/                 # Ready-to-use agents (copied on install)
+│       ├── engineering-manager.md
+│       ├── backend-engineer.md
+│       ├── android-engineer.md
+│       ├── wearos-engineer.md
+│       ├── devops-engineer.md
+│       ├── solutions-architect.md
+│       ├── qa-engineer.md
+│       ├── security-engineer.md
+│       ├── product-manager.md
+│       └── frontend-engineer.md
+│
+├── commands/
+│   ├── core/                # Always installed
+│   │   ├── delegate.md
+│   │   ├── check-inbox.md
+│   │   ├── review.md
+│   │   ├── sprint-status.md
+│   │   ├── git-commit.md
+│   │   └── pr-create.md
+│   └── optional/            # Install as needed
+│       ├── worktree-setup.md
+│       ├── worktree-cleanup.md
+│       ├── jira-create.md
+│       ├── jira-transition.md
+│       └── docs-update.md
+│
+├── templates/             # Inbox message formats
+│   ├── task-assignment.md
+│   ├── completion-report.md
+│   ├── review-request.md
+│   ├── review-complete.md
+│   └── feedback.md
+│
+└── knowledge-library/     # → KnowledgeLibrary/
+    ├── README.md
+    ├── context.txt
+    ├── architecture.txt
+    ├── prd.txt
+    └── [agent-name]/
+        ├── inbox/processed/
+        ├── outbox/
+        ├── context/current.txt
+        ├── history/
+        ├── tech/
+        └── control/
+```
+
+---
+
+## Quick Start for New Project
+
+```bash
+# 1. Navigate to your project
+cd /path/to/your-project
+
+# 2. Run the installer
+/path/to/coreai/scripts/install.sh \
+  --name "Your Project" \
+  --jira "PROJ" \
+  --github "owner/repo" \
+  --agents "engineering-manager,backend-engineer,qa-engineer" \
+  --all-commands
+
+# 3. Add additional agents as needed
+./coreai/scripts/add-agent.sh frontend-engineer --type ic
+./coreai/scripts/add-agent.sh security-engineer --type reviewer
+
+# 4. Customize
+# - Update tech stack in agent files
+# - Update Jira project key, GitHub repo
+# - Fill in KnowledgeLibrary/context.txt, architecture.txt, prd.txt
+```
+
+---
+
+## Next Steps
+
+### Immediate
+
+1. Test the template with a sample workflow
+2. Create specific engineer agents from templates
+3. Validate message templates work as expected
+
+### Short Term
+
+1. Migrate SurfTrack to use coreai patterns
+2. Refine based on real usage
+3. Add more commands as needed
+
+### Medium Term
+
+1. Explore Phase 3 (agent-to-agent orchestration)
+2. Consider GitHub Actions integration
+3. Build release/hotfix commands
+
+### Long Term
+
+1. Event-driven automation
+2. Self-improving agent patterns
+3. Full autonomy for routine tasks
+
+---
+
+## References
+
+- [README.md](README.md) - Setup instructions
+- [AGENT_SPEC.md](AGENT_SPEC.md) - Master specification
+- [WORKFLOWS.md](WORKFLOWS.md) - State machines
+- [knowledge-library/README.md](knowledge-library/README.md) - Communication hub
+
+---
+
+*Version: 1.0.0*
+*Created: 2026-01-05*
+*Origin: SurfTrack multi-agent system learnings*