@deimoscloud/coreai 0.1.0

package/README.md

@@ -0,0 +1,303 @@
+# CoreAI - AI Agent Orchestration Platform
+
+A configurable, team-ready AI agent orchestration platform for Claude Code.
+
+## Features
+
+- **YAML-based agent definitions** - Define agents in structured YAML, compile to Claude-compatible markdown
+- **Variable resolution** - Use `${config.*}`, `${agent.*}`, and `${remote.*}` variables in definitions
+- **Core + custom agents** - Built-in agent library with support for project-specific customizations
+- **Team filtering** - Configure which agents are available per project
+- **Override system** - Customize core agents without modifying the source
+
+## Installation
+
+```bash
+npm install -g @deimoscloud/coreai
+```
+
+## Quick Start
+
+```bash
+# Initialize a new project (coming soon)
+coreai init
+
+# Build agents to .claude/agents/
+coreai build
+
+# List available agents
+coreai agents list
+
+# Show details for a specific agent
+coreai agents show backend-engineer
+```
+
+## Commands
+
+### `coreai build`
+
+Compile agent definitions to Claude-compatible markdown files.
+
+```bash
+# Build to default output (.claude/agents/)
+coreai build
+
+# Build to custom directory
+coreai build --output ./my-agents
+
+# Watch mode (coming soon)
+coreai build --watch
+```
+
+### `coreai agents list`
+
+List all available agents.
+
+```bash
+# List all agents
+coreai agents list
+
+# List only core agents
+coreai agents list --core
+
+# List only custom/override agents
+coreai agents list --custom
+```
+
+### `coreai agents show <name>`
+
+Display details for a specific agent.
+
+```bash
+# Human-readable output
+coreai agents show backend-engineer
+
+# JSON output
+coreai agents show backend-engineer --json
+
+# Compiled markdown output
+coreai agents show backend-engineer --markdown
+```
+
+### Other Commands
+
+```bash
+# Show version
+coreai --version
+
+# Show help
+coreai --help
+
+# Validate configuration (coming soon)
+coreai validate
+
+# Sync remote context (coming soon)
+coreai sync
+
+# Show project status (coming soon)
+coreai status
+
+# Cache management (coming soon)
+coreai cache status
+coreai cache clear
+```
+
+## Configuration
+
+Create a `coreai.config.yaml` in your project root:
+
+```yaml
+project:
+  name: "My Project"
+  description: "Project description"
+
+team:
+  agents:
+    - backend-engineer
+    - frontend-engineer
+    - devops-engineer
+
+integrations:
+  github:
+    repo: "owner/repo"
+  jira:
+    project: "PROJ"
+
+quality_gates:
+  lint: "npm run lint"
+  test: "npm test"
+  build: "npm run build"
+
+tech_stack:
+  languages:
+    - TypeScript
+    - Node.js
+  frameworks:
+    - Express
+    - React
+```
+
+## Built-in Agents
+
+CoreAI includes these core agents:
+
+| Agent | Type | Description |
+|-------|------|-------------|
+| `backend-engineer` | IC Engineer | Server-side development specialist |
+| `frontend-engineer` | IC Engineer | UI/UX implementation specialist |
+| `devops-engineer` | Specialist | Infrastructure and deployment expert |
+| `engineering-manager` | Manager | Team coordination and delivery |
+
+## Custom Agents
+
+Create custom agents in `coreai/agents/` directory:
+
+```yaml
+# coreai/agents/mobile-engineer.yaml
+role: mobile-engineer
+type: ic-engineer
+display_name: "Mobile Engineer"
+description: "React Native mobile development specialist"
+
+responsibilities:
+  - Implement mobile features
+  - Ensure cross-platform compatibility
+  - Optimize mobile performance
+
+expertise:
+  primary:
+    - React Native
+    - iOS development
+    - Android development
+
+behaviors:
+  workflow: implementation
+  quality_gates:
+    - lint
+    - test
+    - build
+```
+
+### Overriding Core Agents
+
+To customize a core agent, create a file with the same name in `coreai/agents/`:
+
+```yaml
+# coreai/agents/backend-engineer.yaml
+# This overrides the core backend-engineer agent
+
+role: backend-engineer
+type: ic-engineer
+display_name: "Backend Engineer"
+description: "Custom backend engineer for our Python stack"
+
+# ... rest of definition
+```
+
+## Variable Resolution
+
+Agent definitions support three variable namespaces:
+
+### `${config.*}` - Project Configuration
+
+```yaml
+description: "Backend engineer for ${config.project.name}"
+```
+
+### `${agent.*}` - Agent Self-Reference
+
+```yaml
+description: "I am ${agent.display_name}, responsible for ${agent.role}"
+```
+
+### `${remote.*}` - Remote Content (Coming Soon)
+
+```yaml
+context:
+  - "${remote.confluence.architecture-docs}"
+```
+
+## Project Structure
+
+```
+your-project/
+├── coreai.config.yaml          # Project configuration
+├── coreai/
+│   └── agents/                 # Custom agent definitions
+│       └── my-agent.yaml
+├── .claude/
+│   └── agents/                 # Compiled agents (generated)
+│       ├── backend-engineer.md
+│       └── my-agent.md
+└── .coreai/
+    └── cache/                  # Local cache (coming soon)
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/coreai.git
+cd coreai
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run CLI locally
+npm run cli -- --help
+npm run cli -- agents list
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run in watch mode
+npm run test:watch
+```
+
+## Roadmap
+
+See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for detailed implementation status.
+
+### Completed
+
+- Project foundation (TypeScript, CLI, configuration)
+- Agent YAML schema and validation
+- Variable resolution system
+- Agent compiler (YAML to Markdown)
+- Agent CLI commands (build, list, show)
+
+### In Progress
+
+- Integration adapter framework
+- MCP integration layer
+
+### Planned
+
+- Shared context and caching
+- Remote content fetching
+- Skill generation
+- Local state management
+
+## License
+
+MIT

