Your App (SDK client)
  │  JSON-RPC over stdio
  ▼
Copilot CLI server (auto-spawned or external)
  │  HTTPS
  ▼
GitHub Copilot backend (model routing, tool execution, AI credits)

// In session config:
mcpServers: {
  ruflo: {
    type: "local",           // or "remote"
    command: "npx",
    args: ["-y", "ruflo@latest", "mcp", "start"],
    tools: ["*"],            // or ["memory_store", "memory_search", ...]
    // env?: Record<string, string>
    // cwd?: string
    // timeout?: number (ms)
  }
}

mcpServers: {
  "ruflo-remote": {
    type: "remote",
    url: "https://your-ruflo-mcp.example.com/mcp",
    headers: { Authorization: "Bearer ${RUFLO_MCP_TOKEN}" },
    tools: ["memory_search", "swarm_init"],
  }
}

v3/@claude-flow/copilot/
├── package.json                  # mirrors codex exactly (see 6.2)
├── tsconfig.json                 # same as codex tsconfig
├── vitest.config.ts              # same as codex
├── README.md                     # (only if user requests)
├── AGENTS.md                     # Copilot-flavored AGENTS.md for the package itself
├── src/
│   ├── index.ts                  # mirrors codex/src/index.ts re-export shape
│   ├── types.ts                  # all Copilot-specific types (mirrors codex types.ts)
│   ├── initializer.ts            # CopilotInitializer + initializeCopilotProject
│   ├── cli.ts                    # claude-flow-copilot bin entry (mirrors codex cli.ts)
│   │
│   ├── client/                   # NEW vs codex — wraps @github/copilot-sdk
│   │   ├── auth.ts               # credential resolution + token cache
│   │   ├── chat.ts               # chat completion with streaming
│   │   ├── tools.ts              # tool/function calling adapter
│   │   └── models.ts             # model catalog + tier mapping + getOptimalModel()
│   │
│   ├── mcp/                      # NEW vs codex — bidirectional MCP bridge
│   │   ├── register.ts           # registers ruflo MCP server WITH Copilot SDK session
│   │   └── bridge.ts             # bridges Copilot MCP tool calls → ruflo MCP tools
│   │
│   ├── dual-mode/                # extends DualModeOrchestrator to tri-mode
│   │   ├── index.ts              # re-exports + MultiModeWorkerConfig
│   │   └── cli.ts                # `claude-flow-copilot dual` subcommand
│   │
│   ├── loop/                     # /loop runner for Copilot platform
│   │   ├── index.ts              # runCopilotLoop() — mirrors runCodexLoop()
│   │   └── cli.ts                # loop subcommand
│   │
│   ├── generators/
│   │   ├── agents-md.ts          # Copilot-flavored AGENTS.md (no $skill syntax needed)
│   │   ├── config-toml.ts        # Copilot config (model defaults, permission handler)
│   │   └── skill-md.ts           # mirrors codex skill-md.ts
│   │
│   ├── templates/
│   │   └── index.ts              # mirrors codex templates/index.ts
│   │
│   ├── migrations/
│   │   └── index.ts              # migrateFromClaudeCode + migrateFromCodex (new)
│   │
│   └── validators/
│       └── index.ts              # validateAgentsMd, validateSkillMd, validateConfig
│
└── tests/
    ├── client/                   # mock @github/copilot-sdk
    ├── mcp/                      # mock ruflo MCP server
    ├── dual-mode/                # multi-mode orchestrator integration
    └── e2e/                      # gated behind COPILOT_E2E=1

