linear-ai-build 1.0.0

package/.env.example

@@ -0,0 +1,3 @@
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+LINEAR_API_KEY=lin_api_your-key-here
+LINEAR_TEAM_ID=your-team-id-here

package/README.md

@@ -0,0 +1,220 @@
+# Linear AI Build
+
+Generate user stories from feature descriptions, push them to Linear, then have AI agents build the code — all from Claude Code.
+
+## What It Does
+
+1. **Generates stories** — Asks clarifying questions, creates a PRD with user stories, acceptance criteria, and tasks
+2. **Pushes to Linear** — Creates a project with parent issues (stories) and child issues (tasks), labels, and priorities
+3. **Builds from Linear** — Pulls labeled stories back from Linear and orchestrates Claude Flow agents to plan, implement, test, and review the code
+
+## Quick Start
+
+### Install
+
+```bash
+git clone <your-repo>
+cd linear-ai-build
+npm install
+```
+
+### Configure
+
+```bash
+npm run init
+```
+
+This will:
+1. Ask for your **Linear API key** (from Linear Settings > Security & Access > Personal API keys)
+2. Ask for your **Anthropic API key** (optional — only needed for standalone CLI)
+3. Ask for your **default Linear team ID** (optional)
+4. Write a `.env` file with your credentials
+5. Configure the **Linear MCP server** for Claude Code (`.mcp.json`)
+6. Install the **Claude Code commands**
+
+### Prerequisites for Building
+
+Install Claude Flow globally:
+
+```bash
+npm install -g claude-flow@alpha
+```
+
+## Usage
+
+### Generate Stories
+
+Create stories and tasks in Linear from a feature description.
+
+**CLI:**
+
+```bash
+npm run generate -- "Add user authentication with OAuth" TEAM-abc123
+```
+
+**Claude Code:**
+
+```
+/linear:generate-stories "Add user authentication with OAuth" TEAM-abc123
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--dry-run` | Preview the generated PRD without creating anything in Linear |
+| `--cycle <id>` | Assign issues to a specific cycle (defaults to active cycle) |
+| `--assignee <id>` | Assign issues to a specific user (defaults to you) |
+| `--no-cycle` | Skip cycle assignment |
+| `--no-assignee` | Skip assignee assignment |
+| `--skip-questions` | Skip clarifying questions, generate PRD directly |
+
+### Build From Linear
+
+Pull labeled stories from Linear and have Claude Flow agents implement the code.
+
+**Claude Code:**
+
+```
+/linear:build-from-linear
+/linear:build-from-linear WIC-42
+/linear:build-from-linear --label ai-build
+```
+
+This command:
+1. Uses **Linear MCP** to fetch stories with the `ai-build` label (or a specific issue)
+2. Fetches child tasks and acceptance criteria for each story
+3. Asks you to confirm which issues to process
+4. Uses **Claude Flow MCP** to orchestrate agents:
+   - **Planner** — analyzes the story and creates an implementation plan
+   - **Implementers** — build each task in parallel
+   - **Tester** — writes and runs tests against acceptance criteria
+   - **Reviewer** — reviews all changes, fixes issues
+5. Creates a git branch per story (`linear/<issue-identifier>`)
+6. Updates Linear with progress comments and moves issues to "In Review"
+
+### Watch Mode (CLI)
+
+Alternatively, poll Linear and auto-process issues without Claude Code:
+
+```bash
+npm run watch
+```
+
+Or process a single issue:
+
+```bash
+npm run build:issue -- WIC-42
+```
+
+## How It Works
+
+```
+Feature Description
+        |
+        v
+  /linear:generate-stories
+        |
+        v
+  Linear (stories + tasks created)
+        |
+  Label with "ai-build"
+        |
+        v
+  /linear:build-from-linear
+        |
+        v
+  Claude Flow Agents
+    Plan → Implement → Test → Review
+        |
+        v
+  Git branch + PR ready
+  Linear issues moved to "In Review"
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `LINEAR_API_KEY` | Yes | Linear API key |
+| `LINEAR_TEAM_ID` | Yes | Default team ID or key (e.g., `WIC`) |
+| `ANTHROPIC_API_KEY` | For CLI | Anthropic API key (not needed for Claude Code plugin) |
+| `TARGET_REPO_PATH` | No | Where agents write code (default: current directory) |
+| `TARGET_BRANCH` | No | Base branch for new branches (default: `main`) |
+| `POLL_INTERVAL_MS` | No | Watch mode polling interval (default: `30000`) |
+| `AI_BUILD_LABEL` | No | Linear label to watch for (default: `ai-build`) |
+
+## MCP Servers
+
+Configured in `.mcp.json`:
+
+| Server | Purpose |
+|---|---|
+| `linear` | Linear API — fetch/create/update issues, comments, projects |
+| `claude-flow` | Claude Flow — agent swarm orchestration, task management |
+
+## Project Structure
+
+```
+linear-ai-build/
+  bin/
+    cli.ts                  # CLI entry point (init, generate, watch, build)
+    init.ts                 # Interactive setup
+  commands/
+    generate-stories.md     # /linear:generate-stories command
+    build-from-linear.md    # /linear:build-from-linear command
+  src/
+    generate-sdk.ts         # PRD generation + Linear SDK integration
+    index.ts                # MCP-based alternative
+    bridge/
+      index.ts              # Watch/build entry point
+      watcher.ts            # Linear polling loop
+      executor.ts           # Claude Flow workflow executor
+      transformer.ts        # Issue → workflow builder
+      reporter.ts           # Linear status updates
+      linear-helpers.ts     # Shared Linear SDK helpers
+      config.ts             # Bridge configuration
+      state.ts              # Deduplication tracking
+      types.ts              # TypeScript types
+  .env.example
+  .mcp.json                 # MCP server config (Linear + Claude Flow)
+  package.json
+  tsconfig.json
+```
+
+## Troubleshooting
+
+### "Missing LINEAR_API_KEY environment variable"
+
+Make sure `.env` exists and contains your key, or export it directly:
+
+```bash
+export LINEAR_API_KEY=lin_api_...
+```
+
+### "Team ID not found"
+
+Verify your team ID:
+
+```bash
+curl -X POST https://api.linear.app/graphql \
+  -H "Authorization: lin_api_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ viewer { teams { nodes { id name key } } } }"}'
+```
+
+### Claude Flow MCP not connecting
+
+Re-register the MCP server:
+
+```bash
+claude mcp add claude-flow -- npx -y claude-flow@alpha mcp start
+```
+
+### "Failed to parse PRD JSON after retry"
+
+Claude occasionally produces unparseable output. Try running again or simplifying the feature description.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { execFileSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Use tsx to run the TypeScript CLI
+const tsxBin = join(__dirname, '..', 'node_modules', '.bin', 'tsx');
+const cliTs = join(__dirname, 'cli.ts');
+
+try {
+  execFileSync(tsxBin, [cliTs, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+} catch (err) {
+  // execFileSync throws on non-zero exit — just propagate the exit code
+  process.exit(err.status || 1);
+}

package/bin/cli.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env npx tsx
+const command = process.argv[2];
+
+switch (command) {
+  case 'init':
+    import('./init.ts');
+    break;
+  case 'generate':
+    // Forward remaining args to generate-sdk
+    process.argv = [process.argv[0], process.argv[1], ...process.argv.slice(3)];
+    import('../src/generate-sdk.ts');
+    break;
+  case 'watch':
+    import('../src/bridge/index.ts').then(m => m.watch());
+    break;
+  case 'build': {
+    const issueId = process.argv[3];
+    if (!issueId) {
+      console.error('Usage: linear-ai-build build <issue-identifier>');
+      console.error('Example: linear-ai-build build WIC-42');
+      process.exit(1);
+    }
+    import('../src/bridge/index.ts').then(m => m.build(issueId));
+    break;
+  }
+  default:
+    console.log(`linear-ai-build - Generate user stories and build with AI agents
+
+Commands:
+  init       Interactive setup — credentials, MCP config, Claude Code command
+  generate   Generate stories and push to Linear (standalone mode)
+  watch      Watch Linear for ai-build issues and process with Claude Flow
+  build      One-shot: process a specific Linear issue with Claude Flow
+
+Usage:
+  npx linear-ai-build init
+  npx linear-ai-build generate "Add auth" TEAM-abc123
+  npx linear-ai-build watch
+  npx linear-ai-build build WIC-42
+
+After running init, use the Claude Code command:
+  /linear:generate-stories "Add user authentication" TEAM-abc123
+
+Environment variables for bridge:
+  TARGET_REPO_PATH   Path to the repo where agents write code (default: cwd)
+  TARGET_BRANCH      Base branch for new branches (default: main)
+  POLL_INTERVAL_MS   Polling interval in ms (default: 30000)
+  AI_BUILD_LABEL     Linear label to watch for (default: ai-build)
+`);
+    break;
+}

package/bin/init.ts

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as readline from 'readline';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const COMMAND_DIR = 'linear';
+const COMMAND_FILE = 'generate-stories.md';
+
+// --- Interactive Prompts ---
+
+function prompt(question: string, defaultValue = ''): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const suffix = defaultValue ? ` [${defaultValue}]` : '';
+  return new Promise(resolve => {
+    rl.question(`${question}${suffix}: `, answer => {
+      rl.close();
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+function promptSecret(question: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    // Note: readline doesn't natively hide input, but we inform the user
+    rl.question(`${question}: `, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// --- Credential Collection ---
+
+async function collectCredentials(): Promise<{
+  linearApiKey: string;
+  anthropicApiKey: string;
+  teamId: string;
+}> {
+  console.log('\nLinear AI Build - Setup\n');
+  console.log('This will configure the tool for CLI use and install the Claude Code plugin.\n');
+
+  // Check for existing .env
+  const envFile = path.resolve(process.cwd(), '.env');
+  const existing = loadExistingEnv(envFile);
+
+  // Linear API Key
+  console.log('1. Linear API Key');
+  console.log('   Get yours at: Linear Settings > Security & Access > Personal API keys');
+  let linearApiKey = existing.LINEAR_API_KEY || '';
+  if (linearApiKey) {
+    const masked = linearApiKey.slice(0, 8) + '...' + linearApiKey.slice(-4);
+    const keep = await prompt(`   Found existing key (${masked}). Keep it? (y/n)`, 'y');
+    if (keep.toLowerCase() !== 'y') {
+      linearApiKey = await promptSecret('   Enter your Linear API key');
+    }
+  } else {
+    linearApiKey = await promptSecret('   Enter your Linear API key');
+  }
+
+  if (!linearApiKey) {
+    console.error('\n   Linear API key is required. Aborting.');
+    process.exit(1);
+  }
+
+  // Anthropic API Key (optional — only needed for standalone CLI, not the Claude Code plugin)
+  console.log('\n2. Anthropic API Key (optional — only needed for standalone CLI)');
+  console.log('   Get yours at: https://console.anthropic.com/ > API Keys');
+  console.log('   Skip this if you only plan to use the Claude Code plugin.');
+  let anthropicApiKey = existing.ANTHROPIC_API_KEY || '';
+  if (anthropicApiKey) {
+    const masked = anthropicApiKey.slice(0, 8) + '...' + anthropicApiKey.slice(-4);
+    const keep = await prompt(`   Found existing key (${masked}). Keep it? (y/n)`, 'y');
+    if (keep.toLowerCase() !== 'y') {
+      anthropicApiKey = await promptSecret('   Enter your Anthropic API key (or press Enter to skip)');
+    }
+  } else {
+    anthropicApiKey = await promptSecret('   Enter your Anthropic API key (or press Enter to skip)');
+  }
+
+  // Team ID
+  console.log('\n3. Default Linear Team ID');
+  console.log('   Find it in the URL: https://linear.app/YOUR-WORKSPACE/...');
+  console.log('   Or query it with: curl -X POST https://api.linear.app/graphql \\');
+  console.log('     -H "Authorization: <your-key>" -H "Content-Type: application/json" \\');
+  console.log('     -d \'{"query": "{ viewer { teams { nodes { id name } } } }"}\'');
+  let teamId = existing.LINEAR_TEAM_ID || '';
+  if (teamId) {
+    teamId = await prompt(`   Default team ID`, teamId);
+  } else {
+    teamId = await prompt('   Default team ID (optional, can pass per-command)');
+  }
+
+  return { linearApiKey, anthropicApiKey, teamId };
+}
+
+function loadExistingEnv(envPath: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!fs.existsSync(envPath)) return result;
+
+  const content = fs.readFileSync(envPath, 'utf-8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const value = trimmed.slice(eqIdx + 1).trim();
+    result[key] = value;
+  }
+  return result;
+}
+
+// --- .env File ---
+
+function writeEnvFile(credentials: { linearApiKey: string; anthropicApiKey: string; teamId: string }) {
+  const envPath = path.resolve(process.cwd(), '.env');
+  const existing = loadExistingEnv(envPath);
+
+  // Merge with existing values (preserve any extra keys)
+  existing.LINEAR_API_KEY = credentials.linearApiKey;
+  if (credentials.anthropicApiKey) {
+    existing.ANTHROPIC_API_KEY = credentials.anthropicApiKey;
+  }
+  if (credentials.teamId) {
+    existing.LINEAR_TEAM_ID = credentials.teamId;
+  }
+
+  const lines: string[] = [];
+  for (const [key, value] of Object.entries(existing)) {
+    lines.push(`${key}=${value}`);
+  }
+
+  fs.writeFileSync(envPath, lines.join('\n') + '\n');
+  console.log(`\n   Saved: ${envPath}`);
+}
+
+// --- Claude Code MCP Configuration ---
+
+function configureLinearMcp(linearApiKey: string) {
+  const claudeDir = path.join(os.homedir(), '.claude');
+
+  // Write MCP config to project-level .mcp.json
+  // This configures the Linear MCP server so Claude Code can talk to Linear directly
+  const mcpConfigPath = path.resolve(process.cwd(), '.mcp.json');
+  let mcpConfig: Record<string, any> = {};
+
+  if (fs.existsSync(mcpConfigPath)) {
+    try {
+      mcpConfig = JSON.parse(fs.readFileSync(mcpConfigPath, 'utf-8'));
+    } catch {
+      // Start fresh if corrupted
+      mcpConfig = {};
+    }
+  }
+
+  if (!mcpConfig.mcpServers) {
+    mcpConfig.mcpServers = {};
+  }
+
+  mcpConfig.mcpServers.linear = {
+    type: 'http',
+    url: 'https://mcp.linear.app/mcp',
+    headers: {
+      Authorization: linearApiKey,
+    },
+  };
+
+  fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+  console.log(`   Configured Linear MCP: ${mcpConfigPath}`);
+}
+
+// --- Claude Code Command Installation ---
+
+function installCommand() {
+  const targetDir = path.join(os.homedir(), '.claude', 'commands', COMMAND_DIR);
+  const targetFile = path.join(targetDir, COMMAND_FILE);
+
+  // Find the command template relative to this script
+  let sourceFile = path.resolve(__dirname, '..', 'commands', COMMAND_FILE);
+
+  if (!fs.existsSync(sourceFile)) {
+    // Fallback: try from cwd
+    sourceFile = path.resolve(process.cwd(), 'commands', COMMAND_FILE);
+    if (!fs.existsSync(sourceFile)) {
+      console.error(`   Could not find command template at:\n     ${path.resolve(__dirname, '..', 'commands', COMMAND_FILE)}\n     ${sourceFile}`);
+      return false;
+    }
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const existed = fs.existsSync(targetFile);
+  fs.copyFileSync(sourceFile, targetFile);
+
+  if (existed) {
+    console.log(`   Updated: ${targetFile}`);
+  } else {
+    console.log(`   Installed: ${targetFile}`);
+  }
+
+  return true;
+}
+
+// --- Main ---
+
+async function init() {
+  // Collect credentials interactively
+  const credentials = await collectCredentials();
+
+  // Write .env file
+  console.log('\nConfiguring environment...');
+  writeEnvFile(credentials);
+
+  // Configure Linear MCP for Claude Code
+  console.log('\nConfiguring Claude Code...');
+  configureLinearMcp(credentials.linearApiKey);
+
+  // Install the Claude Code command
+  const installed = installCommand();
+
+  // Summary
+  console.log('\n' + '═'.repeat(50));
+  console.log('Setup complete!');
+  console.log('═'.repeat(50));
+
+  console.log('\nCLI usage:');
+  if (credentials.teamId) {
+    console.log(`  npm run generate -- "Add user authentication" ${credentials.teamId}`);
+  } else {
+    console.log('  npm run generate -- "Add user authentication" TEAM-abc123');
+  }
+
+  if (installed) {
+    console.log('\nClaude Code usage:');
+    if (credentials.teamId) {
+      console.log(`  /linear:generate-stories "Add user authentication" ${credentials.teamId}`);
+    } else {
+      console.log('  /linear:generate-stories "Add user authentication" TEAM-abc123');
+    }
+    console.log('\n  Linear MCP is configured — Claude can create issues directly.');
+  }
+
+  console.log('');
+}
+
+init();