@deimoscloud/coreai 0.1.9 → 0.1.11

package/PRODUCT.md

@@ -1,473 +0,0 @@
-# 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*