@deimoscloud/coreai 0.1.9 → 0.1.11

package/IMPLEMENTATION_PLAN.md

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