linear-ai-build 1.0.0 → 1.1.0

package/README.md

@@ -13,15 +13,13 @@ Generate user stories from feature descriptions, push them to Linear, then have
 ### Install
 
 ```bash
-git clone <your-repo>
-cd linear-ai-build
-npm install
+npm install linear-ai-build
 ```
 
 ### Configure
 
 ```bash
-npm run init
+npx linear-ai-build init
 ```
 
 This will:
@@ -49,15 +47,19 @@ Create stories and tasks in Linear from a feature description.
 **CLI:**
 
 ```bash
-npm run generate -- "Add user authentication with OAuth" TEAM-abc123
+npx linear-ai-build generate "Add user authentication with OAuth" TEAM-abc123
+npx linear-ai-build generate "Add user authentication with OAuth" TEAM-abc123 "Auth Epic"
 ```
 
 **Claude Code:**
 
 ```
 /linear:generate-stories "Add user authentication with OAuth" TEAM-abc123
+/linear:generate-stories "Add user authentication with OAuth" TEAM-abc123 "Auth Epic"
 ```
 
+The third argument is an optional **project name**. If provided, issues are created under that Linear project (existing projects with the same name are reused). If omitted, the PRD title is used as the project name.
+
 **Options:**
 
 | Flag | Description |
@@ -98,13 +100,14 @@ This command:
 Alternatively, poll Linear and auto-process issues without Claude Code:
 
 ```bash
-npm run watch
+npx linear-ai-build watch
+npx linear-ai-build watch --project "My Project"
 ```
 
 Or process a single issue:
 
 ```bash
-npm run build:issue -- WIC-42
+npx linear-ai-build build WIC-42
 ```
 
 ## How It Works

package/bin/cli.ts

@@ -1,5 +1,14 @@
 #!/usr/bin/env npx tsx
 const command = process.argv[2];
+const args = process.argv.slice(3);
+
+function parseFlag(flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  return undefined;
+}
+
+const projectName = parseFlag('--project');
 
 switch (command) {
   case 'init':
@@ -7,20 +16,20 @@ switch (command) {
     break;
   case 'generate':
     // Forward remaining args to generate-sdk
-    process.argv = [process.argv[0], process.argv[1], ...process.argv.slice(3)];
+    process.argv = [process.argv[0], process.argv[1], ...args];
     import('../src/generate-sdk.ts');
     break;
   case 'watch':
-    import('../src/bridge/index.ts').then(m => m.watch());
+    import('../src/bridge/index.ts').then(m => m.watch({ project: projectName }));
     break;
   case 'build': {
-    const issueId = process.argv[3];
+    const issueId = args.find(a => !a.startsWith('--') && args[args.indexOf(a) - 1] !== '--project');
     if (!issueId) {
-      console.error('Usage: linear-ai-build build <issue-identifier>');
-      console.error('Example: linear-ai-build build WIC-42');
+      console.error('Usage: linear-ai-build build <issue-identifier> [--project "Project Name"]');
+      console.error('Example: linear-ai-build build WIC-42 --project "My Task List"');
       process.exit(1);
     }
-    import('../src/bridge/index.ts').then(m => m.build(issueId));
+    import('../src/bridge/index.ts').then(m => m.build(issueId, { project: projectName }));
     break;
   }
   default:
@@ -35,17 +44,21 @@ Commands:
 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
+  npx linear-ai-build watch [--project "Project Name"]
+  npx linear-ai-build build WIC-42 [--project "Project Name"]
 
 After running init, use the Claude Code command:
   /linear:generate-stories "Add user authentication" TEAM-abc123
 
+Options:
+  --project    Filter issues by Linear project name
+
 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)
+  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)
+  LINEAR_PROJECT_NAME   Filter issues by Linear project name
 `);
     break;
 }

package/commands/build-from-linear.md

@@ -5,12 +5,12 @@ Pull labeled stories and tasks from Linear, then execute them using Claude Flow
 ## Usage
 
 ```
