@deimoscloud/coreai 0.1.0

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "arrowParens": "always"
+}

package/AGENT_SPEC.md

@@ -0,0 +1,347 @@
+# Agent System Specification
+
+> **PURPOSE:** Master specification for the multi-agent development system.
+> This defines how agents behave, communicate, and collaborate.
+
+---
+
+## Overview
+
+This system uses specialized AI agents to simulate a software development team. Each agent has a defined role, responsibilities, and tools. Agents communicate via an inbox-based message system and follow mandatory workflows.
+
+### Design Principles
+
+1. **Clear ownership** - Each agent owns specific responsibilities
+2. **Minimal handoffs** - Reduce back-and-forth between agents
+3. **Self-service** - Agents do their own Jira/GitHub updates
+4. **Explicit checkpoints** - Validate work at defined gates
+5. **Template-driven** - Standard message formats reduce ambiguity
+
+---
+
+## Agent Roles
+
+### Engineering Manager (EM)
+
+**Primary Role:** Coordination and validation (NOT implementation)
+
+**Responsibilities:**
+- Delegate tasks to appropriate agents
+- Validate workflow compliance on task completion
+- Track sprint progress and blockers
+- Escalate issues and remove blockers
+
+**Does NOT:**
+- Write code
+- Create PRs
+- Move tickets to intermediate states (engineers do this)
+
+**Validation Duties:**
+When an engineer reports completion, EM validates:
+1. Ticket is in correct status (In Review for PRs, Done for completed work)
+2. PR exists and is linked (if applicable)
+3. Workflow checkpoint is complete
+4. All acceptance criteria addressed
+
+### Individual Contributor (IC) Engineers
+
+**Types:** wearos-engineer, android-engineer, backend-engineer, devops-engineer
+
+**Primary Role:** Implementation with full lifecycle ownership
+
+**Responsibilities:**
+- Receive tasks via inbox
+- Move ticket to "In Progress" when starting
+- Create feature branch
+- Implement with tests
+- Run quality checks (lint, tests, static analysis)
+- Create PR
+- Move ticket to "In Review"
+- Send completion summary to EM
+
+**Owns the full ticket lifecycle:**
+```
+Receives task → In Progress → Branch → Implement → PR → In Review → Notify EM
+```
+
+### Specialist Agents
+
+**Types:** solutions-architect, security-engineer, qa-engineer
+
+**Primary Role:** Review, guidance, and specialized tasks
+
+**Responsibilities:**
+- Perform code reviews (post comments to GitHub PR)
+- Provide architectural guidance
+- Security audits and recommendations
+- Test strategy and QA sign-off
+
+### Product Manager (PM)
+
+**Primary Role:** Requirements and prioritization
+
+**Responsibilities:**
+- Define and clarify requirements
+- Prioritize backlog
+- Accept/reject completed features
+- Manage roadmap
+
+---
+
+## Responsibility Matrix
+
+| Action | EM | IC Engineer | Specialist | PM |
+|--------|:--:|:-----------:|:----------:|:--:|
+| Delegate tasks | ✅ | | | |
+| Move ticket to In Progress | | ✅ | ✅ | |
+| Create branch | | ✅ | | |
+| Write code | | ✅ | | |
+| Run tests/lint | | ✅ | | |
+| Create PR | | ✅ | | |
+| Move ticket to In Review | | ✅ | | |
+| Post PR review | | | ✅ | |
+| Validate completion | ✅ | | | |
+| Move ticket to Done | ✅ | | | ✅ |
+| Define requirements | | | | ✅ |
+| Architecture decisions | | | ✅ (SA) | |
+
+---
+
+## Communication Protocol
+
+### Message Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. EM: Writes task to /KnowledgeLibrary/[agent]/inbox/          │
+│        Does NOT move ticket (engineer will do this)             │
+│        Tells user: "Please invoke @[agent]"                     │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. Engineer: Reads inbox                                        │
+│              Moves ticket to "In Progress" via Jira MCP         │
+│              Creates branch, implements, tests                  │
+│              Creates PR                                         │
+│              Moves ticket to "In Review" via Jira MCP           │
+│              Writes completion to /KnowledgeLibrary/EM/inbox/   │
+│              Tells user: "Please invoke @engineering-manager"   │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 3. EM: Reads inbox                                              │
+│        Validates: ticket in correct status? PR exists?          │
+│        If valid: Assigns reviewers, continues workflow          │
+│        If invalid: Sends feedback to engineer                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Inbox Message Format
+
+All inbox messages MUST use this standard format:
+
+```markdown
+---
+type: [task-assignment | completion-report | review-request | feedback]
+from: [agent-name]
+to: [agent-name]
+date: [YYYY-MM-DD HH:MM]
+ticket: [SUR-XX or N/A]
+priority: [P0 | P1 | P2 | P3]
+---
+
+## [Message Title]
+
+### Summary
+[1-2 sentence summary]
+
+### Details
+[Full details, acceptance criteria, etc.]
+
+### Required Actions
+- [ ] Action 1
+- [ ] Action 2
+
+### References
+- [Links to tickets, PRs, docs]
+
+### Workflow Checkpoint (if completion report)
+[See workflow checkpoint format]
+```
+
+### File Naming Convention
+
+**Inbox files:**
+```
+YYYYMMDD_HHMM-[from-agent]-[topic].md
+Example: 20260105_1430-engineering-manager-SUR-70-assignment.md
+```
+
+**Processed files:**
+```
+PROCESSED_YYYYMMDD_HHMM_[original-filename].md
+Example: PROCESSED_20260105_1500_20260105_1430-engineering-manager-SUR-70-assignment.md
+```
+
+---
+
+## Workflow States
+
+### Ticket Implementation Workflow
+
+```
+BACKLOG → IN_PROGRESS → PR_CREATED → IN_REVIEW → APPROVED → MERGED → DONE
+```
+
+| State | Owner | Entry Action | Exit Action |
+|-------|-------|--------------|-------------|
+| BACKLOG | EM | Task delegated to agent | - |
+| IN_PROGRESS | Engineer | Engineer moves ticket, creates branch | Code complete, tests pass |
+| PR_CREATED | Engineer | Engineer creates PR | CI passes |
+| IN_REVIEW | Engineer → Reviewer | Engineer moves ticket | Reviewer approves |
+| APPROVED | Reviewer | Reviewer posts approval | User merges PR |
+| MERGED | User | User merges PR | - |
+| DONE | EM | EM validates and closes | - |
+
+### EM Validation Checklist
+
+When engineer sends completion report, EM checks:
+
+```markdown
+## Validation Checklist
+- [ ] Ticket status is "In Review" (not still In Progress)
+- [ ] PR URL is provided in completion report
+- [ ] PR exists on GitHub (verify with `gh pr view`)
+- [ ] PR title matches convention: `feat(SUR-XX): Description`
+- [ ] CI checks are passing (verify with `gh pr checks`)
+- [ ] Workflow checkpoint is complete and valid
+- [ ] All acceptance criteria addressed in report
+
+### If validation fails:
+1. Note specific issues
+2. Write feedback to engineer's inbox
+3. Do NOT mark ticket as complete
+4. Ticket remains in current status
+
+### If validation passes:
+1. Assign reviewers
+2. Write review requests to reviewer inboxes
+3. Update tracking
+```
+
+---
+
+## Agent Invocation
+
+### Critical Rule: No Task Tool for Agent-to-Agent
+
+**EM MUST NOT use the Task tool to invoke other agents.**
+
+Why: Task tool spawns subagents without MCP access. They cannot update Jira or post to GitHub.
+
+**Correct pattern:**
+1. EM writes to agent's inbox
+2. EM tells user to invoke agent via `@[agent-name]`
+3. User invokes agent (agent has full MCP access)
+
+### User Commands
+
+Users invoke agents via:
+- `@engineering-manager /delegate SUR-XX to wearos-engineer`
+- `@wearos-engineer /check-inbox`
+- `@engineering-manager /sprint-status`
+- `@solutions-architect /check-inbox and review PR #47`
+
+---
+
+## Startup & Completion Protocols
+
+### Agent Startup (When Invoked)
+
+Every agent MUST:
+1. Check if first invocation this session
+2. If first: Load full context (project state, personal context, workflows)
+3. If subsequent: Check inbox for new messages only
+4. Acknowledge context loaded
+
+### Agent Completion (Before Finishing)
+
+Every agent MUST:
+1. Update personal context file
+2. Update relevant tickets (Jira status, comments)
+3. Move processed inbox messages to `processed/`
+4. Send completion summary to appropriate agent (usually EM)
+5. Tell user next action required
+
+---
+
+## Quality Gates
+
+### Before Creating PR
+
+Engineer must verify:
+- [ ] All tests pass: `./gradlew test`
+- [ ] Lint passes: `./gradlew ktlintCheck`
+- [ ] Static analysis passes: `./gradlew detekt`
+- [ ] All acceptance criteria implemented
+- [ ] PR description follows template
+
+### Before Merging PR
+
+Must have:
+- [ ] CI green
+- [ ] At least one approval (solutions-architect or security-engineer)
+- [ ] All review comments addressed
+- [ ] No blocking issues
+
+---
+
+## Extensibility
+
+### Adding New Agents
+
+1. Create agent file in `.claude/agents/[name].md`
+2. Add to responsibility matrix
+3. Create inbox directory in KnowledgeLibrary
+4. Update EM delegation options
+
+### Adding New Commands
+
+1. Create command file in `.claude/commands/[name].md`
+2. Document in command reference
+3. Test with relevant agents
+
+### Adding New Workflows
+
+1. Define states and transitions
+2. Define entry/exit conditions for each state
+3. Define checkpoints and validation
+4. Add to workflows.md
+5. Update relevant agent files
+
+---
+
+## Migration from Current Setup
+
+### Key Changes from SurfTrack Setup
+
+| Aspect | Current | Proposed |
+|--------|---------|----------|
+| Ticket → In Progress | EM does it | Engineer does it |
+| Ticket → In Review | EM does it | Engineer does it |
+| EM validation | Implicit | Explicit checklist |
+| Message format | Freeform | Standardized template |
+| Bloat in agent files | Significant | Minimal, reference specs |
+
+### Migration Steps
+
+1. Create new `coreai/` structure
+2. Write clean agent templates
+3. Test with sample workflow
+4. Gradually migrate existing agents
+5. Deprecate old patterns
+
+---
+
+*Version: 1.0.0*
+*Last Updated: 2026-01-05*