@deimoscloud/coreai 0.1.8 → 0.1.10

package/DRAFT_PRD.md

@@ -1,1440 +0,0 @@
-# CoreAI Platform - Product Requirements Document (DRAFT)
-
-**Version:** 0.1 (Draft)
-**Author:** [Your Name]
-**Date:** 2026-01-22
-**Status:** Draft for Review
-
----
-
-## 1. Problem Statement
-
-### Current State
-CoreAI is a file-based framework for orchestrating AI agents that simulate a software development team. It works well for a single engineer on a single project but breaks down when:
-
-1. **Multiple engineers work on the same project** - Local KnowledgeLibrary files drift between engineers, causing context inconsistency and conflicting agent states.
-
-2. **Adapting to different projects** - Agent files contain hardcoded references to specific projects (e.g., Surftrack), requiring extensive manual edits when reusing on new projects.
-
-3. **Different tooling across clients/projects** - Some clients use Jira, others use Linear. Some use GitHub, others GitLab. Commands and workflows hardcode these assumptions.
-
-4. **Different quality gates** - Infrastructure projects have different quality requirements than frontend apps. Build commands, linters, and test frameworks vary widely.
-
-5. **Distribution and updates** - No mechanism to distribute improvements or push updates to projects already using the framework.
-
-### Pain Points Observed
-- Copying framework to a client infrastructure project required extensive manual changes
-- Two SREs working on the same project would have divergent KnowledgeLibrary states
-- Agent files mixed generic role behavior with project-specific context
-- No way to "upgrade" a project to a newer version of CoreAI
-
----
-
-## 2. Vision
-
-**CoreAI Platform** - A configurable, team-ready AI agent orchestration platform with remote state management and pluggable integrations.
-
-### Core Principles
-1. **Remote state by default** - All shared context lives in tools teams already use (Confluence, Notion, etc.)
-2. **Configuration over customization** - Project differences are captured in config, not code changes
-3. **Generic agents, specific context** - Agent files define behavior/role; project context comes from remote sources
-4. **Seamless updates** - Teams can upgrade to new CoreAI versions without losing their configuration
-
----
-
-## 3. Goals & Success Metrics
-
-### Goals
-| Goal | Description |
-|------|-------------|
-| **G1** | Multiple engineers can use CoreAI on the same project with consistent shared state |
-| **G2** | Setting up CoreAI on a new project takes <10 minutes of configuration |
-| **G3** | Agent definitions are reusable across any project without modification |
-| **G4** | Supporting a new tooling combination (e.g., Linear + GitLab) requires only config changes |
-| **G5** | Updates to CoreAI core can be distributed to existing installations |
-
-### Success Metrics
-| Metric | Target |
-|--------|--------|
-| Time to configure new project | < 10 minutes |
-| Manual file edits required after config | 0 |
-| Agent file changes needed per project | 0 |
-| State sync issues between team members | 0 |
-
----
-
-## 4. User Personas
-
-### Persona 1: Engineering Lead (Primary)
-- Sets up CoreAI for their team
-- Configures integrations (Jira/Linear, GitHub/GitLab, Confluence/Notion)
-- Maintains the configuration as project needs evolve
-
-### Persona 2: Individual Contributor
-- Uses CoreAI daily without managing configuration
-- Expects consistent experience with teammates
-- Shouldn't need to understand CoreAI internals
-
-### Persona 3: Platform Admin
-- Manages CoreAI across multiple client projects
-- Needs to distribute updates
-- Needs visibility into which projects use which versions
-
----
-
-## 5. Architecture Proposal
-
-### 5.1 High-Level Components
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        CoreAI Platform                          │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
-│  │   Agent     │    │   Config    │    │    Integration      │ │
-│  │   Registry  │    │   Schema    │    │    Adapters         │ │
-│  │             │    │             │    │                     │ │
-│  │ - Generic   │    │ - Project   │    │ - Issue Trackers    │ │
-│  │   role defs │    │   settings  │    │   (Jira, Linear,    │ │
-│  │ - Behaviors │    │ - Tooling   │    │    GitHub Issues)   │ │
-│  │ - Protocols │    │ - Quality   │    │                     │ │
-│  │             │    │   gates     │    │ - Git Providers     │ │
-│  └─────────────┘    │ - Team      │    │   (GitHub, GitLab,  │ │
-│                     │   structure │    │    Bitbucket)       │ │
-│                     └─────────────┘    │                     │ │
-│                                        │ - Documentation     │ │
-│                                        │   (Confluence,      │ │
-│                                        │    Notion, etc.)    │ │
-│                                        └─────────────────────┘ │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-          ┌───────────────────┴───────────────────┐
-          │                                       │
-          ▼                                       ▼
-┌─────────────────────────┐           ┌─────────────────────────┐
-│   REMOTE (Shared)       │           │   LOCAL (Per-Engineer)  │
-│   Confluence/Notion     │           │   KnowledgeLibrary/     │
-├─────────────────────────┤           ├─────────────────────────┤
-│ • PRD                   │           │ • Agent inbox/outbox    │
-│ • Architecture docs     │           │ • Personal context      │
-│ • Project context       │           │ • Objectives/decisions  │
-│ • Tech decisions        │           │ • Working notes         │
-│                         │           │                         │
-│ Single source of truth  │           │ Per-engineer state      │
-│ for entire team         │           │ (no sync needed)        │
-└─────────────────────────┘           └─────────────────────────┘
-```
-
-### 5.2 Component Details
-
-#### Agent Registry
-A library of generic agent definitions stored as YAML, compiled to markdown for Claude.
-
-**Key Principles:**
-- YAML is the source of truth (structured, tooling-friendly)
-- Build step generates `.md` files Claude actually reads
-- Agent definitions contain NO project-specific information
-- Project context comes from config + remote sources at runtime
-
-**YAML → Markdown Pipeline:**
-```
-agents/
-  backend-engineer.yaml     ──┐
-  frontend-engineer.yaml      │   coreai build
-  devops-engineer.yaml        ├─────────────────►  .claude/agents/
-  ...                         │                      backend-engineer.md
-                              │                      frontend-engineer.md
-coreai.config.yaml ───────────┘                      ...
-```
-
-**Example Agent Definition (YAML Source):**
-```yaml
-# backend-engineer.yaml
-role: backend-engineer
-type: ic-engineer
-display_name: Backend Engineer
-
-# ─────────────────────────────────────────────────────────────
-# ROLE DEFINITION
-# ─────────────────────────────────────────────────────────────
-
-description: |
-  You are a Backend Engineer responsible for server-side implementation,
-  API development, database design, and backend infrastructure.
-
-responsibilities:
-  - Implement backend features, APIs, and services
-  - Write and maintain unit and integration tests
-  - Design and optimize database schemas
-  - Perform code reviews when requested
-  - Document technical decisions and API contracts
-
-# ─────────────────────────────────────────────────────────────
-# EXPERTISE & SKILLS
-# ─────────────────────────────────────────────────────────────
-
-expertise:
-  primary:
-    - API design (REST, GraphQL, gRPC)
-    - Database design and optimization
-    - Authentication and authorization
-    - Caching strategies
-    - Message queues and async processing
-
-  # Resolved from config at build time
-  tech_stack: ${config.tech_stack}  # e.g., Node.js, Python, Go, etc.
-
-skills:
-  - Code review with focus on performance, security, maintainability
-  - Debugging and troubleshooting production issues
-  - Writing technical documentation
-  - Estimating implementation complexity
-
-# ─────────────────────────────────────────────────────────────
-# DEVELOPMENT PRINCIPLES
-# ─────────────────────────────────────────────────────────────
-
-principles:
-  code_quality:
-    - Write clean, readable, self-documenting code
-    - Follow SOLID principles and established patterns
-    - Prefer composition over inheritance
-    - Keep functions small and focused
-
-  testing:
-    - Write tests before or alongside implementation
-    - Aim for high coverage on critical paths
-    - Use meaningful test names that describe behavior
-    - Mock external dependencies appropriately
-
-  security:
-    - Never trust user input - validate and sanitize
-    - Use parameterized queries to prevent SQL injection
-    - Implement proper authentication and authorization
-    - Keep dependencies updated for security patches
-
-  performance:
-    - Profile before optimizing
-    - Use appropriate data structures and algorithms
-    - Implement caching where beneficial
-    - Design for horizontal scalability
-
-# ─────────────────────────────────────────────────────────────
-# WORKFLOW & BEHAVIOR
-# ─────────────────────────────────────────────────────────────
-
-behaviors:
-  workflow: ticket-implementation
-  quality_gates: ${config.quality_gates}  # Resolved from project config
-
-# ─────────────────────────────────────────────────────────────
-# CONTEXT SOURCES
-# ─────────────────────────────────────────────────────────────
-
-context_sources:
-  # REMOTE - fetched from Confluence/Notion at startup
-  shared:
-    - ${remote.documentation}/architecture
-    - ${remote.documentation}/prd
-    - ${remote.documentation}/context
-
-  # LOCAL - stays in local KnowledgeLibrary (per-engineer)
-  personal:
-    - KnowledgeLibrary/${agent.name}/context/current.txt
-    - KnowledgeLibrary/${agent.name}/control/objectives.txt
-
-communication:
-  inbox: KnowledgeLibrary/${agent.name}/inbox
-  outbox: KnowledgeLibrary/${agent.name}/outbox
-```
-
-**Generated Markdown Output:**
-The build process combines the YAML definition with project config to produce a complete `.md` file:
-- Resolves `${config.*}` variables from `coreai.config.yaml`
-- Fetches and embeds remote shared context (or includes fetch instructions)
-- Formats into the markdown structure Claude expects
-- Includes local context file paths
-
-#### Configuration Schema
-A single configuration file per project that defines:
-
-```yaml
-# coreai.config.yaml
-version: "1.0"
-
-project:
-  name: "Client Infrastructure"
-  type: infrastructure  # software | infrastructure | data | mobile
-
-team:
-  agents:
-    - backend-engineer
-    - devops-engineer
-    - security-engineer
-    - engineering-manager
-
-integrations:
-  issue_tracker:
-    provider: jira  # jira | linear | github-issues | azure-devops
-    config:
-      project_key: INFRA
-      base_url: https://client.atlassian.net
-
-  git:
-    provider: github  # github | gitlab | bitbucket | azure-devops
-    config:
-      repo: client-org/infrastructure
-      default_branch: main
-
-  documentation:
-    provider: confluence  # confluence | notion | github-wiki | local
-    config:
-      space_key: INFRA
-      base_url: https://client.atlassian.net/wiki
-
-  state:
-    provider: confluence  # confluence | notion | s3 | github-repo
-    config:
-      space_key: INFRA
-      base_path: /CoreAI/State
-
-quality_gates:
-  lint:
-    command: "terraform fmt -check"
-    required: true
-  validate:
-    command: "terraform validate"
-    required: true
-  security_scan:
-    command: "tfsec ."
-    required: true
-  test:
-    command: "terratest"
-    required: false  # Not all infra projects have tests
-
-tech_stack:
-  primary_language: hcl
-  frameworks: [terraform, terragrunt]
-  cloud: aws
-```
-
-#### Integration Adapters
-Pluggable adapters that translate CoreAI operations to specific tools. Each adapter implements a standard interface, allowing commands and workflows to work identically regardless of underlying tool.
-
-**Interface Summary:**
-
-| Interface | Operations | Implementations |
-|-----------|------------|-----------------|
-| `IssueTracker` | createTicket, transitionTicket, getTicket, search | JiraAdapter, LinearAdapter, GitHubIssuesAdapter |
-| `GitProvider` | createBranch, createPR, getPR, mergePR | GitHubAdapter, GitLabAdapter, BitbucketAdapter |
-| `DocumentationProvider` | getPage, updatePage, createPage | ConfluenceAdapter, NotionAdapter |
-
-**How Adapters Work:**
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     CoreAI Command/Workflow                     │
-│                                                                 │
-│   "Create a ticket for this bug"                                │
-│                         │                                       │
-│                         ▼                                       │
-│              ┌─────────────────────┐                            │
-│              │   IssueTracker      │  ◄── Interface (abstract)  │
-│              │   .createTicket()   │                            │
-│              └─────────────────────┘                            │
-│                         │                                       │
-│         ┌───────────────┼───────────────┐                       │
-│         ▼               ▼               ▼                       │
-│   ┌───────────┐   ┌───────────┐   ┌───────────┐                │
-│   │   Jira    │   │  Linear   │   │  GitHub   │                │
-│   │  Adapter  │   │  Adapter  │   │  Issues   │                │
-│   └───────────┘   └───────────┘   └───────────┘                │
-│         │               │               │                       │
-│         ▼               ▼               ▼                       │
-│   POST /rest/     GraphQL           POST /repos/                │
-│   api/2/issue     mutation          {owner}/{repo}/issues       │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-**Adapter Selection:**
-Determined by `coreai.config.yaml`:
-```yaml
-integrations:
-  issue_tracker:
-    provider: jira  # ← Selects JiraAdapter
-```
-
-**Interface Definitions:**
-
-```typescript
-// IssueTracker Interface
-interface IssueTracker {
-  createTicket(params: {
-    title: string;
-    description: string;
-    type: 'bug' | 'story' | 'task';
-    priority?: 'low' | 'medium' | 'high' | 'critical';
-    labels?: string[];
-    assignee?: string;
-  }): Promise<{ id: string; key: string; url: string }>;
-
-  getTicket(key: string): Promise<{
-    key: string;
-    title: string;
-    description: string;
-    status: string;
-    assignee?: string;
-    labels: string[];
-  }>;
-
-  transitionTicket(key: string, status: string): Promise<void>;
-
-  search(query: string, options?: {
-    status?: string[];
-    assignee?: string;
-    limit?: number;
-  }): Promise<Ticket[]>;
-
-  addComment(key: string, comment: string): Promise<void>;
-}
-
-// GitProvider Interface
-interface GitProvider {
-  createBranch(params: {
-    name: string;
-    from?: string;  // default: main/master
-  }): Promise<{ name: string; url: string }>;
-
-  createPR(params: {
-    title: string;
-    body: string;
-    head: string;   // source branch
-    base?: string;  // target branch (default: main)
-    draft?: boolean;
-    reviewers?: string[];
-  }): Promise<{ number: number; url: string }>;
-
-  getPR(number: number): Promise<{
-    number: number;
-    title: string;
-    body: string;
-    status: 'open' | 'closed' | 'merged';
-    reviews: Review[];
-    checks: Check[];
-  }>;
-
-  mergePR(number: number, options?: {
-    method?: 'merge' | 'squash' | 'rebase';
-    deleteSourceBranch?: boolean;
-  }): Promise<void>;
-
-  getFile(path: string, ref?: string): Promise<string>;
-
-  listFiles(path: string, ref?: string): Promise<string[]>;
-}
-
-// DocumentationProvider Interface
-interface DocumentationProvider {
-  getPage(path: string): Promise<{
-    title: string;
-    content: string;  // markdown
-    lastModified: Date;
-    version?: string;
-  }>;
-
-  updatePage(path: string, params: {
-    content: string;
-    message?: string;  // commit message or version note
-  }): Promise<void>;
-
-  createPage(params: {
-    path: string;
-    title: string;
-    content: string;
-    parent?: string;
-  }): Promise<{ url: string }>;
-
-  searchPages(query: string): Promise<{
-    path: string;
-    title: string;
-    snippet: string;
-  }[]>;
-}
-```
-
-**Adapter Implementation Example (Jira):**
-
-```typescript
-// adapters/jira.ts
-import { IssueTracker, Ticket } from '../interfaces';
-
-export class JiraAdapter implements IssueTracker {
-  private baseUrl: string;
-  private projectKey: string;
-  private auth: { email: string; token: string };
-
-  constructor(config: JiraConfig) {
-    this.baseUrl = config.base_url;
-    this.projectKey = config.project_key;
-    this.auth = { email: config.email, token: config.api_token };
-  }
-
-  async createTicket(params: CreateTicketParams): Promise<TicketResult> {
-    const response = await fetch(`${this.baseUrl}/rest/api/3/issue`, {
-      method: 'POST',
-      headers: this.getHeaders(),
-      body: JSON.stringify({
-        fields: {
-          project: { key: this.projectKey },
-          summary: params.title,
-          description: this.toADF(params.description),  // Jira uses ADF format
-          issuetype: { name: this.mapType(params.type) },
-          priority: params.priority ? { name: params.priority } : undefined,
-          labels: params.labels,
-          assignee: params.assignee ? { accountId: params.assignee } : undefined,
-        }
-      })
-    });
-
-    const data = await response.json();
-    return {
-      id: data.id,
-      key: data.key,
-      url: `${this.baseUrl}/browse/${data.key}`
-    };
-  }
-
-  async transitionTicket(key: string, status: string): Promise<void> {
-    // 1. Get available transitions
-    const transitions = await this.getTransitions(key);
-    const transition = transitions.find(t => t.to.name === status);
-
-    if (!transition) {
-      throw new Error(`Cannot transition ${key} to ${status}`);
-    }
-
-    // 2. Execute transition
-    await fetch(`${this.baseUrl}/rest/api/3/issue/${key}/transitions`, {
-      method: 'POST',
-      headers: this.getHeaders(),
-      body: JSON.stringify({ transition: { id: transition.id } })
-    });
-  }
-
-  // ... other methods
-}
-```
-
-**Using Adapters in Commands:**
-
-Commands become tool-agnostic by using the interface:
-
-```typescript
-// commands/create-ticket.ts
-export async function createTicket(args: Args, context: Context) {
-  // Get the configured adapter (Jira, Linear, etc.)
-  const issueTracker = context.getAdapter<IssueTracker>('issue_tracker');
-
-  // Same code works for any issue tracker
-  const ticket = await issueTracker.createTicket({
-    title: args.title,
-    description: args.description,
-    type: args.type ?? 'task',
-  });
-
-  return `Created ticket: ${ticket.key} - ${ticket.url}`;
-}
-```
-
-**MCP Server Integration:**
-
-Adapters can also be exposed as MCP tools, allowing Claude to call them directly:
-
-```yaml
-# coreai.config.yaml
-mcp:
-  expose_adapters: true  # Makes adapters available as MCP tools
-```
-
-This generates MCP tool definitions like:
-- `coreai_create_ticket` → IssueTracker.createTicket()
-- `coreai_transition_ticket` → IssueTracker.transitionTicket()
-- `coreai_create_pr` → GitProvider.createPR()
-- etc.
-
-**Authentication:**
-
-Each adapter handles auth according to its provider's requirements:
-
-| Provider | Auth Method | Config Location |
-|----------|-------------|-----------------|
-| Jira | API Token | `JIRA_EMAIL` + `JIRA_API_TOKEN` env vars |
-| Linear | API Key | `LINEAR_API_KEY` env var |
-| GitHub | PAT or App | `GITHUB_TOKEN` env var or GitHub App |
-| GitLab | PAT | `GITLAB_TOKEN` env var |
-| Confluence | API Token | `CONFLUENCE_EMAIL` + `CONFLUENCE_TOKEN` env vars |
-| Notion | Integration Token | `NOTION_TOKEN` env var |
-
----
-
-#### MCP-Backed Adapters
-
-When an MCP server already exists for a tool (Jira, GitHub, Confluence, etc.), we should use it instead of implementing our own API calls. This gives us:
-- Battle-tested implementations maintained by others
-- Consistent auth handling via MCP config
-- Less code to maintain
-- Community improvements for free
-
-**Adapter Implementation Strategies:**
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                      IssueTracker Interface                     │
-│                                                                 │
-│                    .createTicket()                              │
-│                    .transitionTicket()                          │
-│                    .getTicket()                                 │
-│                              │                                  │
-│              ┌───────────────┼───────────────┐                  │
-│              ▼               ▼               ▼                  │
-│     ┌─────────────┐   ┌─────────────┐   ┌─────────────┐        │
-│     │   Native    │   │  MCP-Based  │   │   Hybrid    │        │
-│     │   Adapter   │   │   Adapter   │   │   Adapter   │        │
-│     └─────────────┘   └─────────────┘   └─────────────┘        │
-│            │                 │                 │                │
-│            ▼                 ▼                 ▼                │
-│     Direct API calls   MCP Server calls   MCP + fallback       │
-│     (fetch/axios)      (tool invocation)  to native API        │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-**Configuration for MCP-Backed Adapters:**
-
-```yaml
-# coreai.config.yaml
-integrations:
-  issue_tracker:
-    provider: jira
-
-    # Strategy: 'mcp' | 'native' | 'auto'
-    # - mcp: Use MCP server exclusively (fail if not available)
-    # - native: Use built-in API adapter (no MCP dependency)
-    # - auto: Use MCP if available, fall back to native
-    strategy: mcp
-
-    # MCP server configuration (when strategy is 'mcp' or 'auto')
-    mcp:
-      server: "@anthropic/jira-mcp"  # npm package or path
-      # OR reference existing MCP config
-      server_name: "jira"  # references server in claude_desktop_config.json
-
-    # Native config (when strategy is 'native' or 'auto' fallback)
-    config:
-      project_key: PROJ
-      base_url: https://company.atlassian.net
-
-  git:
-    provider: github
-    strategy: mcp
-    mcp:
-      server_name: "github"  # Use existing GitHub MCP from user's config
-
-  documentation:
-    provider: confluence
-    strategy: auto  # Try MCP first, fall back to native
-    mcp:
-      server: "@anthropic/confluence-mcp"
-    config:
-      space_key: DOCS
-      base_url: https://company.atlassian.net/wiki
-```
-
-**MCP Adapter Implementation:**
-
-```typescript
-// adapters/mcp-jira.ts
-import { IssueTracker, Ticket } from '../interfaces';
-import { MCPClient } from '../mcp/client';
-
-export class MCPJiraAdapter implements IssueTracker {
-  private mcp: MCPClient;
-  private serverName: string;
-
-  constructor(config: MCPAdapterConfig) {
-    this.serverName = config.server_name;
-    this.mcp = new MCPClient();
-  }
-
-  async createTicket(params: CreateTicketParams): Promise<TicketResult> {
-    // Call the MCP tool instead of direct API
-    const result = await this.mcp.callTool(this.serverName, 'jira_create_issue', {
-      project: params.projectKey,
-      summary: params.title,
-      description: params.description,
-      issuetype: params.type,
-      priority: params.priority,
-    });
-
-    return {
-      id: result.id,
-      key: result.key,
-      url: result.url,
-    };
-  }
-
-  async transitionTicket(key: string, status: string): Promise<void> {
-    await this.mcp.callTool(this.serverName, 'jira_transition_issue', {
-      issue_key: key,
-      transition: status,
-    });
-  }
-
-  async getTicket(key: string): Promise<Ticket> {
-    const result = await this.mcp.callTool(this.serverName, 'jira_get_issue', {
-      issue_key: key,
-    });
-
-    return {
-      key: result.key,
-      title: result.summary,
-      description: result.description,
-      status: result.status,
-      assignee: result.assignee,
-      labels: result.labels,
-    };
-  }
-
-  // ... other methods map to MCP tools
-}
-```
-
-**How MCP Tool Mapping Works:**
-
-The challenge: MCP servers don't follow a standard naming convention. One Jira MCP might call it `jira_create_issue`, another calls it `create_ticket`. We need a translation layer.
-
-**Our approach: Supported MCP Servers (Curated List)**
-
-CoreAI maintains a curated list of **officially supported MCP servers** with built-in mappings. These are tested and maintained as part of CoreAI releases.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                  CoreAI Supported MCP Servers                   │
-│                     (Built-in, Maintained)                      │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  Issue Trackers:                                                │
-│  ├── @anthropic/jira-mcp (official)                             │
-│  ├── @modelcontextprotocol/jira-server                          │
-│  └── @linear/mcp-server                                         │
-│                                                                 │
-│  Git Providers:                                                 │
-│  ├── @anthropic/github-mcp (official)                           │
-│  ├── @modelcontextprotocol/github-server                        │
-│  └── @gitlab/mcp-server                                         │
-│                                                                 │
-│  Documentation:                                                 │
-│  ├── @anthropic/confluence-mcp (official)                       │
-│  └── @notionhq/mcp-server                                       │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-**When you configure an integration:**
-
-```yaml
-integrations:
-  issue_tracker:
-    provider: jira
-    strategy: mcp
-    mcp:
-      server_name: "jira"  # References your existing MCP config
-```
-
-CoreAI:
-1. Looks up "jira" in your MCP config to find the server
-2. Identifies which supported MCP server it is (by package name or auto-detection)
-3. Uses the built-in mapping for that server
-
-**No manual mapping required for supported servers.**
-
-**How We Identify the MCP Server:**
-
-```typescript
-// On first use, CoreAI queries the MCP server
-const serverInfo = await mcp.getServerInfo("jira");
-// Returns: { name: "@anthropic/jira-mcp", version: "1.2.0", tools: [...] }
-
-// Look up in our supported servers registry
-const mapping = SUPPORTED_MCP_SERVERS["@anthropic/jira-mcp"];
-// Returns built-in mapping for this server
-```
-
-**Auto-Discovery for Unknown Servers:**
-
-If the MCP server isn't in our supported list, we attempt auto-discovery:
-
-```typescript
-// 1. Get available tools from the MCP server
-const tools = await mcp.listTools("custom-jira");
-// Returns: ["create_issue", "get_issue", "transition", "search", "comment"]
-
-// 2. Use fuzzy matching to map to our interface
-const autoMapping = {
-  createTicket: findToolMatch(tools, ["create_issue", "create_ticket", "new_issue"]),
-  getTicket: findToolMatch(tools, ["get_issue", "fetch_issue", "read_issue"]),
-  // ...
-};
-
-// 3. If high confidence (>80% match), use auto-discovered mapping
-// 4. If low confidence, warn user and ask for explicit mapping
-```
-
-**Three Scenarios:**
-
-| Scenario | What Happens | User Action |
-|----------|--------------|-------------|
-| **Supported MCP server** | Built-in mapping used automatically | None - just works |
-| **Unknown server, auto-discovery succeeds** | Auto-mapping used with warning | Review mapping (optional) |
-| **Unknown server, auto-discovery fails** | Error with helpful message | Provide explicit mapping |
-
-**Explicit Mapping (Only for Custom/Unsupported Servers):**
-
-If you're using a custom or unsupported MCP server, you provide the mapping:
-
-```yaml
-integrations:
-  issue_tracker:
-    provider: jira
-    strategy: mcp
-    mcp:
-      server_name: "my-custom-jira-mcp"
-      # Only needed for unsupported servers
-      tool_mappings:
-        createTicket: my_create_ticket
-        getTicket: my_get_ticket
-        transitionTicket: my_transition
-        search: my_search
-        addComment: my_comment
-```
-
-**Contributing New MCP Server Support:**
-
-When a new MCP server becomes popular, we add it to the supported list:
-
-```typescript
-// src/mcp/supported-servers.ts
-export const SUPPORTED_MCP_SERVERS = {
-  "@anthropic/jira-mcp": {
-    type: "issue_tracker",
-    provider: "jira",
-    mappings: {
-      createTicket: "jira_create_issue",
-      getTicket: "jira_get_issue",
-      transitionTicket: "jira_transition_issue",
-      search: "jira_search",
-      addComment: "jira_add_comment",
-    },
-  },
-
-  "@linear/mcp-server": {
-    type: "issue_tracker",
-    provider: "linear",
-    mappings: {
-      createTicket: "createIssue",
-      getTicket: "getIssue",
-      transitionTicket: "updateIssueState",
-      search: "searchIssues",
-      addComment: "createComment",
-    },
-  },
-
-  // ... more servers
-};
-```
-
-This is similar to how database ORMs work:
-- Prisma supports PostgreSQL, MySQL, SQLite out of the box
-- Each has different SQL dialects, but Prisma handles the translation
-- You can add custom drivers for unsupported databases
-
-**Summary:**
-
-| Question | Answer |
-|----------|--------|
-| Do I need to map tools manually? | No, for supported MCP servers |
-| What if I use a custom MCP server? | Auto-discovery tries first, then explicit mapping |
-| How do new MCP servers get supported? | CoreAI releases add them to the curated list |
-| Can I contribute a mapping? | Yes, via PR to CoreAI repo |
-
-**Adapter Factory:**
-
-The system automatically selects the right adapter based on config:
-
-```typescript
-// adapters/factory.ts
-export function createAdapter(
-  type: 'issue_tracker' | 'git' | 'documentation',
-  config: IntegrationConfig
-): IssueTracker | GitProvider | DocumentationProvider {
-
-  const strategy = config.strategy ?? 'auto';
-
-  if (strategy === 'mcp' || strategy === 'auto') {
-    // Check if MCP server is available
-    if (config.mcp && isMCPServerAvailable(config.mcp)) {
-      return createMCPAdapter(type, config);
-    }
-
-    if (strategy === 'mcp') {
-      throw new Error(`MCP server required but not available: ${config.mcp.server_name}`);
-    }
-  }
-
-  // Fall back to native adapter
-  return createNativeAdapter(type, config);
-}
-```
-
-**Benefits of MCP-First Approach:**
-
-| Benefit | Description |
-|---------|-------------|
-| **Reuse existing setup** | If user already has Jira MCP configured, just reference it |
-| **Auth handled by MCP** | No need to manage API tokens separately |
-| **Community maintained** | MCP servers get updates and fixes from maintainers |
-| **Consistent experience** | Same MCP tools work in Claude Desktop, CLI, and CoreAI |
-| **Fallback option** | Native adapters available when MCP not suitable |
-
-**When to Use Native vs MCP:**
-
-| Use MCP When | Use Native When |
-|--------------|-----------------|
-| MCP server exists and is maintained | No MCP server available for the tool |
-| User already has MCP configured | Running in CI/CD (no MCP context) |
-| Want community improvements | Need custom API behavior |
-| Simpler auth management | Offline/air-gapped environments |
-
-#### Remote State Layer
-Hybrid approach: shared context is remote, agent working state is local.
-
-**Shared Context (REMOTE):**
-- PRD, architecture decisions, project context
-- Stored in documentation provider (Confluence/Notion)
-- Single source of truth for all team members
-- Read by all agents at startup
-- Updated via designated workflows (EM/PM only for PRD, etc.)
-
-**Agent Working State (LOCAL):**
-- Personal context, objectives, decisions
-- Inbox/outbox messages
-- Stored in local KnowledgeLibrary (current approach)
-- Each engineer has their own agent instance
-- No sync needed - agent state is per-engineer, not shared
-
-**Why Hybrid?**
-- Shared context is what causes drift between team members - must be remote
-- Agent directories are personal working state - each engineer runs their own agents
-- Avoids API latency and rate limits for frequent inbox/outbox operations
-- Simpler implementation - only sync what actually needs to be shared
-- Local agent state can still be git-ignored or committed per team preference
-
----
-
-## 6. Feature Requirements
-
-### 6.1 Phase 1: Core Platform (MVP)
-
-#### F1.1 Configuration-Driven Setup
-- [ ] Define configuration schema (YAML/JSON)
-- [ ] Validate configuration on install
-- [ ] Generate all required files from config
-- [ ] Support multiple tech stack presets (node, python, go, terraform, etc.)
-
-#### F1.2 Generic Agent Definitions
-- [ ] Refactor existing agents to remove project-specific content
-- [ ] Create agent YAML schema with context references
-- [ ] Support runtime resolution of context sources
-- [ ] Maintain backward compatibility with existing agent invocation
-
-#### F1.3 Integration Adapters (Core Set)
-- [ ] Jira adapter (issue tracker)
-- [ ] GitHub adapter (git provider)
-- [ ] Confluence adapter (documentation + state)
-- [ ] Local filesystem adapter (fallback/offline mode)
-
-#### F1.4 Curated MCP Server Support (Phase 1)
-
-Start with the most common tools teams actually use:
-
-| Category | MCP Server | Priority | Rationale |
-|----------|------------|----------|-----------|
-| **Issue Tracker** | `@modelcontextprotocol/server-github` (issues) | P0 | Most common, free tier |
-| **Issue Tracker** | Jira MCP (TBD - find best option) | P0 | Enterprise standard |
-| **Git Provider** | `@modelcontextprotocol/server-github` | P0 | Most common |
-| **Documentation** | `@modelcontextprotocol/server-confluence` | P1 | Atlassian stack common |
-| **Documentation** | `@modelcontextprotocol/server-notion` | P1 | Popular for smaller teams |
-
-**Phase 1 Goal:** Support the Atlassian stack (Jira + Confluence + GitHub) since this covers the majority of enterprise teams.
-
-**How the curated list grows:**
-1. Community requests via GitHub issues
-2. Usage analytics (opt-in) show demand
-3. PR contributions with mappings + tests
-4. Each CoreAI release can add new servers
-
-**MCP Server Registry Structure:**
-```typescript
-// src/mcp/registry.ts
-export const MCP_SERVER_REGISTRY = {
-  // ─────────────────────────────────────────────────────────
-  // PHASE 1: Core (MVP)
-  // ─────────────────────────────────────────────────────────
-  "@modelcontextprotocol/server-github": {
-    phase: 1,
-    types: ["issue_tracker", "git"],
-    provider: "github",
-    mappings: {
-      // IssueTracker
-      createTicket: "create_issue",
-      getTicket: "get_issue",
-      // GitProvider
-      createBranch: "create_branch",
-      createPR: "create_pull_request",
-      getPR: "get_pull_request",
-      // ...
-    },
-  },
-
-  "jira-mcp-server": {  // TBD: identify best Jira MCP
-    phase: 1,
-    types: ["issue_tracker"],
-    provider: "jira",
-    mappings: {
-      createTicket: "create_issue",
-      getTicket: "get_issue",
-      transitionTicket: "transition_issue",
-      search: "search_issues",
-      addComment: "add_comment",
-    },
-  },
-
-  // ─────────────────────────────────────────────────────────
-  // PHASE 2: Extended
-  // ─────────────────────────────────────────────────────────
-  "@modelcontextprotocol/server-gitlab": {
-    phase: 2,
-    types: ["issue_tracker", "git"],
-    provider: "gitlab",
-    mappings: { /* ... */ },
-  },
-
-  "linear-mcp": {  // TBD
-    phase: 2,
-    types: ["issue_tracker"],
-    provider: "linear",
-    mappings: { /* ... */ },
-  },
-
-  "@modelcontextprotocol/server-confluence": {
-    phase: 2,
-    types: ["documentation"],
-    provider: "confluence",
-    mappings: { /* ... */ },
-  },
-
-  "@modelcontextprotocol/server-notion": {
-    phase: 2,
-    types: ["documentation"],
-    provider: "notion",
-    mappings: { /* ... */ },
-  },
-};
-```
-
-**Before Phase 1 ships, we need to:**
-1. Identify the actual MCP server packages for Jira (research existing options)
-2. Test each supported server end-to-end
-3. Document any quirks or limitations per server
-
-#### F1.5 Shared Context Sync
-- [ ] Read shared context from remote (Confluence/Notion) on agent startup
-- [ ] Cache shared context locally with TTL for performance
-- [ ] Provide commands to update shared context (with proper permissions)
-- [ ] Handle offline/disconnected gracefully (use cached version)
-- [ ] Agent working state (inbox/outbox/personal context) remains local
-
-### 6.2 Phase 2: Extended Integrations
-
-#### F2.1 Additional MCP Server Support
-Expand the curated list based on user demand:
-
-| Category | MCP Server | Notes |
-|----------|------------|-------|
-| Issue Tracker | Linear MCP | Popular with startups |
-| Issue Tracker | Azure DevOps MCP | Enterprise Microsoft shops |
-| Git Provider | GitLab MCP | Self-hosted Git common in enterprise |
-| Git Provider | Bitbucket MCP | Atlassian Git option |
-| Documentation | Notion MCP | Popular for smaller/modern teams |
-
-#### F2.2 Native Adapter Fallbacks
-For when MCP isn't available (CI/CD, offline):
-- [ ] Native Jira adapter (direct API)
-- [ ] Native GitHub adapter (direct API)
-- [ ] Native GitLab adapter (direct API)
-- [ ] Native Confluence adapter (direct API)
-
-#### F2.3 Additional State Providers
-- [ ] S3/GCS adapter (state storage for teams without Confluence/Notion)
-- [ ] GitHub repo adapter (state as files in a dedicated repo)
-
-### 6.3 Phase 3: Distribution & Updates
-
-#### F3.1 Package Distribution
-- [ ] Publish as npm package / brew formula / standalone binary
-- [ ] Version management
-- [ ] Dependency resolution
-
-#### F3.2 Update Mechanism
-- [ ] Check for updates command
-- [ ] Upgrade installed project to new version
-- [ ] Preserve project configuration during upgrade
-- [ ] Migration scripts for breaking changes
-
-#### F3.3 Enterprise Features
-- [ ] Project registry (track all installations)
-- [ ] Usage analytics (optional, opt-in)
-- [ ] Centralized configuration inheritance
-
----
-
-## 7. Technical Decisions
-
-### 7.1 Implementation Language/Runtime
-| Option | Pros | Cons |
-|--------|------|------|
-| **TypeScript/Node.js** | Familiar to web teams, npm distribution, good async | Requires Node.js installed |
-| **Go** | Single binary, cross-platform, fast | Less familiar, harder to extend |
-| **Python** | AI/ML ecosystem, pip distribution | Dependency management complexity |
-| **Shell + jq** | No dependencies, current approach | Limited capabilities, harder to maintain |
-
-**Decision: TypeScript/Node.js**
-- Distribution via npm
-- Core platform maintained in main repo (modifications require repo access)
-- Users can extend for project-specific needs without modifying core
-
-### 7.2 Configuration Format
-| Option | Pros | Cons |
-|--------|------|------|
-| **YAML** | Human-readable, supports comments | Whitespace-sensitive |
-| **JSON** | Universal support, strict | No comments, verbose |
-| **TOML** | Clean syntax, good for config | Less common |
-
-**Decision: YAML with JSON schema validation**
-- Human-readable config files with inline comments
-- JSON schema provides IDE autocomplete and validation
-- Familiar to teams using k8s, docker-compose, GitHub Actions
-
-### 7.3 State Provider Strategy
-| Option | Pros | Cons |
-|--------|------|------|
-| **Fully remote** | Complete sync | API rate limits, latency, complexity |
-| **Fully local** | Fast, simple | Drift between team members |
-| **Hybrid (shared=remote, agent=local)** | Sync what matters, fast operations | Two systems to understand |
-
-**Decision: Hybrid approach**
-- Shared context (PRD, architecture, project context) stored in Confluence/Notion
-- Agent working state (inbox/outbox, personal context) stays local per-engineer
-- Solves drift problem while keeping agent operations fast
-
-### 7.4 Command/Skill Generation
-| Option | Pros | Cons |
-|--------|------|------|
-| **Static templates with placeholders** | Simple, current approach | Limited flexibility |
-| **Runtime generation from config** | Always up-to-date | More complex |
-| **Plugin system** | Maximum flexibility | Over-engineering risk |
-
-**Decision: Runtime generation from config**
-- Commands read `coreai.config.yaml` at execution and adapt behavior
-- Skip steps gracefully if integration not configured (e.g., no issue tracker = skip ticket creation)
-- Project-specific extensions via `coreai/commands/` directory without modifying core
-
----
-
-## 8. Migration Path
-
-### From Current CoreAI to Platform
-
-1. **Phase 0: Preparation**
-   - Document all project-specific content in current agent files
-   - Identify all placeholder patterns used
-
-2. **Phase 1: New Installation**
-   - New projects use config-driven installation
-   - Existing projects continue working unchanged
-
-3. **Phase 2: Migration Tool**
-   - Tool to generate config from existing installation
-   - Tool to upgrade existing installation to new structure
-
-4. **Phase 3: Deprecation**
-   - Mark file-based approach as legacy
-   - Provide migration guide
-   - Eventually remove legacy support
-
----
-
-## 9. Open Questions (Answered)
-
-1. **Authentication for remote providers** - How do we handle API tokens securely?
-
-   **Answer:** MCP servers handle their own auth - CoreAI doesn't manage credentials separately. For native adapters or other credentials, store in config file. All config files (`.claude/`, `coreai.config.yaml`) must be gitignored.
-
-2. **Offline mode** - Should there be a local cache of shared context for offline work? What's the TTL?
-
-   **Answer:** Yes, local cache at `.coreai/cache/`. Cache until manual refresh - user runs `coreai sync` to update. On first run or empty cache, fetch from remote automatically. Commands: `coreai sync` (refresh), `coreai sync --force` (clear + refresh), `coreai cache clear`.
-
-3. **Shared context updates** - Who can update shared context? Just EM/PM? How do we prevent conflicts when two people update simultaneously?
-
-   **Answer:** No enforcement - CoreAI doesn't restrict who updates what (team process decision). For conflicts, rely on provider - Confluence/Notion have built-in version history and conflict handling. Keep CoreAI simple.
-
-4. **Custom agents** - How do teams add project-specific agents without forking CoreAI?
-
-   **Answer:** Both approaches:
-   - **Local agent directory** - `coreai/agents/` for custom YAML definitions (new roles like Security Reviewer)
-   - **Config-based customization** - `coreai.config.yaml` to extend/override core agents or disable unused ones
-   - **Manual option** - Can also create `.md` files directly in `.claude/agents/` for quick one-offs
-
-5. **Workflow customization** - Should workflows be configurable, or are the 4 current workflows sufficient?
-
-   **Answer:** Fixed workflows for MVP (ticket-implementation, bug-investigation, code-review, planning/estimation). Design architecture to support customization later. Phase 2+ will add workflow customization and custom workflow definitions - teams/clients always have nuances based on their operations.
-
-6. **CI/CD integration** - Should CoreAI run in CI pipelines? How does that change state management?
-
-   **Answer:** No CI/CD support - CoreAI is an interactive developer tool, not an automation tool. PR reviews are delegated so agents behave like human engineers. Ticket/doc changes are delegated or part of skills. Security scans happen via existing pipeline tooling.
-
-7. **Audit trail** - Do we need history of shared context changes? Confluence/Notion have version history built-in.
-
-   **Answer:** No audit trail - rely on provider. Confluence/Notion have built-in version history. CoreAI doesn't duplicate this functionality.
-
-8. **Local state portability** - If an engineer switches machines, how do they handle local agent state? Git commit it? Start fresh?
-
-   **Answer:** Start fresh - local state is ephemeral. Users can manually copy/paste local state files if needed (it's just files). Tooling for export/import can be added later if there's demand.
-
----
-
-## 10. Risks & Mitigations
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| API rate limits on Confluence/Notion | High | Implement caching, batch operations |
-| Network dependency for all operations | High | Offline mode with sync |
-| Configuration complexity | Medium | Sensible defaults, presets, wizard |
-| Breaking changes on updates | Medium | Semantic versioning, migration scripts |
-| Adoption friction | Medium | Maintain CLI simplicity, good docs |
-
----
-
-## 11. Timeline (Rough Estimates)
-
-| Phase | Scope | Notes |
-|-------|-------|-------|
-| **Phase 1** | Core platform, Jira/GitHub/Confluence, basic remote state | Foundation |
-| **Phase 2** | Additional integrations, improved sync | Based on client needs |
-| **Phase 3** | Distribution, updates, enterprise features | Scale |
-
----
-
-## 12. Next Steps
-
-1. [ ] Review and refine this PRD
-2. [ ] Decide on implementation language/runtime
-3. [ ] Design detailed configuration schema
-4. [ ] Prototype Confluence state adapter
-5. [ ] Refactor one agent file to new generic format
-6. [ ] Build minimal CLI that reads config and resolves agent context
-
----
-
-## Appendix A: Current vs Proposed Agent File
-
-### Current Format (agents/examples/backend-engineer.md)
-```markdown
-# Backend Engineer
-
-You are the Backend Engineer for the Surftrack project...
-
-## Context Sources
-Read these files at the start of every task:
-- KnowledgeLibrary/context.txt
-- KnowledgeLibrary/backend-engineer/context/current.txt
-...
-```
-
-### Proposed Format (agents/backend-engineer.yaml)
-```yaml
-role: backend-engineer
-type: ic-engineer
-display_name: Backend Engineer
-
-description: |
-  You are a Backend Engineer responsible for server-side implementation,
-  API development, and backend infrastructure.
-
-responsibilities:
-  - Implement backend features and APIs
-  - Write and maintain unit and integration tests
-  - Perform code reviews when requested
-  - Document technical decisions
-
-context_sources:
-  # REMOTE - fetched from documentation provider at startup
-  shared:
-    - type: remote
-      provider: documentation
-      path: architecture
-    - type: remote
-      provider: documentation
-      path: prd
-    - type: remote
-      provider: documentation
-      path: project-context
-
-  # LOCAL - read from local KnowledgeLibrary (per-engineer)
-  personal:
-    - type: local
-      path: KnowledgeLibrary/${agent.name}/context/current.txt
-    - type: local
-      path: KnowledgeLibrary/${agent.name}/control/objectives.txt
-
-communication:
-  # LOCAL - per-engineer working state
-  inbox: KnowledgeLibrary/${agent.name}/inbox
-  outbox: KnowledgeLibrary/${agent.name}/outbox
-
-quality_gates:
-  required:
-    - lint
-    - test
-  optional:
-    - build
-    - security_scan
-
-workflow: ticket-implementation
-```
-
----
-
-## Appendix B: Example Configuration for Different Project Types
-
-### B.1 Web Application (Node.js + React)
-```yaml
-project:
-  name: "Customer Portal"
-  type: software
-
-integrations:
-  issue_tracker:
-    provider: jira
-    config:
-      project_key: PORTAL
-  git:
-    provider: github
-    config:
-      repo: company/customer-portal
-  documentation:
-    provider: confluence
-    config:
-      space_key: PORTAL
-
-quality_gates:
-  lint:
-    command: "npm run lint"
-  test:
-    command: "npm test"
-  build:
-    command: "npm run build"
-  type_check:
-    command: "npm run typecheck"
-
-tech_stack:
-  primary_language: typescript
-  frameworks: [react, express, prisma]
-```
-
-### B.2 Infrastructure Project (Terraform)
-```yaml
-project:
-  name: "AWS Infrastructure"
-  type: infrastructure
-
-integrations:
-  issue_tracker:
-    provider: jira
-    config:
-      project_key: INFRA
-  git:
-    provider: github
-    config:
-      repo: company/aws-infra
-  documentation:
-    provider: confluence
-    config:
-      space_key: INFRA
-
-quality_gates:
-  format:
-    command: "terraform fmt -check -recursive"
-  validate:
-    command: "terraform validate"
-  security:
-    command: "tfsec ."
-  plan:
-    command: "terraform plan -out=tfplan"
-
-tech_stack:
-  primary_language: hcl
-  frameworks: [terraform, terragrunt]
-  cloud: aws
-```
-
-### B.3 Mobile App (Android/Kotlin)
-```yaml
-project:
-  name: "Mobile App"
-  type: mobile
-
-integrations:
-  issue_tracker:
-    provider: linear
-    config:
-      team_key: MOB
-  git:
-    provider: github
-    config:
-      repo: company/mobile-app
-  documentation:
-    provider: notion
-    config:
-      workspace: company
-      database_id: abc123
-
-quality_gates:
-  lint:
-    command: "./gradlew ktlintCheck"
-  static_analysis:
-    command: "./gradlew detekt"
-  test:
-    command: "./gradlew testDebugUnitTest"
-  build:
-    command: "./gradlew assembleDebug"
-
-tech_stack:
-  primary_language: kotlin
-  frameworks: [android, compose, hilt]
-```
-
----
-
-*End of Document*