-/linear:build-from-linear [issue-identifier] [--label ai-build]
+/linear:build-from-linear [issue-identifier] [--project "Project Name"] [--label ai-build]
 ```
 
 ## Arguments
 
-- `$ARGUMENTS` will contain an optional issue identifier (e.g., `WIC-42`) or `--label <name>` to process all issues with that label
+- `$ARGUMENTS` will contain an optional issue identifier (e.g., `WIC-42`), `--project <name>` to filter by Linear project, or `--label <name>` to process all issues with that label
 
 ## Instructions
 
@@ -20,6 +20,7 @@ When the user invokes this command, follow this workflow:
 
 Extract from `$ARGUMENTS`:
 - **Issue identifier** (optional) — e.g., `WIC-42` to process a specific issue
+- **--project** (optional) — Linear project name to filter by (e.g., `"My Task List"`)
 - **--label** (optional) — label name to filter by (defaults to `ai-build`)
 
 If no arguments provided, default to fetching all issues with the `ai-build` label.
@@ -32,9 +33,9 @@ Use the **Linear MCP tools** to find issues to process.
 
 Use the Linear MCP `search_issues` tool to find the issue by identifier. Then fetch its child issues (sub-tasks).
 
-**If fetching by label:**
+**If fetching by label (and optionally project):**
 
-Use the Linear MCP `search_issues` tool to find all issues with the specified label that are in an unstarted/todo state. Only fetch parent issues (stories), not child tasks.
+Use the Linear MCP `search_issues` tool to find all issues with the specified label that are in an unstarted/todo state. Only fetch parent issues (stories), not child tasks. If `--project` was provided, also filter by the project name.
 
 For each issue found, also fetch:
 - Child issues (sub-tasks) — these are the implementation tasks

package/dist/bridge/config.d.ts

@@ -1,6 +1,7 @@
 export interface BridgeConfig {
     linearApiKey: string;
     linearTeamId: string;
+    linearProjectName?: string;
     pollIntervalMs: number;
     aiLabel: string;
     targetRepoPath: string;

package/dist/bridge/config.js

@@ -14,6 +14,7 @@ export function loadConfig() {
     return {
         linearApiKey,
         linearTeamId,
+        linearProjectName: process.env.LINEAR_PROJECT_NAME || undefined,
         pollIntervalMs: parseInt(process.env.POLL_INTERVAL_MS || '30000', 10),
         aiLabel: process.env.AI_BUILD_LABEL || 'ai-build',
         targetRepoPath,

package/dist/bridge/index.d.ts

@@ -1,3 +1,7 @@
 import 'dotenv/config';
-export declare function watch(): Promise<void>;
-export declare function build(issueIdentifier: string): Promise<void>;
+export declare function watch(opts?: {
+    project?: string;
+}): Promise<void>;
+export declare function build(issueIdentifier: string, opts?: {
+    project?: string;
+}): Promise<void>;

package/dist/bridge/index.js

@@ -14,8 +14,10 @@ function parseAcceptanceCriteria(description) {
         .map(line => line.replace(/^\s*[-*\d.]+\s*/, '').trim())
         .filter(Boolean);
 }
-export async function watch() {
+export async function watch(opts) {
     const config = loadConfig();
+    if (opts?.project)
+        config.linearProjectName = opts.project;
     const state = new ProcessingState(config.processedFile);
     await state.load();
     const watcher = new LinearWatcher(config, state.getSet());
@@ -57,8 +59,10 @@ export async function watch() {
     };
     await watcher.start();
 }
-export async function build(issueIdentifier) {
+export async function build(issueIdentifier, opts) {
     const config = loadConfig();
+    if (opts?.project)
+        config.linearProjectName = opts.project;
     const executor = new WorkflowExecutor(config);
     const reporter = new LinearReporter();
     const linear = getLinearClient();

package/dist/bridge/watcher.js

@@ -24,6 +24,9 @@ export class LinearWatcher {
         this.running = true;
         console.log(`Watching Linear for issues with label "${this.config.aiLabel}"`);
         console.log(`Team: ${this.config.linearTeamId} (${this.teamId})`);
+        if (this.config.linearProjectName) {
+            console.log(`Project: ${this.config.linearProjectName}`);
+        }
         console.log(`Polling every ${this.config.pollIntervalMs / 1000}s`);
         console.log(`Target repo: ${this.config.targetRepoPath}`);
         console.log('');
@@ -47,15 +50,18 @@ export class LinearWatcher {
     }
     async pollForReadyIssues() {
         const linear = getLinearClient();
-        // Query: parent issues (no parent) with ai-build label in unstarted state
-        const issues = await linear.issues({
-            filter: {
-                team: { id: { eq: this.teamId } },
-                labels: { some: { name: { eq: this.config.aiLabel } } },
-                state: { type: { eq: 'unstarted' } },
-                parent: { null: true },
-            },
-        });
+        // Build filter: parent issues with ai-build label in unstarted state
+        const filter = {
+            team: { id: { eq: this.teamId } },
+            labels: { some: { name: { eq: this.config.aiLabel } } },
+            state: { type: { eq: 'unstarted' } },
+            parent: { null: true },
+        };
+        // Optionally filter by project name
+        if (this.config.linearProjectName) {
+            filter.project = { name: { eq: this.config.linearProjectName } };
+        }
+        const issues = await linear.issues({ filter });
         const results = [];
         for (const issue of issues.nodes) {
             if (this.processedIds.has(issue.id))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linear-ai-build",
-  "version": "1.0.0",
+  "version": "1.1.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",

package/src/bridge/config.ts

@@ -3,6 +3,7 @@ import * as path from 'path';
 export interface BridgeConfig {
   linearApiKey: string;
   linearTeamId: string;
+  linearProjectName?: string;
   pollIntervalMs: number;
   aiLabel: string;
   targetRepoPath: string;
@@ -29,6 +30,7 @@ export function loadConfig(): BridgeConfig {
   return {
     linearApiKey,
     linearTeamId,
+    linearProjectName: process.env.LINEAR_PROJECT_NAME || undefined,
     pollIntervalMs: parseInt(process.env.POLL_INTERVAL_MS || '30000', 10),
     aiLabel: process.env.AI_BUILD_LABEL || 'ai-build',
     targetRepoPath,

package/src/bridge/index.ts

@@ -18,8 +18,9 @@ function parseAcceptanceCriteria(description: string): string[] {
     .filter(Boolean);
 }
 
-export async function watch(): Promise<void> {
+export async function watch(opts?: { project?: string }): Promise<void> {
   const config = loadConfig();
+  if (opts?.project) config.linearProjectName = opts.project;
   const state = new ProcessingState(config.processedFile);
   await state.load();
 
@@ -67,8 +68,9 @@ export async function watch(): Promise<void> {
   await watcher.start();
 }
 
-export async function build(issueIdentifier: string): Promise<void> {
+export async function build(issueIdentifier: string, opts?: { project?: string }): Promise<void> {
   const config = loadConfig();
+  if (opts?.project) config.linearProjectName = opts.project;
   const executor = new WorkflowExecutor(config);
   const reporter = new LinearReporter();
 

package/src/bridge/watcher.ts

@@ -34,6 +34,9 @@ export class LinearWatcher {
 
     console.log(`Watching Linear for issues with label "${this.config.aiLabel}"`);
     console.log(`Team: ${this.config.linearTeamId} (${this.teamId})`);
+    if (this.config.linearProjectName) {
+      console.log(`Project: ${this.config.linearProjectName}`);
+    }
     console.log(`Polling every ${this.config.pollIntervalMs / 1000}s`);
     console.log(`Target repo: ${this.config.targetRepoPath}`);
     console.log('');
@@ -60,15 +63,20 @@ export class LinearWatcher {
   private async pollForReadyIssues(): Promise<LinearIssueContext[]> {
     const linear = getLinearClient();
 
-    // Query: parent issues (no parent) with ai-build label in unstarted state
-    const issues = await linear.issues({
-      filter: {
-        team: { id: { eq: this.teamId } },
-        labels: { some: { name: { eq: this.config.aiLabel } } },
-        state: { type: { eq: 'unstarted' } },
-        parent: { null: true },
-      },
-    });
+    // Build filter: parent issues with ai-build label in unstarted state
+    const filter: Record<string, any> = {
+      team: { id: { eq: this.teamId } },
+      labels: { some: { name: { eq: this.config.aiLabel } } },
+      state: { type: { eq: 'unstarted' } },
+      parent: { null: true },
+    };
+
+    // Optionally filter by project name
+    if (this.config.linearProjectName) {
+      filter.project = { name: { eq: this.config.linearProjectName } };
+    }
+
+    const issues = await linear.issues({ filter });
 
     const results: LinearIssueContext[] = [];