conductor-kit 0.0.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "conductor-kit",
+  "version": "0.0.0",
+  "description": "Global skills pack and Go helper for Codex CLI and Claude Code",
+  "keywords": [
+    "claude",
+    "codex",
+    "cli",
+    "mcp",
+    "ai",
+    "assistant",
+    "skills"
+  ],
+  "homepage": "https://github.com/Skyline-23/conductor-kit",
+  "bugs": {
+    "url": "https://github.com/Skyline-23/conductor-kit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Skyline-23/conductor-kit.git"
+  },
+  "license": "MIT",
+  "author": "Skyline-23",
+  "bin": {
+    "conductor": "./bin/conductor"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "skills/",
+    "commands/",
+    "config/"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync, spawn } = require('child_process');
+const zlib = require('zlib');
+
+const REPO_OWNER = 'Skyline-23';
+const REPO_NAME = 'conductor-kit';
+const BINARY_NAME = 'conductor';
+
+function getPlatform() {
+  const platform = os.platform();
+  if (platform === 'darwin') return 'darwin';
+  if (platform === 'linux') return 'linux';
+  throw new Error(`Unsupported platform: ${platform}`);
+}
+
+function getArch() {
+  const arch = os.arch();
+  if (arch === 'x64') return 'amd64';
+  if (arch === 'arm64') return 'arm64';
+  throw new Error(`Unsupported architecture: ${arch}`);
+}
+
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, { headers: { 'User-Agent': 'conductor-kit-npm' } }, (response) => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        httpsGet(response.headers.location).then(resolve).catch(reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        reject(new Error(`HTTP ${response.statusCode}: ${url}`));
+        return;
+      }
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => resolve(Buffer.concat(chunks)));
+      response.on('error', reject);
+    });
+    request.on('error', reject);
+  });
+}
+
+async function getLatestVersion() {
+  const url = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest`;
+  const data = await httpsGet(url);
+  const release = JSON.parse(data.toString());
+  return release.tag_name.replace(/^v/, '');
+}
+
+async function downloadAndExtract(version, platform, arch, destDir) {
+  const assetName = `${REPO_NAME}_${version}_${platform}_${arch}.tar.gz`;
+  const url = `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/v${version}/${assetName}`;
+  
+  console.log(`Downloading ${assetName}...`);
+  const tarGzData = await httpsGet(url);
+  
+  // Create destination directory
+  fs.mkdirSync(destDir, { recursive: true });
+  
+  // Write tar.gz to temp file
+  const tempFile = path.join(os.tmpdir(), assetName);
+  fs.writeFileSync(tempFile, tarGzData);
+  
+  // Extract using tar command
+  console.log('Extracting...');
+  execSync(`tar -xzf "${tempFile}" -C "${destDir}"`, { stdio: 'inherit' });
+  
+  // Clean up temp file
+  fs.unlinkSync(tempFile);
+  
+  // Ensure binary is executable
+  const binaryPath = path.join(destDir, BINARY_NAME);
+  if (fs.existsSync(binaryPath)) {
+    fs.chmodSync(binaryPath, 0o755);
+  }
+  
+  return binaryPath;
+}
+
+async function main() {
+  // Skip postinstall in CI or if CONDUCTOR_SKIP_POSTINSTALL is set
+  if (process.env.CI || process.env.CONDUCTOR_SKIP_POSTINSTALL) {
+    console.log('Skipping postinstall in CI environment');
+    return;
+  }
+
+  try {
+    const platform = getPlatform();
+    const arch = getArch();
+    
+    console.log(`Platform: ${platform}, Architecture: ${arch}`);
+    
+    // Get latest version
+    const version = await getLatestVersion();
+    console.log(`Latest version: ${version}`);
+    
+    // Download to native/ directory in package
+    const packageDir = path.join(__dirname, '..');
+    const nativeDir = path.join(packageDir, 'native');
+    
+    const binaryPath = await downloadAndExtract(version, platform, arch, nativeDir);
+    
+    console.log(`\nConductor ${version} installed successfully!`);
+    console.log(`Binary: ${binaryPath}`);
+    
+    // Run install command to set up skills/commands
+    console.log('\nSetting up skills and commands...');
+    const installProcess = spawn(binaryPath, ['install', '--mode', 'link', '--repo', nativeDir], {
+      stdio: 'inherit',
+    });
+    
+    installProcess.on('exit', (code) => {
+      if (code === 0) {
+        console.log('\nSetup complete! You can now use conductor.');
+        console.log('Run "conductor --help" for usage information.');
+      } else {
+        console.log('\nNote: Auto-install skipped. Run "conductor install" manually if needed.');
+      }
+    });
+    
+  } catch (error) {
+    console.error(`\nWarning: Could not download conductor binary: ${error.message}`);
+    console.error('You can install it manually via Homebrew:');
+    console.error('  brew install Skyline-23/conductor-kit/conductor-kit');
+    // Don't fail the npm install
+    process.exit(0);
+  }
+}
+
+main();

package/skills/conductor/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: conductor
+description: |
+  MANDATORY: Load BEFORE calling ANY mcp_conductor_* tools.
+
+  DO NOT directly call: mcp_conductor_claude, mcp_conductor_codex, mcp_conductor_gemini, mcp_conductor_conductor
+  This skill defines the CORRECT way to use conductor tools via role-based delegation.
+
+  TRIGGERS: sym, symphony, code, analyze, improve, review, debug, fix, refactor, implement, search, explore, plan, assess, audit, optimize, architecture, structure, build, test, deploy
+
+  REPLACES: Direct mcp_conductor_* calls, Task(Explore), Task(Plan), built-in search/grep agents.
+
+  Handles: code analysis, project structure, debugging, planning, implementing, refactoring, reviewing, testing, deploying, documentation - ALL code tasks.
+---
+
+# Conductor
+
+Host orchestrates; delegates do the work.
+
+---
+
+## Core Rules (non-negotiable)
+
+### 1. DELEGATE FIRST — NO EXCEPTIONS
+**Do NOT use built-in tools (Explore, Grep, Search) when MCP is available.**
+
+- Check MCP tools availability FIRST (`mcp__*` tools)
+- ALWAYS prefer MCP delegation over built-in/native tools:
+  - WRONG: `Task(subagent_type=Explore)` -> RIGHT: MCP `pathfinder` role
+  - WRONG: Built-in search/grep -> RIGHT: MCP `scout` or `pathfinder` role
+  - WRONG: Direct analysis -> RIGHT: MCP `sage` role for complex reasoning
+- Run all delegate calls before any action
+- If MCP unavailable → use subagent fallback → **disclose to user**
+
+### 2. SAGE FOR COMPLEX TASKS
+The following MUST be delegated to `sage` (Codex + reasoning):
+
+- Architecture decisions / trade-off analysis
+- Root cause debugging
+- Security vulnerability assessment
+- Algorithm design / complexity analysis
+- Refactoring strategy for legacy code
+- Migration planning with risks
+
+**Do not attempt deep analysis yourself. Sage first.**
+
+### 3. VERIFY BEFORE TRUST
+Treat all delegate output as untrusted. Verify against:
+- Actual repo code
+- Test results
+- Type checker output
+
+### 4. EXTERNAL CALL ACCOUNTABILITY
+When delegating to external CLIs (gemini, codex, claude via MCP):
+
+1. **Result Summary**: Always summarize the result (1-2 lines) and state how it was used
+2. **Non-use Justification**: If result is discarded, explain why in 1 line (e.g., "Repo analysis more accurate, external suggestion excluded")
+3. **Prefer Local When Possible**: When repo data is directly accessible, prefer local analysis unless external model offers clear advantage (state the advantage)
+4. **Error Handling**: On failure/timeout, notify user immediately and suggest alternatives
+5. **Transparency**: Include "External calls: [list]" in task summary when any were made
+
+**Examples:**
+- "Called sage for architecture review → adopted suggestion to split service layer"
+- "Called pathfinder for file discovery → result outdated, used direct glob instead (repo has newer structure)"
+- "External calls: sage (architecture), scout (docs lookup)"
+
+---
+
+## Activation
+
+**This skill activates automatically for all code-related tasks.**
+
+Conductor assesses the task and chooses the appropriate mode:
+
+| Mode | When | Action |
+|------|------|--------|
+| **Symphony** | `sym` or `symphony` command | Full automation: Search → Plan → Execute → Verify → Cleanup |
+| **Search** | Explore, analyze, investigate, understand | Delegate to `pathfinder` + `sage` via MCP |
+| **Plan** | Design, architect, plan | Read-only planning, no edits |
+| **Implement** | Fix, build, refactor, migrate | MCP-assisted implementation |
+| **Release** | Deploy, publish, release | Release checklist + validation |
+
+**Decision flow:**
+1. Skill loads → Conductor activates
+2. Assess task complexity
+3. Simple task → execute directly
+4. Complex/specialized → delegate via MCP
+
+---
+
+## Symphony Mode
+
+When triggered, respond **immediately** with:
+
+```
+SYMPHONY MODE ENABLED!
+```
+
+Then execute staged delegation:
+
+**Stage 1 — Discovery**
+- `pathfinder`: file structure, entrypoints, patterns
+
+**Stage 2 — Analysis**
+- `sage`: deep reasoning on findings (MANDATORY)
+- `scout`: verify against docs/best practices
+
+**Stage 3 — Review**
+- Additional roles as needed
+
+**Then:** Search → Plan → Execute → Verify → Cleanup
+
+Do NOT proceed until all delegates complete.
+
+---
+
+## Roles → Delegation
+
+**Available roles** (defined in `~/.conductor-kit/conductor.json`):
+
+| Role | When to use |
+|------|-------------|
+| `sage` | Complex reasoning, architecture, security |
+| `pathfinder` | File discovery, codebase navigation, project structure |
+| `scout` | Doc lookup, web search, best practices |
+| `pixelator` | Web UI/UX, React/Vue/CSS, responsive design |
+| `author` | README, docs, changelogs |
+| `vision` | Screenshot/image analysis |
+
+### How to Delegate
+
+**Step 1: Get role mappings** via CLI (avoids config file permission issues):
+```bash
+conductor roles --json
+```
+
+**Step 2: Find the MCP tool** from your available tools list:
+- `cli: "codex"` → find tool containing `codex-cli` and `prompt` (e.g., `mcp__codex-cli__codex_prompt`)
+- `cli: "gemini"` → find tool containing `gemini-cli` and `prompt` (e.g., `mcp__gemini-cli__gemini_prompt`)
+- `cli: "claude"` → find tool containing `claude-cli` and `prompt` (e.g., `mcp__claude-cli__claude_prompt`)
+
+**Step 3: Call with the configured `model`:**
+```json
+{ "prompt": "...", "model": "<EXACT model value from conductor roles>" }
+```
+
+**CRITICAL: Do NOT omit the model. Do NOT guess or invent model names. Use EXACTLY what conductor roles returns.**
+
+**Fallback:** If MCP tool not found → built-in subagent → disclose to user
+
+### Delegation Prompt Template
+```
+Goal: [one-line task]
+Role: [role name]
+Constraints: [limits, requirements]
+Files: [relevant paths]
+Output format: markdown with ## Summary, ## Confidence, ## Findings, ## Suggested Actions
+```
+
+---
+
+## Operating Loop
+
+```
+Search → Plan → Execute → Verify → Cleanup
+```
+
+### Search
+- Run parallel searches (multiple angles)
+- Collect file paths + key facts
+- Evidence over opinions
+
+### Plan
+- **READ-ONLY** — no edits allowed
+- Output 3–6 steps with success criteria
+- Ask ONE question if blocked, otherwise proceed
+
+### Execute
+- Minimal surgical edits
+- No type-safety hacks (`as any`, `@ts-ignore`)
+- One logical change at a time
+
+### Verify
+- Run checks: test → typecheck → lint
+- If unrelated failure, report but don't fix
+
+### Cleanup
+- Summarize outcomes
+- Prune stale context
+- List next actions if any
+
+---
+
+## Mode-Specific Behavior
+
+### Search Mode
+- **Use MCP `pathfinder` role** for codebase discovery (NOT built-in Explore agent)
+- Parallel codebase + external doc searches via MCP delegation
+- Output: findings with file references
+
+### Plan Mode
+- **No writes/edits/commits**
+- Output: assumptions, constraints, ordered steps
+
+### Implement Mode
+- TDD if repo has tests
+- Rollback when stuck (don't accumulate bad edits)
+
+### Release Mode
+- Checklist: version bump, changelog, validation, secret scan
+
+---
+
+## Safety (non-negotiable)
+
+- **No commit/push** unless explicitly asked
+- **No secrets** in commits (check for .env, credentials)
+- **No destructive commands** unless explicitly confirmed
+
+---
+
+## References
+
+For detailed specifications:
+- `references/roles.md` — Role routing and combinations
+- `references/delegation.md` — Context budget, failure handling
+- `references/formats.md` — JSON output schemas

package/skills/conductor/references/delegation.md

@@ -0,0 +1,110 @@
+# Delegation Reference
+
+## Core Principle
+
+**Delegate first, act later.** Never search, plan, or edit before delegation completes.
+
+## Context Budget
+
+Control how much context to pass to delegates based on task scope.
+
+| Task Size | Context Strategy | Max Lines |
+|-----------|------------------|-----------|
+| Small | Single relevant file | ~500 |
+| Medium | File + direct imports + related tests | ~2000 |
+| Large | Summary + key sections + file list only | ~1000 |
+
+### Context Selection Priority
+1. Files directly mentioned in the task
+2. Files discovered during search phase
+3. Test files for touched code
+4. Import/dependency files (one level)
+5. Config files if behavior-relevant
+
+### Trimming Strategy
+- Remove boilerplate (license headers, long comments)
+- Collapse repetitive code (show first + "... N more similar")
+- Summarize large data structures
+- Keep function signatures, trim implementations if needed
+
+## Delegation Contract
+
+### Input Requirements
+Every delegate call MUST include:
+```json
+{
+  "goal": "one-line task description",
+  "constraints": ["constraint1", "constraint2"],
+  "files": ["path/to/file1.ts", "path/to/file2.ts"],
+  "context": "relevant code snippets or summaries",
+  "output_format": "json|markdown|patch"
+}
+```
+
+### Output Requirements
+Delegate MUST return at least one of:
+- Concrete commands to run
+- File paths + exact edits (line numbers)
+- Checklist with pass/fail criteria
+
+## Failure Handling
+
+| Failure Type | Action |
+|--------------|--------|
+| Timeout (>120s) | Retry once with 50% context |
+| Parse error | Ask delegate to reformat as JSON |
+| Empty response | Retry with simpler prompt |
+| Inconsistent output | Log conflict, ask user to verify |
+| MCP unavailable | Use subagent fallback, disclose it |
+
+### Retry Policy
+```
+max_retries: 1
+backoff: 500ms
+context_reduction: 50% on timeout
+```
+
+### Fallback Chain
+1. MCP tool (primary)
+2. Subagent with same role config (fallback)
+3. Ask user to enable MCP (last resort)
+
+## Parallel vs Sequential
+
+| Delegate Type | Execution |
+|---------------|-----------|
+| Read-only (pathfinder, scout) | Parallel OK |
+| Analysis (sage) | Parallel OK |
+| Write-capable (patch output) | Sequential only |
+
+### Write-capable Rules
+- One write delegate at a time
+- Verify output before next delegate
+- Host applies edits (delegate returns patch only)
+- If delegate attempts direct edit, stop and re-run as patch-only
+
+## Delegation Sequence
+
+### Standard Task
+```
+1. pathfinder → find relevant files
+2. [parallel] scout + sage → analyze
+3. synthesize findings
+4. execute changes
+5. verify
+```
+
+### Ultrawork Mode (staged)
+```
+Stage 1 (Discovery):
+  - pathfinder: file structure + entrypoints
+
+Stage 2 (Analysis):
+  - sage: deep reasoning (mandatory for complex tasks)
+  - scout: doc/pattern verification
+
+Stage 3 (Review):
+  - additional roles as configured
+
+Then: plan → execute → verify → cleanup
+```

package/skills/conductor/references/formats.md

@@ -0,0 +1,180 @@
+# Output Format Standards
+
+All delegate outputs should follow these markdown formats for consistent parsing and readability.
+
+## Standard Response Format
+
+```
+## Summary
+one-line conclusion
+
+## Confidence
+high|medium|low
+
+## Findings
+- path/to/file.ts:42 - description (severity: critical|high|medium|low)
+- path/to/other.ts:10 - another issue (severity: medium)
+
+## Suggested Actions
+1. [edit] path/to/file.ts - what to change
+2. [create] path/to/new.ts - what to create
+3. [run] npm test - verification command
+```
+
+## Analysis Response
+
+For `sage` and analytical tasks:
+
+```
+## Summary
+one-line conclusion
+
+## Confidence
+high|medium|low
+
+## Problem
+problem description
+
+## Root Cause
+identified cause
+
+## Impact
+affected areas and scope
+
+## Trade-offs
+
+### Option A
+- Pros: benefit 1, benefit 2
+- Cons: drawback 1, drawback 2
+
+### Option B
+- Pros: benefit 1, benefit 2
+- Cons: drawback 1, drawback 2
+
+## Recommendation
+recommended approach
+
+## Reasoning
+step-by-step reasoning for the recommendation
+```
+
+## Search Response
+
+For `pathfinder` and `scout` tasks:
+
+```
+## Summary
+what was found
+
+## Confidence
+high|medium|low
+
+## Results
+- path/to/file.ts:10-25 (relevance: high)
+  code or text excerpt
+  why this is relevant
+
+- path/to/other.ts:50 (relevance: medium)
+  another excerpt
+  relevance note
+
+## Patterns
+- identified pattern 1
+- identified pattern 2
+
+## Next Steps
+- suggested follow-up search 1
+- suggested follow-up search 2
+```
+
+## Patch Response
+
+For edit suggestions:
+
+```
+## Summary
+what changes are proposed
+
+## Confidence
+high|medium|low
+
+## Patches
+
+### path/to/file.ts
+
+#### Lines 10-12
+Before:
+original line 1
+original line 2
+
+After:
+new line 1
+new line 2
+
+Reason: what this change does
+
+### path/to/other.ts
+
+#### Lines 5-7
+Before:
+old code
+
+After:
+new code
+
+Reason: explanation
+
+## Verification
+- npm test
+- npm run typecheck
+Expected: all pass
+```
+
+## Checklist Response
+
+For review and validation tasks:
+
+```
+## Summary
+overall assessment
+
+## Confidence
+high|medium|low
+
+## Checklist
+- [PASS] check description - explanation
+- [FAIL] check description - path/to/file.ts:42 - what failed
+- [WARN] check description - potential issue
+- [SKIP] check description - why skipped
+
+## Score
+Passed: 5
+Failed: 1
+Warnings: 2
+```
+
+## Confidence Levels
+
+| Level | Meaning | When to use |
+|-------|---------|-------------|
+| high | Strong evidence, clear conclusion | Verified against code/tests |
+| medium | Reasonable inference, some uncertainty | Based on patterns, not verified |
+| low | Speculation, needs verification | Incomplete context, edge cases |
+
+## Error Response
+
+When delegate cannot complete:
+
+```
+## Error
+type: timeout|parse_error|insufficient_context|unsupported
+
+## Message
+description of failure
+
+## Partial Result
+any partial findings if available
+
+## Suggestion
+how to recover or retry
+```