package/WORKFLOWS.md

@@ -0,0 +1,295 @@
+# Workflow Definitions
+
+> **PURPOSE:** Defines mandatory workflows as state machines.
+> All agents MUST follow these workflows. Each state has required outputs.
+
+---
+
+## Workflow 1: Ticket Implementation
+
+**Applies to:** Any Jira ticket being implemented
+
+### State Machine
+
+```
+BACKLOG → IN_PROGRESS → PR_CREATED → IN_REVIEW → APPROVED → MERGED → DONE
+```
+
+### State Definitions
+
+#### BACKLOG
+- **Entry:** Ticket exists, not yet assigned
+- **Owner:** EM
+- **Exit to IN_PROGRESS:** EM delegates to engineer via inbox
+
+#### IN_PROGRESS
+- **Entry conditions:**
+  - Engineer received task via inbox
+  - Engineer moves ticket to "In Progress" via Jira
+  - Engineer adds Jira comment: "Starting work. Branch: `feature/SUR-XX-description`"
+- **Owner:** Engineer
+- **Required outputs before exit:**
+  - [ ] Code changes complete
+  - [ ] Unit tests written and passing
+  - [ ] Lint checks pass
+  - [ ] Static analysis passes
+  - [ ] All acceptance criteria addressed
+- **Exit to PR_CREATED:** Engineer creates PR
+
+#### PR_CREATED
+- **Entry conditions:**
+  - Branch pushed to origin
+  - PR created with correct title format
+- **Owner:** Engineer
+- **Required outputs:**
+  - PR URL logged in completion report
+  - Jira comment: "PR created: [URL]"
+- **Exit to IN_REVIEW:** Engineer moves ticket to "In Review"
+
+#### IN_REVIEW
+- **Entry conditions:**
+  - Ticket status is "In Review"
+  - CI checks passing
+  - Completion report sent to EM inbox
+- **Owner:** Engineer → EM → Reviewers
+- **EM validation:**
+  - [ ] Ticket status correct
+  - [ ] PR exists
+  - [ ] CI passing
+  - [ ] Completion report valid
+- **Required outputs:**
+  - EM assigns reviewers via inbox
+  - Reviewers post approval/feedback on PR
+- **Exit to APPROVED:** Reviewer posts APPROVED decision
+
+#### APPROVED
+- **Entry conditions:**
+  - At least one approval posted on PR
+  - All review comments addressed
+  - CI still passing
+- **Owner:** User (human)
+- **Required action:** User merges PR
+- **Exit to MERGED:** PR merged to main
+
+#### MERGED
+- **Entry conditions:**
+  - PR merged to main
+  - CI passes on main
+- **Owner:** EM
+- **Required outputs:**
+  - Jira comment: "Merged to main: [commit SHA]"
+  - Ticket moved to "Done"
+- **Exit to DONE:** Verification complete
+
+#### DONE
+- **Entry conditions:**
+  - Jira ticket is "Done"
+  - All documentation updated
+- **Owner:** EM
+- **Workflow complete**
+
+---
+
+## Workflow 2: Code Review
+
+**Applies to:** Any PR assigned for review
+
+### State Machine
+
+```
+ASSIGNED → REVIEWING → DECISION_POSTED
+```
+
+### State Definitions
+
+#### ASSIGNED
+- **Entry:** Reviewer receives request via inbox
+- **Owner:** Reviewer (solutions-architect, security-engineer, etc.)
+- **Exit to REVIEWING:** Reviewer begins review
+
+#### REVIEWING
+- **Required checks:**
+  - [ ] Code follows development standards
+  - [ ] Tests are adequate for changes
+  - [ ] No security vulnerabilities
+  - [ ] Architecture aligns with design
+  - [ ] Performance implications considered
+- **Exit to DECISION_POSTED:** Review complete
+
+#### DECISION_POSTED
+- **Required outputs:**
+  - Review comment posted on GitHub PR (via `gh pr comment`)
+  - Completion report sent to EM inbox
+- **Review comment format:**
+
+```markdown
+## Code Review: SUR-XX
+
+### Summary
+[Brief description of what was reviewed]
+
+### Checklist
+- [x] Code follows development standards
+- [x] Tests are adequate
+- [x] No security vulnerabilities
+- [x] Architecture aligns with design
+- [x] Performance considered
+
+### Findings
+- [Positive/concern/blocking items]
+
+### **DECISION: APPROVED** | **DECISION: CHANGES REQUESTED**
+
+[If APPROVED]: Ready for merge by repository owner.
+[If CHANGES REQUESTED]: Please address the issues marked above.
+
+---
+*Review by: [agent-name]*
+```
+
+---
+
+## Workflow 3: Release Process
+
+**Applies to:** Creating a new release for deployment
+
+### State Machine
+
+```
+PLANNING → VERSION_BUMPED → TAGGED → BUILD_VERIFIED → DEPLOYED
+```
+
+### State Definitions
+
+#### PLANNING
+- **Entry:** Release scope defined
+- **Required:** All included tickets merged to main
+- **Exit:** Version numbers updated
+
+#### VERSION_BUMPED
+- **Required outputs:**
+  - versionCode incremented
+  - versionName updated
+  - Version bump commit pushed
+- **Exit:** Git tag created
+
+#### TAGGED
+- **Required outputs:**
+  - Annotated tag: `watch-vX.Y.Z` or `phone-vX.Y.Z`
+  - Tag message includes release notes
+  - Release workflow triggered
+- **Exit:** Build completes
+
+#### BUILD_VERIFIED
+- **Required outputs:**
+  - GitHub Release created with artifacts
+  - ProGuard mapping attached
+- **Exit:** Deployed to testing track
+
+#### DEPLOYED
+- **Required outputs:**
+  - Deployed to Play Console track
+  - Installation verified
+  - Notification sent
+
+---
+
+## Workflow 4: Hotfix Process
+
+**Applies to:** Critical bugs requiring immediate fix
+
+### State Machine
+
+```
+IDENTIFIED → HOTFIX_BRANCH → FIX_IMPLEMENTED → EXPEDITED_REVIEW → DEPLOYED
+```
+
+### State Definitions
+
+#### IDENTIFIED
+- **Entry:** Critical bug confirmed
+- **Required:** HOTFIX label on ticket, team notified
+- **Exit:** Hotfix branch created
+
+#### HOTFIX_BRANCH
+- **Required:** Branch from affected release or main
+- **Naming:** `hotfix/SUR-XX-description`
+- **Exit:** Fix coding started
+
+#### FIX_IMPLEMENTED
+- **Required outputs:**
+  - Minimal fix (no feature creep)
+  - Regression test added
+  - All checks passing
+- **Exit:** PR created
+
+#### EXPEDITED_REVIEW
+- **Required:** Single reviewer, focused on fix correctness
+- **Exit:** Approved and merged
+
+#### DEPLOYED
+- **Required outputs:**
+  - Version bumped to patch release
+  - Deployed directly to production
+  - Post-mortem scheduled
+
+---
+
+## Checkpoint Reporting Format
+
+When completing any workflow state, report using this format:
+
+```markdown
+## Workflow Checkpoint
+**Workflow:** [Ticket Implementation | Code Review | Release | Hotfix]
+**Ticket:** SUR-XX
+**Previous State:** [state name]
+**Current State:** [state name]
+**Timestamp:** [YYYY-MM-DD HH:MM]
+
+### Entry Conditions Verified
+- [x] Condition 1
+- [x] Condition 2
+
+### Required Outputs Completed
+- [x] Output 1: [details/link]
+- [x] Output 2: [details/link]
+
+### Next State
+**Target:** [next state name]
+**Blockers:** [None | list blockers]
+```
+
+---
+
+## Workflow Violations
+
+If unable to complete a required output:
+
+1. **STOP** - Do not proceed to next state
+2. **Report blocker** - Document what's missing
+3. **Escalate** - Notify appropriate agent
+4. **Wait** - Do not skip the step
+
+**Common violations to catch:**
+- Creating PR before tests pass
+- Merging without CI green
+- Skipping Jira status updates
+- Not posting review to GitHub PR
+- Missing workflow checkpoint in completion report
+
+---
+
+## Quick Reference
+
+| Workflow | When to Use | Final State |
+|----------|-------------|-------------|
+| Ticket Implementation | Implementing a Jira ticket | DONE |
+| Code Review | Reviewing a PR | DECISION_POSTED |
+| Release | Creating a scheduled release | DEPLOYED |
+| Hotfix | Critical production bug | DEPLOYED |
+
+---
+
+*Version: 1.0.0*
+*Last Updated: 2026-01-05*