{
  "name": "@claude-flow/copilot",
  "version": "3.8.0",
  "description": "GitHub Copilot SDK integration for RuFlo (claude-flow) — Copilot platform adapter",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "bin": {
    "claude-flow-copilot": "./dist/cli.js"
  },
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.js",
      "default": "./dist/index.js"
    },
    "./client": {
      "types": "./dist/client/index.d.ts",
      "import": "./dist/client/index.js",
      "require": "./dist/client/index.js"
    },
    "./mcp": {
      "types": "./dist/mcp/index.d.ts",
      "import": "./dist/mcp/index.js",
      "require": "./dist/mcp/index.js"
    },
    "./generators": {
      "types": "./dist/generators/index.d.ts",
      "import": "./dist/generators/index.js",
      "require": "./dist/generators/index.js"
    },
    "./templates": {
      "types": "./dist/templates/index.d.ts",
      "import": "./dist/templates/index.js",
      "require": "./dist/templates/index.js"
    },
    "./migrations": {
      "types": "./dist/migrations/index.d.ts",
      "import": "./dist/migrations/index.js",
      "require": "./dist/migrations/index.js"
    },
    "./dual-mode": {
      "types": "./dist/dual-mode/index.d.ts",
      "import": "./dist/dual-mode/index.js",
      "require": "./dist/dual-mode/index.js"
    },
    "./loop": {
      "types": "./dist/loop/index.d.ts",
      "import": "./dist/loop/index.js",
      "require": "./dist/loop/index.js"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "lint": "eslint src --ext .ts",
    "test": "vitest",
    "prepublishOnly": "npm run build"
  },
  "keywords": ["copilot", "github", "claude-flow", "ruflo", "agents", "skills", "AGENTS.md", "agentic-ai"],
  "author": "rUv",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/ruvnet/ruflo.git",
    "directory": "v3/@claude-flow/copilot"
  },
  "homepage": "https://github.com/ruvnet/ruflo#readme",
  "bugs": { "url": "https://github.com/ruvnet/ruflo/issues" },
  "engines": { "node": ">=20" },
  "dependencies": {
    "@github/copilot-sdk": "^1.0.0",
    "commander": "^12.0.0",
    "fs-extra": "^11.2.0",
    "chalk": "^5.3.0",
    "inquirer": "^9.2.0",
    "yaml": "^2.4.0",
    "toml": "^3.0.0",
    "@iarna/toml": "^2.2.5"
  },
  "peerDependencies": {
    "@claude-flow/cli": "^3.0.0",
    "@claude-flow/guidance": "^3.0.0"
  },
  "peerDependenciesMeta": {
    "@claude-flow/cli": { "optional": true },
    "@claude-flow/guidance": { "optional": true }
  },
  "devDependencies": {
    "@types/fs-extra": "^11.0.4",
    "@types/node": "^20.0.0",
    "typescript": "^5.4.0",
    "vitest": "^4.0.16",
    "eslint": "^8.57.0"
  }
}

/**
 * @claude-flow/copilot
 *
 * GitHub Copilot SDK platform adapter for Claude Flow / RuFlo
 * Third platform in the tri-mode collaboration system (Claude + Codex + Copilot)
 */

// Re-export all types
export * from './types.js';

// Re-export generators
export {
  generateAgentsMd,
  generateSkillMd,
  generateConfigToml,
} from './generators/index.js';

// Re-export migrations
export {
  migrateFromClaudeCode,
  migrateFromCodex,
  analyzeClaudeMd,
  generateMigrationReport,
  convertSkillSyntax,
  convertSettingsToConfig,
  FEATURE_MAPPINGS,
  CODEX_TO_COPILOT_MAPPINGS,
} from './migrations/index.js';

// Re-export validators
export {
  validateAgentsMd,
  validateSkillMd,
  validateConfig,
} from './validators/index.js';

// Main initializer
export { CopilotInitializer, initializeCopilotProject } from './initializer.js';

// Copilot client (wraps @github/copilot-sdk)
export { CopilotClient, createCopilotClient } from './client/chat.js';
export { resolveCredential, getCachedToken, clearCachedToken } from './client/auth.js';
export { getOptimalModel, COPILOT_MODEL_CATALOG, TIER_DEFAULTS } from './client/models.js';
export { defineCopilotTool, CopilotToolRegistry } from './client/tools.js';
export type {
  CopilotClientConfig,
  CopilotSession,
  CopilotMessage,
  StreamEvent,
  CopilotTool,
} from './client/chat.js';

// MCP bridge (bidirectional)
export {
  registerRufloMcpWithCopilot,
  CopilotMcpBridge,
} from './mcp/register.js';
export type { RufloMcpServerConfig, CopilotMcpSession } from './mcp/register.js';

// Tri-mode collaboration (extends DualModeOrchestrator)
export {
  MultiModeOrchestrator,
  TriModeCollaborationTemplates,
  createMultiModeCommand,
} from './dual-mode/index.js';
export type {
  MultiModeConfig,
  MultiModeWorkerConfig,
  MultiModeWorkerResult,
  CollaborationResult,
} from './dual-mode/index.js';

// /loop runner
export {
  buildCopilotLoopPrompt,
  loadLoopState,
  normalizeLoopName,
  requestLoopStop,
  resolveLoopPaths,
  runCopilotLoop,
} from './loop/index.js';
export { createLoopCommand } from './loop/cli.js';
export type {
  LoopCommandResult,
  LoopEvent,
  LoopPaths,
  LoopRunOptions,
  LoopState,
} from './loop/index.js';

