@deimoscloud/coreai 0.1.0

package/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,256 @@
+# CoreAI Platform - Implementation Plan
+
+## Phase 1: Core Platform (MVP)
+
+### Epic 1: Project Foundation
+
+#### 1.1 Initialize TypeScript/Node.js Project ✅
+- [x] Initialize npm package with `@deimoscloud/coreai` name
+- [x] Set up TypeScript configuration
+- [x] Configure ESLint + Prettier
+- [x] Set up Jest for testing
+- [x] Create basic CLI entry point using Commander.js or similar
+- [x] Set up build pipeline (tsup or similar)
+
+#### 1.2 Configuration Schema ✅
+- [x] Define JSON schema for `coreai.config.yaml`
+- [x] Implement YAML parser with schema validation
+- [x] Create TypeScript types from schema
+- [x] Add config file discovery (walk up directory tree)
+- [x] Implement config defaults and merging
+
+**Deliverable:** `coreai init` command that creates a valid `coreai.config.yaml`
+
+---
+
+### Epic 2: Agent System ✅
+
+#### 2.1 Agent YAML Schema
+- [x] Define JSON schema for agent YAML definitions
+- [x] Create core agent definitions (refactor from current .md files):
+  - [x] backend-engineer.yaml
+  - [x] frontend-engineer.yaml
+  - [x] devops-engineer.yaml
+  - [x] engineering-manager.yaml
+- [x] Implement variable resolution (`${config.*}`, `${agent.*}`, `${remote.*}`)
+
+#### 2.2 Agent Compiler (YAML → Markdown)
+- [x] Build compiler that transforms YAML to Claude-compatible .md
+- [x] Handle context source injection (remote + local paths)
+- [x] Support agent customization from config overrides
+- [x] Support custom agents from `coreai/agents/` directory
+
+#### 2.3 Agent Commands ✅
+- [x] `coreai build` - compile all agents to `.claude/agents/`
+- [x] `coreai agents list` - show available agents
+- [x] `coreai agents show <name>` - display agent details
+
+**Deliverable:** Running `coreai build` generates `.claude/agents/*.md` files from YAML definitions ✅
+
+---
+
+### Epic 3: Integration Adapter Framework ✅
+
+#### 3.1 Adapter Interfaces
+- [x] Define `IssueTracker` interface
+- [x] Define `GitProvider` interface
+- [x] Define `DocumentationProvider` interface
+- [x] Create adapter factory with provider selection logic
+
+#### 3.2 MCP Integration Layer
+- [x] Create MCP client wrapper
+- [x] Implement server discovery (from claude config)
+- [x] Build tool mapping system for supported servers
+- [x] Add auto-discovery for unknown servers (with confidence scoring)
+
+#### 3.3 MCP Server Registry
+- [x] Create supported servers registry structure
+- [x] Add mapping for `@modelcontextprotocol/server-github`
+- [x] Research and add Jira MCP server mapping
+- [x] Add mapping for Confluence MCP server
+
+#### 3.4 Native Adapter Fallbacks (minimal for MVP)
+- [x] GitHub native adapter (for when MCP unavailable)
+- [x] Local filesystem adapter (offline/testing)
+
+**Deliverable:** Commands can call `context.getAdapter('issue_tracker')` and get working adapter ✅
+
+---
+
+### Epic 4: Shared Context & Cache ✅
+
+#### 4.1 Cache System
+- [x] Create `.coreai/cache/` directory structure
+- [x] Implement cache read/write operations
+- [x] Add cache metadata (timestamps, source URLs)
+
+#### 4.2 Context Loader
+- [x] Implement remote context fetching via DocumentationProvider
+- [x] Cache-first resolution with remote fallback
+- [x] Handle missing cache (first run) gracefully
+
+#### 4.3 Sync Commands
+- [x] `coreai sync` - refresh cache from remote
+- [x] `coreai sync --force` - clear and refresh
+- [x] `coreai cache clear` - remove local cache
+- [x] `coreai cache status` - show cache state
+
+**Deliverable:** Agents can reference remote docs that are cached locally ✅
+
+---
+
+### Epic 5: Commands & Skills ✅
+
+#### 5.1 Command Framework
+- [x] Create command registration system
+- [x] Implement runtime config reading
+- [x] Add graceful degradation (skip steps if integration missing)
+- [x] Support project-specific commands from `coreai/commands/`
+
+#### 5.2 Core Commands
+- [x] `coreai init` - initialize new project
+- [x] `coreai build` - compile agents
+- [x] `coreai sync` - sync shared context
+- [x] `coreai validate` - validate config and setup
+
+#### 5.3 Skill Generation
+- [x] Generate Claude skills from config
+- [x] Output to `.claude/commands/` directory
+- [x] Skills adapt based on configured integrations
+
+**Deliverable:** `coreai init && coreai build` sets up a working project ✅
+
+---
+
+### Epic 6: Local State (KnowledgeLibrary) ✅
+
+#### 6.1 Directory Structure
+- [x] Define KnowledgeLibrary structure per agent
+- [x] Create initialization for new agents
+- [x] Handle inbox/outbox directories
+
+#### 6.2 State Commands
+- [x] `coreai status` - show agent states, pending messages
+- [x] Integration with agent build (ensure directories exist)
+
+**Deliverable:** Local agent working state functions as before ✅
+
+---
+
+## Implementation Order (Suggested)
+
+```
+Week 1-2: Epic 1 (Foundation)
+    └── Basic CLI, config schema, project structure
+
+Week 3-4: Epic 2 (Agent System)
+    └── YAML schema, compiler, core agents
+
+Week 5-6: Epic 3 (Adapters)
+    └── Interfaces, MCP integration, GitHub adapter
+
+Week 7-8: Epic 4 (Context & Cache)
+    └── Cache system, sync commands
+
+Week 9-10: Epic 5 (Commands)
+    └── Command framework, skill generation
+
+Week 11-12: Epic 6 (Local State) + Integration Testing
+    └── KnowledgeLibrary, end-to-end testing
+```
+
+---
+
+## Definition of Done (Phase 1 MVP)
+
+- [x] Engineer can run `npm install -g @deimoscloud/coreai`
+- [x] Engineer can run `coreai init` in a new project
+- [x] Engineer can configure integrations in `coreai.config.yaml`
+- [x] Engineer can run `coreai build` to generate agent files
+- [x] Engineer can run `coreai sync` to fetch shared context
+- [x] Generated agents work with Claude Code
+- [x] At least GitHub integration works end-to-end
+- [ ] Documentation covers setup and configuration (in progress)
+
+---
+
+## Project Tooling
+
+| Need | Decision |
+|------|----------|
+| Issue tracking | GitHub Issues |
+| Git provider | GitHub |
+| Documentation | Markdown in repo |
+
+Lightweight approach for now. Will dogfood Jira/Confluence integrations once they're built.
+
+---
+
+## Open Implementation Questions
+
+1. **CLI framework** - Commander.js, oclif, or yargs?
+
+   **Answer:** Commander.js - lightweight, widely known, sufficient for our needs.
+
+2. **MCP client** - Use existing SDK or implement minimal client?
+
+   **Answer:** Official MCP SDK (`@modelcontextprotocol/sdk`) - handles protocol evolution, edge cases, and reduces maintenance burden.
+
+3. **Testing strategy** - Unit tests + integration tests with mocked MCP?
+
+   **Answer:** Unit + Mocked integration tests. Unit tests for pure logic (config, compiler), mocked integration for adapters. Jest as test framework. No real API calls in tests.
+
+4. **Monorepo vs single package** - One package or split (core, cli, adapters)?
+
+   **Answer:** Single package (`@deimoscloud/coreai`) for MVP. Simpler tooling, one install command. Can split later if needed based on real usage patterns.
+
+---
+
+## Files to Create (Initial Structure)
+
+```
+coreai/
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── cli/
+│   │   ├── index.ts          # Entry point
+│   │   └── commands/
+│   │       ├── init.ts
+│   │       ├── build.ts
+│   │       ├── sync.ts
+│   │       └── validate.ts
+│   ├── config/
+│   │   ├── schema.ts         # JSON schema
+│   │   ├── loader.ts         # Config loading
+│   │   └── types.ts          # TypeScript types
+│   ├── agents/
+│   │   ├── schema.ts         # Agent YAML schema
+│   │   ├── compiler.ts       # YAML → MD compiler
+│   │   └── definitions/      # Core agent YAMLs
+│   ├── adapters/
+│   │   ├── interfaces.ts     # IssueTracker, GitProvider, etc.
+│   │   ├── factory.ts        # Adapter creation
+│   │   ├── mcp/
+│   │   │   ├── client.ts     # MCP client wrapper
+│   │   │   └── registry.ts   # Supported servers
+│   │   └── native/
+│   │       ├── github.ts
+│   │       └── filesystem.ts
+│   ├── context/
+│   │   ├── cache.ts          # Cache operations
+│   │   └── loader.ts         # Context resolution
+│   └── state/
+│       └── knowledge-library.ts
+├── schemas/
+│   ├── coreai.config.schema.json
+│   └── agent.schema.json
+└── agents/                   # Core agent definitions
+    ├── backend-engineer.yaml
+    ├── frontend-engineer.yaml
+    └── ...
+```
+
+---
+
+*Generated from DRAFT_PRD.md decisions*