linear-ai-build 1.0.0

package/dist/index.js

@@ -0,0 +1,232 @@
+import Anthropic from '@anthropic-ai/sdk';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+// Initialize Anthropic client
+const anthropic = new Anthropic({
+    apiKey: process.env.ANTHROPIC_API_KEY,
+});
+/**
+ * Step 1: Generate PRD from feature description using Claude
+ */
+async function generatePRD(featureDescription) {
+    console.log('🤔 Generating PRD with Claude...\n');
+    const response = await anthropic.messages.create({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 4000,
+        messages: [{
+                role: 'user',
+                content: `You are an expert product manager. Create a comprehensive Product Requirements Document (PRD) for the following feature:
+
+FEATURE REQUEST:
+${featureDescription}
+
+Generate a detailed PRD with:
+1. Executive summary
+2. 3-5 user stories following the format: "As a [persona], I want to [action] so that [benefit]"
+3. For each story, include acceptance criteria
+4. Technical notes and considerations
+
+Respond ONLY with valid JSON matching this schema:
+{
+  "title": "Feature Title",
+  "summary": "2-3 sentence executive summary",
+  "stories": [
+    {
+      "title": "Story title",
+      "description": "As a [persona], I want to [action] so that [benefit]",
+      "persona": "User type",
+      "acceptanceCriteria": ["criterion 1", "criterion 2"],
+      "priority": "high|medium|low"
+    }
+  ],
+  "technicalNotes": ["note 1", "note 2"]
+}
+
+Return ONLY the JSON, no markdown formatting or explanation.`
+            }]
+    });
+    const content = response.content[0];
+    if (content.type !== 'text') {
+        throw new Error('Unexpected response type');
+    }
+    // Parse JSON response
+    const prd = JSON.parse(content.text);
+    // Save PRD to file
+    const prdsDir = path.join(process.cwd(), '.linear', 'prds');
+    await fs.mkdir(prdsDir, { recursive: true });
+    const filename = `${prd.title.toLowerCase().replace(/\s+/g, '-')}-${Date.now()}.json`;
+    await fs.writeFile(path.join(prdsDir, filename), JSON.stringify(prd, null, 2));
+    console.log(`✅ PRD generated and saved to .linear/prds/${filename}\n`);
+    return prd;
+}
+/**
+ * Step 2: Break down each story into tasks using Claude
+ */
+async function generateTasks(story) {
+    console.log(`  🔨 Breaking down: ${story.title}...`);
+    const response = await anthropic.messages.create({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 2000,
+        messages: [{
+                role: 'user',
+                content: `Break down this user story into concrete development tasks:
+
+STORY: ${story.title}
+DESCRIPTION: ${story.description}
+ACCEPTANCE CRITERIA:
+${story.acceptanceCriteria.map((ac, i) => `${i + 1}. ${ac}`).join('\n')}
+
+Create 3-7 specific tasks covering:
+- Frontend/UI work
+- Backend/API work
+- Database changes (if needed)
+- Testing requirements
+
+For each task provide:
+- Clear title (verb-object format like "Create login form" or "Implement JWT authentication")
+- Description with technical details
+- Effort estimate (1=small, 3=medium, 5=large)
+- Whether it can run in parallel with other tasks
+
+Respond ONLY with valid JSON array:
+[
+  {
+    "title": "Task title",
+    "description": "Technical details of what needs to be done",
+    "effort": 1-5,
+    "parallel": true|false
+  }
+]
+
+Return ONLY the JSON array, no markdown or explanation.`
+            }]
+    });
+    const content = response.content[0];
+    if (content.type !== 'text') {
+        throw new Error('Unexpected response type');
+    }
+    const tasks = JSON.parse(content.text);
+    console.log(`    ✓ Generated ${tasks.length} tasks`);
+    return tasks;
+}
+/**
+ * Step 3: Create issues in Linear using MCP tools
+ */
+async function createInLinear(prd, teamId, projectName) {
+    console.log('\n📝 Creating issues in Linear via MCP...\n');
+    // Build the tool use request for Claude
+    const toolMessages = [
+        {
+            role: 'user',
+            content: `You have access to Linear through MCP tools. Create a project and issues for this PRD:
+
+PROJECT NAME: ${projectName || prd.title}
+TEAM ID: ${teamId}
+
+PRD DATA:
+${JSON.stringify(prd, null, 2)}
+
+INSTRUCTIONS:
+1. First, search for existing projects with name "${projectName || prd.title}" to avoid duplicates
+2. If project doesn't exist, create it with the PRD summary as description
+3. For each story in the PRD:
+   - Create a parent issue with the story title and description
+   - Add label "user-story" if available
+   - Set priority based on the story's priority field
+4. For each task within a story:
+   - Create a child issue linked to the parent story
+   - Include effort estimate in the description
+   - Add label "task" if available
+
+After creating all issues, provide a summary with:
+- Project URL
+- Number of stories created
+- Number of tasks created
+- Any issues encountered
+
+Use Linear MCP tools to accomplish this.`
+        }
+    ];
+    const response = await anthropic.messages.create({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 8000,
+        messages: toolMessages,
+        tools: [
+            {
+                type: 'mcp',
+                name: 'linear',
+                mcp_server_name: 'linear'
+            }
+        ]
+    });
+    // Process the response (Claude will have used Linear MCP tools)
+    let finalResponse = '';
+    for (const block of response.content) {
+        if (block.type === 'text') {
+            finalResponse += block.text;
+        }
+    }
+    console.log('\n✅ Linear issues created!\n');
+    return finalResponse;
+}
+/**
+ * Main workflow
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.log(`
+Usage: npm start -- "Feature description" [teamId] [projectName]
+
+Example:
+  npm start -- "Add user authentication with social login" "TEAM-123" "Auth Epic"
+
+Environment variables required:
+  ANTHROPIC_API_KEY=sk-ant-...
+  LINEAR_API_KEY=lin_api_...  (for MCP server)
+`);
+        process.exit(1);
+    }
+    const featureDescription = args[0];
+    const teamId = args[1] || process.env.LINEAR_TEAM_ID;
+    const projectName = args[2];
+    if (!teamId) {
+        console.error('❌ Error: Team ID required (provide as argument or LINEAR_TEAM_ID env var)');
+        process.exit(1);
+    }
+    try {
+        // Step 1: Generate PRD
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('  STEP 1: Generate PRD');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+        const prd = await generatePRD(featureDescription);
+        console.log(`📋 PRD Summary:`);
+        console.log(`   Title: ${prd.title}`);
+        console.log(`   Stories: ${prd.stories.length}`);
+        console.log('');
+        // Step 2: Generate tasks for each story
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('  STEP 2: Generate Tasks');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+        for (const story of prd.stories) {
+            story.tasks = await generateTasks(story);
+        }
+        const totalTasks = prd.stories.reduce((sum, s) => sum + s.tasks.length, 0);
+        console.log(`\n✅ Generated ${totalTasks} total tasks across ${prd.stories.length} stories\n`);
+        // Step 3: Create in Linear
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('  STEP 3: Create in Linear');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        const summary = await createInLinear(prd, teamId, projectName);
+        console.log(summary);
+    }
+    catch (error) {
+        console.error('❌ Error:', error);
+        process.exit(1);
+    }
+}
+// Run if called directly
+if (require.main === module) {
+    main();
+}
+export { generatePRD, generateTasks, createInLinear };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "linear-ai-build",
+  "version": "1.0.0",
+  "description": "Generate user stories from feature descriptions, push them to Linear, then have AI agents build the code with Claude Flow",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "linear-ai-build": "bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx src/index.ts",
+    "generate": "tsx src/generate-sdk.ts",
+    "init": "tsx bin/init.ts",
+    "dev": "tsx watch src/index.ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build",
+    "watch": "tsx bin/cli.ts watch",
+    "build:issue": "tsx bin/cli.ts build"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "commands",
+    "src",
+    ".env.example",
+    "README.md"
+  ],
+  "keywords": [
+    "linear",
+    "claude",
+    "claude-code",
+    "claude-flow",
+    "mcp",
+    "user-stories",
+    "agile",
+    "ai",
+    "ai-agents",
+    "code-generation",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alwick/linear-ai-build.git"
+  },
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.32.1",
+    "@linear/sdk": "^29.0.0",
+    "dotenv": "^16.4.5",
+    "tsx": "^4.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/bridge/config.ts

@@ -0,0 +1,39 @@
+import * as path from 'path';
+
+export interface BridgeConfig {
+  linearApiKey: string;
+  linearTeamId: string;
+  pollIntervalMs: number;
+  aiLabel: string;
+  targetRepoPath: string;
+  targetBranch: string;
+  contextDir: string;
+  processedFile: string;
+}
+
+export function loadConfig(): BridgeConfig {
+  const linearApiKey = process.env.LINEAR_API_KEY;
+  if (!linearApiKey) {
+    console.error('Missing LINEAR_API_KEY environment variable');
+    process.exit(1);
+  }
+
+  const linearTeamId = process.env.LINEAR_TEAM_ID;
+  if (!linearTeamId) {
+    console.error('Missing LINEAR_TEAM_ID environment variable');
+    process.exit(1);
+  }
+
+  const targetRepoPath = process.env.TARGET_REPO_PATH || process.cwd();
+
+  return {
+    linearApiKey,
+    linearTeamId,
+    pollIntervalMs: parseInt(process.env.POLL_INTERVAL_MS || '30000', 10),
+    aiLabel: process.env.AI_BUILD_LABEL || 'ai-build',
+    targetRepoPath,
+    targetBranch: process.env.TARGET_BRANCH || 'main',
+    contextDir: path.join(targetRepoPath, '.linear', 'context'),
+    processedFile: path.join(targetRepoPath, '.linear', 'processed.json'),
+  };
+}

package/src/bridge/executor.ts

@@ -0,0 +1,167 @@
+import { spawn, execSync } from 'child_process';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import type { LinearIssueContext, WorkflowResult } from './types.js';
+import { buildWorkflow } from './transformer.js';
+import type { BridgeConfig } from './config.js';
+
+function createBranch(identifier: string, baseBranch: string, cwd: string): string {
+  const branchName = `linear/${identifier.toLowerCase()}`;
+
+  try {
+    execSync(`git checkout ${baseBranch}`, { cwd, stdio: 'pipe' });
+  } catch {
+    console.log(`  Warning: could not checkout ${baseBranch}, continuing on current branch`);
+  }
+
+  try {
+    execSync(`git pull origin ${baseBranch}`, { cwd, stdio: 'pipe' });
+  } catch {
+    console.log(`  Warning: could not pull ${baseBranch}, continuing with local state`);
+  }
+
+  try {
+    execSync(`git checkout -b ${branchName}`, { cwd, stdio: 'pipe' });
+  } catch {
+    // Branch may already exist
+    try {
+      execSync(`git checkout ${branchName}`, { cwd, stdio: 'pipe' });
+    } catch {
+      console.log(`  Warning: could not create or checkout branch ${branchName}`);
+    }
+  }
+
+  return branchName;
+}
+
+export class WorkflowExecutor {
+  private config: BridgeConfig;
+
+  constructor(config: BridgeConfig) {
+    this.config = config;
+  }
+
+  async execute(ctx: LinearIssueContext): Promise<WorkflowResult> {
+    const identifier = ctx.story.identifier;
+    console.log(`\nExecuting workflow for ${identifier}: ${ctx.story.title}`);
+
+    // Create git branch in target repo
+    const branchName = createBranch(identifier, this.config.targetBranch, this.config.targetRepoPath);
+    console.log(`  Branch: ${branchName}`);
+
+    // Write context file
+    await fs.mkdir(this.config.contextDir, { recursive: true });
+    const contextPath = path.join(this.config.contextDir, `${identifier}.json`);
+    await fs.writeFile(contextPath, JSON.stringify(ctx, null, 2));
+
+    // Build and write workflow JSON
+    const workflow = buildWorkflow(ctx);
+    const workflowPath = path.join(this.config.contextDir, `${identifier}-workflow.json`);
+    await fs.writeFile(workflowPath, JSON.stringify(workflow, null, 2));
+    console.log(`  Workflow: ${workflowPath}`);
+
+    // Execute Claude Flow
+    try {
+      const output = await this.runClaudeFlow(workflowPath, contextPath);
+      console.log(`  Workflow completed for ${identifier}`);
+
+      return {
+        success: true,
+        branchName,
+        summary: `Workflow completed for ${identifier}`,
+        errors: [],
+        taskResults: ctx.tasks.map(t => ({
+          taskId: t.id,
+          taskIdentifier: t.identifier,
+          status: 'completed' as const,
+          summary: `Implemented: ${t.title}`,
+        })),
+      };
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      console.error(`  Workflow failed for ${identifier}: ${errorMsg}`);
+
+      return {
+        success: false,
+        branchName,
+        summary: `Workflow failed for ${identifier}: ${errorMsg}`,
+        errors: [errorMsg],
+        taskResults: ctx.tasks.map(t => ({
+          taskId: t.id,
+          taskIdentifier: t.identifier,
+          status: 'failed' as const,
+          summary: `Failed: ${errorMsg}`,
+        })),
+      };
+    }
+  }
+
+  private runClaudeFlow(workflowPath: string, contextPath: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        'claude-flow',
+        [
+          'automation',
+          'run-workflow',
+          workflowPath,
+          '--claude',
+          '--non-interactive',
+          '--output-format',
+          'stream-json',
+        ],
+        {
+          cwd: this.config.targetRepoPath,
+          env: {
+            ...process.env,
+            CONTEXT_FILE: contextPath,
+          },
+          stdio: ['pipe', 'pipe', 'pipe'],
+        },
+      );
+
+      let stdout = '';
+      let stderr = '';
+
+      child.stdout.on('data', (data: Buffer) => {
+        const chunk = data.toString();
+        stdout += chunk;
+        for (const line of chunk.split('\n').filter(Boolean)) {
+          try {
+            const event = JSON.parse(line);
+            if (event.type === 'message') {
+              const text = event.content?.[0]?.text || '';
+              if (text) console.log(`  [agent] ${text.slice(0, 120)}`);
+            }
+          } catch {
+            // Not JSON, log raw output
+            if (line.trim()) console.log(`  [claude-flow] ${line.trim().slice(0, 120)}`);
+          }
+        }
+      });
+
+      child.stderr.on('data', (data: Buffer) => {
+        stderr += data.toString();
+      });
+
+      child.on('error', (err) => {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+          reject(
+            new Error(
+              'claude-flow not found. Install it with: npm install -g claude-flow@alpha',
+            ),
+          );
+        } else {
+          reject(err);
+        }
+      });
+
+      child.on('close', (code: number | null) => {
+        if (code === 0) {
+          resolve(stdout);
+        } else {
+          reject(new Error(`claude-flow exited with code ${code}:\n${stderr || stdout}`));
+        }
+      });
+    });
+  }
+}

package/src/bridge/index.ts

@@ -0,0 +1,156 @@
+import 'dotenv/config';
+import { loadConfig } from './config.js';
+import { LinearWatcher } from './watcher.js';
+import { WorkflowExecutor } from './executor.js';
+import { LinearReporter } from './reporter.js';
+import { ProcessingState } from './state.js';
+import { getLinearClient, resolveTeamId } from './linear-helpers.js';
+import type { LinearIssueContext } from './types.js';
+
+function parseAcceptanceCriteria(description: string): string[] {
+  const match = description.match(
+    /\*\*Acceptance Criteria:?\*\*\s*\n([\s\S]*?)(?:\n\n|\n\*\*|$)/i,
+  );
+  if (!match) return [];
+  return match[1]
+    .split('\n')
+    .map(line => line.replace(/^\s*[-*\d.]+\s*/, '').trim())
+    .filter(Boolean);
+}
+
+export async function watch(): Promise<void> {
+  const config = loadConfig();
+  const state = new ProcessingState(config.processedFile);
+  await state.load();
+
+  const watcher = new LinearWatcher(config, state.getSet());
+  const executor = new WorkflowExecutor(config);
+  const reporter = new LinearReporter();
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    console.log('\nShutting down...');
+    watcher.stop();
+    await state.save();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  watcher.onIssueFound = async (ctx: LinearIssueContext) => {
+    console.log(`\nFound issue: ${ctx.story.identifier} - ${ctx.story.title}`);
+    console.log(`  Tasks: ${ctx.tasks.length}`);
+    console.log(`  URL: ${ctx.story.url}`);
+
+    // Mark as processed to prevent re-processing
+    state.add(ctx.story.id);
+    await state.save();
+
+    try {
+      await reporter.markInProgress(ctx);
+      const result = await executor.execute(ctx);
+
+      if (result.success) {
+        await reporter.markComplete(ctx, result);
+        console.log(`  Done: ${ctx.story.identifier} → branch ${result.branchName}`);
+      } else {
+        await reporter.markFailed(ctx, result.summary);
+        console.error(`  Failed: ${ctx.story.identifier}`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`  Error processing ${ctx.story.identifier}: ${msg}`);
+      await reporter.markFailed(ctx, msg);
+    }
+  };
+
+  await watcher.start();
+}
+
+export async function build(issueIdentifier: string): Promise<void> {
+  const config = loadConfig();
+  const executor = new WorkflowExecutor(config);
+  const reporter = new LinearReporter();
+
+  const linear = getLinearClient();
+  const teamId = await resolveTeamId(config.linearTeamId);
+
+  // Parse issue number from identifier (e.g., "WIC-42" → 42)
+  const parts = issueIdentifier.split('-');
+  const issueNumber = parseInt(parts[parts.length - 1], 10);
+
+  if (isNaN(issueNumber)) {
+    console.error(`Invalid issue identifier: ${issueIdentifier}`);
+    console.error('Expected format: TEAM-123 (e.g., WIC-42)');
+    process.exit(1);
+  }
+
+  const issues = await linear.issues({
+    filter: {
+      team: { id: { eq: teamId } },
+      number: { eq: issueNumber },
+    },
+  });
+
+  const issue = issues.nodes[0];
+  if (!issue) {
+    console.error(`Issue ${issueIdentifier} not found in team ${config.linearTeamId}`);
+    process.exit(1);
+  }
+
+  const children = await issue.children();
+  const labels = await issue.labels();
+  const project = await issue.project;
+
+  const ctx: LinearIssueContext = {
+    story: {
+      id: issue.id,
+      identifier: issue.identifier,
+      title: issue.title,
+      description: issue.description || '',
+      url: issue.url,
+      priority: issue.priority,
+      branchName: issue.branchName,
+      labels: labels.nodes.map(l => l.name),
+      acceptanceCriteria: parseAcceptanceCriteria(issue.description || ''),
+    },
+    tasks: children.nodes.map(child => ({
+      id: child.id,
+      identifier: child.identifier,
+      title: child.title,
+      description: child.description || '',
+      effort: child.estimate ?? null,
+      url: child.url,
+    })),
+    project: project
+      ? {
+          id: project.id,
+          name: project.name,
+          description: project.description || '',
+          url: project.url,
+        }
+      : undefined,
+    meta: {
+      teamId,
+      teamKey: config.linearTeamId,
+      fetchedAt: new Date().toISOString(),
+    },
+  };
+
+  console.log(`Building: ${ctx.story.identifier} - ${ctx.story.title}`);
+  console.log(`  Tasks: ${ctx.tasks.length}`);
+  console.log(`  URL: ${ctx.story.url}`);
+  console.log('');
+
+  await reporter.markInProgress(ctx);
+  const result = await executor.execute(ctx);
+
+  if (result.success) {
+    await reporter.markComplete(ctx, result);
+    console.log(`\nDone! Branch: ${result.branchName}`);
+  } else {
+    await reporter.markFailed(ctx, result.summary);
+    console.error(`\nFailed: ${result.summary}`);
+    process.exit(1);
+  }
+}

package/src/bridge/linear-helpers.ts

@@ -0,0 +1,49 @@
+import { LinearClient } from '@linear/sdk';
+
+let linear: LinearClient;
+
+export function getLinearClient(): LinearClient {
+  if (!linear) {
+    const apiKey = process.env.LINEAR_API_KEY;
+    if (!apiKey) throw new Error('Missing LINEAR_API_KEY environment variable');
+    linear = new LinearClient({ apiKey });
+  }
+  return linear;
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export async function resolveTeamId(teamIdOrKey: string): Promise<string> {
+  if (UUID_RE.test(teamIdOrKey)) return teamIdOrKey;
+
+  const client = getLinearClient();
+  const viewer = await client.viewer;
+  const teams = await viewer.teams();
+  const match = teams.nodes.find(t => t.key.toLowerCase() === teamIdOrKey.toLowerCase());
+  if (!match) {
+    const available = teams.nodes.map(t => `${t.key} (${t.name})`).join(', ');
+    throw new Error(`Team key "${teamIdOrKey}" not found. Available teams: ${available}`);
+  }
+  console.log(`  Resolved team: ${match.key} → ${match.name} (${match.id})`);
+  return match.id;
+}
+
+export async function findStateByType(teamId: string, type: string): Promise<string | undefined> {
+  const client = getLinearClient();
+  const states = await client.workflowStates({
+    filter: { team: { id: { eq: teamId } }, type: { eq: type } },
+  });
+  return states.nodes[0]?.id;
+}
+
+export async function findStateByName(teamId: string, name: string): Promise<string | undefined> {
+  const client = getLinearClient();
+  const states = await client.workflowStates({
+    filter: { team: { id: { eq: teamId } }, name: { eqIgnoreCase: name } },
+  });
+  return states.nodes[0]?.id;
+}
+
+export function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}