// Template utilities (mirrors codex)
export {
  getTemplate,
  listTemplates,
  BUILT_IN_SKILLS,
  TEMPLATES,
  DEFAULT_SKILLS_BY_TEMPLATE,
  DIRECTORY_STRUCTURE,
  PLATFORM_MAPPING,
  GITIGNORE_ENTRIES,
  AGENTS_OVERRIDE_TEMPLATE,
} from './templates/index.js';

export const VERSION = '3.8.0';

export const PACKAGE_INFO = {
  name: '@claude-flow/copilot',
  version: VERSION,
  description: 'GitHub Copilot SDK integration for Claude Flow / RuFlo',
  platform: 'copilot',
  repository: 'https://github.com/ruvnet/ruflo',
} as const;

export default { VERSION, PACKAGE_INFO };

// In @claude-flow/codex/src/dual-mode/orchestrator.ts (existing):
 export interface WorkerConfig {
   id: string;
-  platform: 'claude' | 'codex';
+  platform: 'claude' | 'codex' | 'copilot';  // ← ADD copilot
   role: string;
   prompt: string;
   model?: string;
   ...
 }

// src/dual-mode/index.ts in @claude-flow/copilot:
import { DualModeOrchestrator, WorkerConfig as BaseWorkerConfig } from '@claude-flow/codex/dual-mode';

export interface MultiModeWorkerConfig extends Omit<BaseWorkerConfig, 'platform'> {
  platform: 'claude' | 'codex' | 'copilot';
  copilotModel?: string;   // e.g. 'gpt-5.3-codex' | 'gpt-5.5'
  copilotOptions?: {
    permissionHandler?: 'approve-all' | 'deny-all' | 'custom';
    streaming?: boolean;
    mcpServers?: Record<string, unknown>;
  };
}

export class MultiModeOrchestrator extends DualModeOrchestrator {
  protected async executeHeadless(config: MultiModeWorkerConfig): Promise<string> {
    if (config.platform === 'copilot') {
      return this.executeCopilotHeadless(config);
    }
    return super.executeHeadless(config as BaseWorkerConfig);
  }

  private async executeCopilotHeadless(config: MultiModeWorkerConfig): Promise<string> {
    const { CopilotClient } = await import('../client/chat.js');
    const { getOptimalModel } = await import('../client/models.js');
    const { registerRufloMcpWithCopilot } = await import('../mcp/register.js');
    const { GuidanceControlPlane } = await import('@claude-flow/guidance');

    const guidance = new GuidanceControlPlane();
    await guidance.initialize();

    const prompt = this.buildCollaborativePrompt(config);
    const compiled = await guidance.compile(prompt);

    const client = new CopilotClient();
    const session = await client.createSession({
      model: config.copilotModel ?? getOptimalModel('Tier3'),
      streaming: config.copilotOptions?.streaming ?? false,
      mcpServers: await registerRufloMcpWithCopilot(this.config.projectPath),
    });

    const result = await session.sendAndWait({ prompt: compiled.policyText + '\n\n' + prompt });
    await session.disconnect();
    await client.stop();

    await guidance.finalizeRun(guidance.startRun(config.id, 'feature'));
    return result.content ?? '';
  }
}

// TriModeCollaborationTemplates in src/dual-mode/index.ts:
export const TriModeCollaborationTemplates = {
  featureDevelopment: (feature: string): MultiModeWorkerConfig[] => [
    {
      id: 'architect',
      platform: 'claude',          // 🔵 Claude: architecture reasoning
      role: 'architect',
      prompt: `Design the architecture for: ${feature}. Define components, interfaces, data flow.`,
      maxTurns: 10,
    },
    {
      id: 'coder',
      platform: 'codex',           // 🟢 Codex: bulk implementation
      role: 'coder',
      prompt: `Implement the feature based on the architecture. Write clean, typed code.`,
      dependsOn: ['architect'],
      maxTurns: 15,
    },
    {
      id: 'reviewer',
      platform: 'copilot',         // 🟠 Copilot (GPT-5.3-Codex): code review
      role: 'reviewer',
      prompt: `Review the code and tests for quality, security, and best practices.`,
      dependsOn: ['coder'],
      copilotModel: 'gpt-5.3-codex',
    },
    {
      id: 'tester',
      platform: 'claude',          // 🔵 Claude: test strategy
      role: 'tester',
      prompt: `Write comprehensive tests. Target 80% coverage.`,
      dependsOn: ['reviewer'],
      maxTurns: 10,
    },
  ],

  securityAudit: (target: string): MultiModeWorkerConfig[] => [
    {
      id: 'scanner',
      platform: 'copilot',         // 🟠 Copilot GPT-5.5: deep security analysis
      role: 'security-scanner',
      prompt: `Scan ${target} for security vulnerabilities. Check OWASP Top 10.`,
      copilotModel: 'gpt-5.5',    // frontier model for security reasoning
      copilotOptions: { streaming: false },
    },
    {
      id: 'fixer',
      platform: 'codex',           // 🟢 Codex: generate fixes
      role: 'security-fixer',
      prompt: `Generate fixes for identified vulnerabilities.`,
      dependsOn: ['scanner'],
      maxTurns: 12,
    },
  ],
};

// In CopilotClient.runGoverned() (src/client/chat.ts):
async runGoverned(prompt: string, taskId: string): Promise<string> {
  // 1. pre-task hook (same as codex/claude adapters)
  await execa('npx', ['@claude-flow/cli@latest', 'hooks', 'pre-task',
    '--description', prompt, '--coordinate-swarm']);

  // 2. route hook — get model recommendation
  const routeResult = await execa('npx', ['@claude-flow/cli@latest', 'hooks', 'route',
    '--task', prompt, '--context', 'copilot']);
  const model = extractModelFromRoute(routeResult.stdout) ?? TIER_DEFAULTS.tier3;

  // 3. guidance compile
  const guidance = await initializeGuidanceControlPlane();
  const { policyText } = await guidance.retrieveForTask({ taskDescription: prompt });

  // 4. Copilot call (with governance-compiled prompt)
  const result = await this.session.sendAndWait({
    prompt: `${policyText}\n\n---\n\n${prompt}`
  });

  // 5. post-task hook (learning + cost tracking)
  await execa('npx', ['@claude-flow/cli@latest', 'hooks', 'post-task',
    '--task-id', taskId, '--success', 'true', '--store-results', 'true']);

  // 6. finalize governance proof
  const event = guidance.startRun(taskId, 'feature');
  await guidance.finalizeRun(event);

  return result.content ?? '';
}

export const COPILOT_MODEL_CATALOG = {
  'gpt-5.3-codex': { tier: 3, multiplier: 1.0,  category: 'coding-lts',   ltsUntil: '2027-02-04' },
  'gpt-5.4-mini':  { tier: 2, multiplier: 0.33, category: 'fast',         ltsUntil: null },
  'gpt-5.5':       { tier: 3, multiplier: 7.5,  category: 'frontier',     ltsUntil: null },
  // Runtime-authoritative list via client.listModels()
} as const;

export const TIER_DEFAULTS = {
  tier2: 'gpt-5.4-mini',
  tier3: 'gpt-5.3-codex',
  tier3Reasoning: 'gpt-5.5',
} as const;

/**
 * Select the optimal Copilot model for a given task complexity score.
 * complexity: 0-100 where 0=trivial codemod, 100=frontier reasoning
 */
export function getOptimalModel(
  complexityOrTier: number | 'Tier2' | 'Tier3' | 'Tier3Reasoning',
  allowFrontier = false
): string {
  if (typeof complexityOrTier === 'string') {
    if (complexityOrTier === 'Tier2') return TIER_DEFAULTS.tier2;
    if (complexityOrTier === 'Tier3Reasoning' && allowFrontier) return TIER_DEFAULTS.tier3Reasoning;
    return TIER_DEFAULTS.tier3;
  }
  const c = complexityOrTier;
  if (c < 30) return TIER_DEFAULTS.tier2;
  if (c >= 80 && allowFrontier) return TIER_DEFAULTS.tier3Reasoning;
  return TIER_DEFAULTS.tier3;
}

import { TokenCache } from '@claude-flow/security';  // existing module

export async function resolveCredential(): Promise<string | null> {
  // 1. Check environment (COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN) — SDK picks these up natively
  // 2. Verify CLI is authenticated
  const { execa } = await import('execa');
  try {
    await execa('gh', ['auth', 'status'], { stdio: 'pipe' });
    return 'gh-auth';  // CLI is authenticated; SDK will use stored credential
  } catch {
    return null;  // Not authenticated — surface error to user
  }
}

// NEVER echo the token. NEVER write it to a file.
// The SDK reads credentials itself; auth.ts only VERIFIES that auth state exists.
export async function getCachedToken(): Promise<string | null> {
  // TokenCache from @claude-flow/security stores opaque handles, not raw tokens
  return TokenCache.get('copilot-auth-status');
}

export async function clearCachedToken(): Promise<void> {
  return TokenCache.clear('copilot-auth-status');
}

// src/mcp/register.ts
import { CopilotClient } from '@github/copilot-sdk';

export interface RufloMcpServerConfig {
  type: 'local';
  command: 'npx';
  args: ['-y', 'ruflo@latest', 'mcp', 'start'];
  tools: ['*'];  // expose all ruflo MCP tools to Copilot
  env?: Record<string, string>;
}

export async function registerRufloMcpWithCopilot(
  projectPath: string,
  toolFilter: string[] | '*' = '*'
): Promise<Record<string, RufloMcpServerConfig>> {
  return {
    ruflo: {
      type: 'local',
      command: 'npx',
      args: ['-y', 'ruflo@latest', 'mcp', 'start'],
      tools: toolFilter === '*' ? ['*'] : toolFilter,
      env: { CLAUDE_FLOW_CONFIG: `${projectPath}/claude-flow.config.json` },
    }
  };
}

const session = await client.createSession({
  model: 'gpt-5.3-codex',
  mcpServers: await registerRufloMcpWithCopilot(process.cwd()),
});

tests/
├── client/
│   ├── auth.test.ts          # mock gh CLI + env vars; test resolveCredential()
│   ├── chat.test.ts          # mock @github/copilot-sdk CopilotClient; test streaming + non-streaming
│   ├── models.test.ts        # unit test getOptimalModel() at complexity boundaries
│   └── tools.test.ts         # test tool registration shape against SDK contract
│
├── mcp/
│   ├── register.test.ts      # verify RufloMcpServerConfig shape is valid SDK input
│   └── bridge.test.ts        # mock ruflo MCP server; test tool call routing
│
├── dual-mode/
│   └── orchestrator.test.ts  # mock claude + codex + copilot workers; test dependency levels
│
├── generators/
│   ├── agents-md.test.ts     # snapshot tests for generated AGENTS.md
│   └── config-toml.test.ts   # snapshot tests for generated config
│
├── migrations/
│   └── migration.test.ts     # test migrateFromClaudeCode + migrateFromCodex
│
└── e2e/
    └── copilot-session.test.ts  # COPILOT_E2E=1 required; real SDK call; costs AI credits

// tests/__mocks__/@github/copilot-sdk.ts
export class CopilotClient {
  async createSession() {
    return {
      sendAndWait: async ({ prompt }: { prompt: string }) => ({
        content: `Mock Copilot response to: ${prompt.slice(0, 50)}`,
        model: 'gpt-5.3-codex',
      }),
      disconnect: async () => {},
    };
  }
  async stop() {}
}

// tests/e2e/copilot-session.test.ts
const runE2E = process.env.COPILOT_E2E === '1';
(runE2E ? it : it.skip)('sends a real prompt to Copilot', async () => { ... });

# STEP 1: Build and publish @claude-flow/copilot (new package, first publish)
cd v3/@claude-flow/copilot
npm version 3.8.0 --no-git-tag-version
npm run build
npm publish                                       # default tag is latest
npm dist-tag add @claude-flow/[email protected] alpha
npm dist-tag add @claude-flow/[email protected] v3alpha

# STEP 2: Bump umbrella claude-flow (add @claude-flow/copilot as optional dep)
cd /Users/cohen/Projects/ruflo
# Edit package.json: add "@claude-flow/copilot": "^3.8.0" to optionalDependencies
npm version 3.8.0 --no-git-tag-version
npm publish
npm dist-tag add [email protected] alpha
npm dist-tag add [email protected] v3alpha

# STEP 3: Bump ruflo wrapper
cd ruflo
npm version 3.8.0 --no-git-tag-version
# Edit package.json: add "@claude-flow/copilot" to optionalDependencies and overrides
npm publish
npm dist-tag add [email protected] alpha
npm dist-tag add [email protected] v3alpha

for pkg in @claude-flow/copilot @claude-flow/cli claude-flow ruflo; do
  echo "$pkg: $(npm view $pkg@latest version)"
  npm view $pkg dist-tags --json
done
# All packages: latest === alpha === v3alpha === new version

git tag v3.8.0 main
git push origin v3.8.0
gh release create v3.8.0 --title "v3.8.0 — @claude-flow/copilot: GitHub Copilot SDK integration + tri-mode collaboration"

export async function migrateFromCodex(options: MigrationOptions): Promise<MigrationResult> {
  // 1. Read .agents/config.toml
  // 2. Parse TOML model, approval_policy, sandbox_mode, mcp_servers, skills
  // 3. Generate .copilot/config.json with Copilot SDK equivalents
  // 4. For each [skills] entry: generate a CopilotTool registration stub
  // 5. Convert $skill-name references in AGENTS.md to MCP tool call comments
  // 6. Migrate .codex/loop/ state dir to .copilot/loop/ (mode: 'copilot')
  // 7. Return warnings for: sandbox_mode (no direct equiv), approval_policy differences
}