cortex-agents 2.3.1 → 3.4.0

package/dist/tools/repl.js

@@ -0,0 +1,240 @@
+/**
+ * REPL Loop Tools
+ *
+ * Four tools for the implement agent's iterative task-by-task development loop:
+ *   - repl_init    — Initialize a loop from a plan
+ *   - repl_status  — Get current progress and next task
+ *   - repl_report  — Report task outcome (pass/fail/skip)
+ *   - repl_summary — Generate markdown summary for PR body
+ */
+import { tool } from "@opencode-ai/plugin";
+import * as fs from "fs";
+import * as path from "path";
+import { parseTasksFromPlan, detectCommands, readReplState, writeReplState, getNextTask, getCurrentTask, isLoopComplete, formatProgress, formatSummary, } from "../utils/repl.js";
+const CORTEX_DIR = ".cortex";
+const PLANS_DIR = "plans";
+// ─── repl_init ───────────────────────────────────────────────────────────────
+export const init = tool({
+    description: "Initialize a REPL implementation loop from a plan. Parses plan tasks, " +
+        "auto-detects build/test commands, and creates .cortex/repl-state.json " +
+        "for tracking progress through each task iteratively.",
+    args: {
+        planFilename: tool.schema
+            .string()
+            .describe("Plan filename from .cortex/plans/ to load tasks from"),
+        buildCommand: tool.schema
+            .string()
+            .optional()
+            .describe("Override auto-detected build command (e.g., 'npm run build')"),
+        testCommand: tool.schema
+            .string()
+            .optional()
+            .describe("Override auto-detected test command (e.g., 'npm test')"),
+        maxRetries: tool.schema
+            .number()
+            .optional()
+            .describe("Max retries per failing task before escalating to user (default: 3)"),
+    },
+    async execute(args, context) {
+        const { planFilename, buildCommand, testCommand, maxRetries = 3 } = args;
+        const cwd = context.worktree;
+        // 1. Validate plan filename
+        if (!planFilename || planFilename === "." || planFilename === "..") {
+            return `\u2717 Error: Invalid plan filename.`;
+        }
+        const plansDir = path.join(cwd, CORTEX_DIR, PLANS_DIR);
+        const planPath = path.resolve(plansDir, planFilename);
+        const resolvedPlansDir = path.resolve(plansDir);
+        // Prevent path traversal — resolved path must be strictly inside plans dir
+        if (!planPath.startsWith(resolvedPlansDir + path.sep)) {
+            return `\u2717 Error: Invalid plan filename.`;
+        }
+        if (!fs.existsSync(planPath)) {
+            return `\u2717 Error: Plan not found: ${planFilename}\n\nUse plan_list to see available plans.`;
+        }
+        const planContent = fs.readFileSync(planPath, "utf-8");
+        // 2. Parse tasks from plan
+        const taskDescriptions = parseTasksFromPlan(planContent);
+        if (taskDescriptions.length === 0) {
+            return `\u2717 Error: No tasks found in plan: ${planFilename}\n\nThe plan must contain unchecked checkbox items (- [ ] ...) in a ## Tasks section.`;
+        }
+        // 3. Auto-detect commands (or use overrides)
+        const detected = await detectCommands(cwd);
+        const finalBuild = buildCommand ?? detected.buildCommand;
+        const finalTest = testCommand ?? detected.testCommand;
+        // 4. Build initial state
+        const tasks = taskDescriptions.map((desc, i) => ({
+            index: i,
+            description: desc,
+            status: "pending",
+            retries: 0,
+            iterations: [],
+        }));
+        const state = {
+            planFilename,
+            startedAt: new Date().toISOString(),
+            buildCommand: finalBuild,
+            testCommand: finalTest,
+            lintCommand: detected.lintCommand,
+            maxRetries,
+            currentTaskIndex: -1,
+            tasks,
+        };
+        // 5. Write state
+        writeReplState(cwd, state);
+        // 6. Format output
+        const cmdInfo = detected.detected
+            ? `Auto-detected (${detected.framework})`
+            : "Not detected \u2014 provide overrides if needed";
+        return `\u2713 REPL loop initialized
+
+Plan: ${planFilename}
+Tasks: ${tasks.length}
+Detection: ${cmdInfo}
+
+Build: ${finalBuild || "(none)"}
+Test:  ${finalTest || "(none)"}
+${detected.lintCommand ? `Lint:  ${detected.lintCommand}` : ""}
+Max retries: ${maxRetries}
+
+First task (#1):
+  "${tasks[0].description}"
+
+Run \`repl_status\` to begin, then implement the task and run build/tests.`;
+    },
+});
+// ─── repl_status ─────────────────────────────────────────────────────────────
+export const status = tool({
+    description: "Get the current REPL loop progress \u2014 which task is active, " +
+        "what\u2019s been completed, retry counts, and detected build/test commands. " +
+        "Call this to decide what to implement next.",
+    args: {},
+    async execute(args, context) {
+        const state = readReplState(context.worktree);
+        if (!state) {
+            return `\u2717 No REPL loop active.\n\nRun repl_init with a plan filename to start a loop.`;
+        }
+        // Auto-advance: if no task is in_progress, promote the next pending task
+        const current = getCurrentTask(state);
+        if (!current && !isLoopComplete(state)) {
+            const next = getNextTask(state);
+            if (next) {
+                next.status = "in_progress";
+                state.currentTaskIndex = next.index;
+                writeReplState(context.worktree, state);
+            }
+        }
+        return `\u2713 REPL Loop Status\n\n${formatProgress(state)}`;
+    },
+});
+// ─── repl_report ─────────────────────────────────────────────────────────────
+export const report = tool({
+    description: "Report the outcome of the current task iteration. " +
+        "After implementing a task and running build/tests, report whether it passed, " +
+        "failed, or should be skipped. The loop will auto-advance on pass, " +
+        "retry on fail (up to max), or escalate to user when retries exhausted.",
+    args: {
+        result: tool.schema
+            .enum(["pass", "fail", "skip"])
+            .describe("Task result: 'pass' (build+tests green), 'fail' (something broke), 'skip' (defer task)"),
+        detail: tool.schema
+            .string()
+            .describe("Result details: test output summary, error message, or skip reason"),
+    },
+    async execute(args, context) {
+        const { result, detail } = args;
+        const state = readReplState(context.worktree);
+        if (!state) {
+            return `\u2717 No REPL loop active. Run repl_init first.`;
+        }
+        // Find the current in_progress task
+        const current = getCurrentTask(state);
+        if (!current) {
+            // Try to find the task at currentTaskIndex
+            if (state.currentTaskIndex >= 0 && state.currentTaskIndex < state.tasks.length) {
+                const task = state.tasks[state.currentTaskIndex];
+                if (task.status === "pending") {
+                    task.status = "in_progress";
+                }
+                return processReport(state, task, result, detail, context.worktree);
+            }
+            return `\u2717 No task is currently in progress.\n\nRun repl_status to advance to the next task.`;
+        }
+        return processReport(state, current, result, detail, context.worktree);
+    },
+});
+/**
+ * Process a report for a task and update state.
+ */
+function processReport(state, task, result, detail, cwd) {
+    // Record iteration
+    task.iterations.push({
+        at: new Date().toISOString(),
+        result,
+        detail: detail.substring(0, 2000), // Cap detail length
+    });
+    const taskNum = task.index + 1;
+    const taskDesc = task.description;
+    let output;
+    switch (result) {
+        case "pass": {
+            task.status = "passed";
+            const attempt = task.iterations.length;
+            const suffix = attempt === 1 ? "1st" : attempt === 2 ? "2nd" : attempt === 3 ? "3rd" : `${attempt}th`;
+            output = `\u2713 Task #${taskNum} PASSED (${suffix} attempt)\n  "${taskDesc}"\n  Detail: ${detail.substring(0, 200)}`;
+            break;
+        }
+        case "fail": {
+            task.retries += 1;
+            const attempt = task.iterations.length;
+            if (task.retries >= state.maxRetries) {
+                // Retries exhausted
+                task.status = "failed";
+                output = `\u2717 Task #${taskNum} FAILED \u2014 retries exhausted (${attempt}/${state.maxRetries} attempts)\n  "${taskDesc}"\n  Detail: ${detail.substring(0, 200)}\n\n\u2192 ASK THE USER how to proceed. Suggest: fix manually, skip task, or abort loop.`;
+            }
+            else {
+                // Retries remaining — stay in_progress
+                const remaining = state.maxRetries - task.retries;
+                output = `\u26A0 Task #${taskNum} FAILED (attempt ${attempt}/${state.maxRetries})\n  "${taskDesc}"\n  Detail: ${detail.substring(0, 200)}\n\n\u2192 Fix the issue and run build/tests again. ${remaining} retr${remaining > 1 ? "ies" : "y"} remaining.`;
+                // Don't advance — keep task in_progress
+                writeReplState(cwd, state);
+                return output;
+            }
+            break;
+        }
+        case "skip": {
+            task.status = "skipped";
+            output = `\u2298 Task #${taskNum} SKIPPED\n  "${taskDesc}"\n  Reason: ${detail.substring(0, 200)}`;
+            break;
+        }
+    }
+    // Advance to next task
+    const next = getNextTask(state);
+    if (next) {
+        next.status = "in_progress";
+        state.currentTaskIndex = next.index;
+        output += `\n\n\u2192 Next: Task #${next.index + 1} "${next.description}"`;
+    }
+    else {
+        // All tasks done
+        state.currentTaskIndex = -1;
+        state.completedAt = new Date().toISOString();
+        output += "\n\n\u2713 All tasks complete. Run repl_summary to generate the results report, then proceed to the quality gate (Step 7).";
+    }
+    writeReplState(cwd, state);
+    return output;
+}
+// ─── repl_summary ────────────────────────────────────────────────────────────
+export const summary = tool({
+    description: "Generate a formatted summary of the REPL loop results for inclusion in " +
+        "the quality gate report and PR body. Call after all tasks are complete " +
+        "or when the loop is terminated.",
+    args: {},
+    async execute(args, context) {
+        const state = readReplState(context.worktree);
+        if (!state) {
+            return `\u2717 No REPL loop data found.\n\nRun repl_init to start a loop, or this may have been cleaned up already.`;
+        }
+        return formatSummary(state);
+    },
+});

package/dist/tools/task.d.ts

@@ -7,6 +7,7 @@ export declare const finalize: {
         baseBranch: import("zod").ZodOptional<import("zod").ZodString>;
         planFilename: import("zod").ZodOptional<import("zod").ZodString>;
         draft: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        issueRefs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodNumber>>;
     };
     execute(args: {
         commitMessage: string;
@@ -15,6 +16,7 @@ export declare const finalize: {
         baseBranch?: string | undefined;
         planFilename?: string | undefined;
         draft?: boolean | undefined;
+        issueRefs?: number[] | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 //# sourceMappingURL=task.d.ts.map

package/dist/tools/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"AAyGA,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;CAqNnB,CAAC"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"AA+EA,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;CA0OnB,CAAC"}

package/dist/tools/task.js

@@ -2,35 +2,12 @@ import { tool } from "@opencode-ai/plugin";
 import * as fs from "fs";
 import * as path from "path";
 import { detectWorktreeInfo } from "../utils/worktree-detect.js";
-import { findPlanContent, extractPlanSections, buildPrBodyFromPlan, } from "../utils/plan-extract.js";
-import { git, gh, which } from "../utils/shell.js";
+import { findPlanContent, extractPlanSections, extractIssueRefs, buildPrBodyFromPlan, } from "../utils/plan-extract.js";
+import { git, gh } from "../utils/shell.js";
+import { checkGhAvailability } from "../utils/github.js";
 const PROTECTED_BRANCHES = ["main", "master", "develop", "production", "staging"];
 const DOCS_DIR = "docs";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
-/**
- * Check if `gh` CLI is installed and authenticated.
- */
-async function checkGhCli(cwd) {
-    // Check if gh exists
-    const ghPath = await which("gh");
-    if (!ghPath) {
-        return {
-            ok: false,
-            error: "GitHub CLI (gh) is not installed. Install it from https://cli.github.com/ and run `gh auth login`.",
-        };
-    }
-    // Check if authenticated
-    try {
-        await gh(cwd, "auth", "status");
-    }
-    catch {
-        return {
-            ok: false,
-            error: "GitHub CLI is not authenticated. Run `gh auth login` to authenticate.",
-        };
-    }
-    return { ok: true };
-}
 /**
  * Check if a remote named "origin" is configured.
  */
@@ -117,9 +94,13 @@ export const finalize = tool({
             .boolean()
             .optional()
             .describe("Create as draft PR (default: false)"),
+        issueRefs: tool.schema
+            .array(tool.schema.number())
+            .optional()
+            .describe("GitHub issue numbers to link in PR body (adds 'Closes #N' for each)"),
     },
     async execute(args, context) {
-        const { commitMessage, prTitle, prBody: customPrBody, baseBranch: customBaseBranch, planFilename, draft = false, } = args;
+        const { commitMessage, prTitle, prBody: customPrBody, baseBranch: customBaseBranch, planFilename, draft = false, issueRefs: explicitIssueRefs, } = args;
         const cwd = context.worktree;
         const output = [];
         const warnings = [];
@@ -162,9 +143,12 @@ Create a feature/bugfix branch first with branch_create or worktree_create.`;
             output.push(`Worktree detected (main tree: ${wtInfo.mainWorktreePath})`);
         }
         // ── 4. Check prerequisites ────────────────────────────────
-        const ghCheck = await checkGhCli(cwd);
-        if (!ghCheck.ok) {
-            return `✗ ${ghCheck.error}`;
+        const ghStatus = await checkGhAvailability(cwd);
+        if (!ghStatus.installed) {
+            return "✗ GitHub CLI (gh) is not installed. Install it from https://cli.github.com/ and run `gh auth login`.";
+        }
+        if (!ghStatus.authenticated) {
+            return "✗ GitHub CLI is not authenticated. Run `gh auth login` to authenticate.";
         }
         const remoteCheck = await checkRemote(cwd);
         if (!remoteCheck.ok) {
@@ -218,6 +202,7 @@ All previous steps succeeded (changes committed). Try pushing manually:
         }
         // ── 9. Build PR body ──────────────────────────────────────
         let prBodyContent = customPrBody || "";
+        let issueRefs = explicitIssueRefs ?? [];
         if (!prBodyContent) {
             // Try to build from plan
             const plan = findPlanContent(cwd, planFilename, branchName);
@@ -225,6 +210,10 @@ All previous steps succeeded (changes committed). Try pushing manually:
                 const sections = extractPlanSections(plan.content, plan.filename);
                 prBodyContent = buildPrBodyFromPlan(sections);
                 output.push(`PR body generated from plan: ${plan.filename}`);
+                // Extract issue refs from plan frontmatter if not explicitly provided
+                if (issueRefs.length === 0) {
+                    issueRefs = extractIssueRefs(plan.content);
+                }
             }
             else {
                 // Fall back to commit log
@@ -237,6 +226,12 @@ All previous steps succeeded (changes committed). Try pushing manually:
                 }
             }
         }
+        // Append issue closing references to PR body
+        if (issueRefs.length > 0) {
+            const closingRefs = issueRefs.map((n) => `Closes #${n}`).join("\n");
+            prBodyContent += `\n\n## Linked Issues\n\n${closingRefs}`;
+            output.push(`Linked issues: ${issueRefs.map((n) => `#${n}`).join(", ")}`);
+        }
         // ── 10. Create PR via gh ──────────────────────────────────
         const finalPrTitle = prTitle || commitMessage;
         let prUrl = "";

package/dist/tools/worktree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAiBvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AACpC,KAAK,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAE9B;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;;;;;;;EAuF1C;AAED,eAAO,MAAM,IAAI;;;;CAiCf,CAAC;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;EAkI1C;AAED,eAAO,MAAM,IAAI;;;;;;;;CAgDf,CAAC;AAkUH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;;;;;;;;;;EAsIxD"}
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAiBvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AACpC,KAAK,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAE9B;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;;;;;;;EAuF1C;AAED,eAAO,MAAM,IAAI;;;;CAiCf,CAAC;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;EAkI1C;AAED,eAAO,MAAM,IAAI;;;;;;;;CAgDf,CAAC;AA8UH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;;;;;;;;;;EAsIxD"}

package/dist/tools/worktree.js

@@ -2,8 +2,8 @@ import { tool } from "@opencode-ai/plugin";
 import * as fs from "fs";
 import * as path from "path";
 import { propagatePlan } from "../utils/propagate.js";
-import { git, which, kill, spawn as shellSpawn } from "../utils/shell.js";
-import { detectDriver, closeSession, writeSession, readSession, } from "../utils/terminal.js";
+import { git, which, shellEscape, kill, spawn as shellSpawn } from "../utils/shell.js";
+import { detectTerminalDriver, closeSession, writeSession, readSession, } from "../utils/terminal.js";
 const WORKTREE_ROOT = ".worktrees";
 /**
  * Factory function that creates the worktree_create tool with access
@@ -171,8 +171,8 @@ Use worktree_list to see existing worktrees.`;
                         // PTY may already be closed
                     }
                 }
-                else if (session.mode === "terminal") {
-                    // Close terminal tab via driver
+                else if (session.mode === "terminal" || session.mode === "ide") {
+                    // Close terminal/IDE tab via driver
                     closedSession = await closeSession(session);
                 }
                 else if (session.mode === "background" && session.pid) {
@@ -351,7 +351,11 @@ async function launchTerminalTab(client, worktreePath, branchName, opencodeBin,
             // Toast failure is non-fatal
         }
     };
-    const driver = detectDriver();
+    // KEY FIX: Use multi-strategy terminal detection that NEVER returns IDE drivers.
+    // This ensures "Open in terminal tab" always opens in the user's actual terminal
+    // emulator (iTerm2, Ghostty, kitty, etc.), not in a new IDE window.
+    const detection = await detectTerminalDriver(worktreePath);
+    const driver = detection.driver;
     const opts = {
         worktreePath,
         opencodeBin,
@@ -373,13 +377,20 @@ async function launchTerminalTab(client, worktreePath, branchName, opencodeBin,
             ...result,
         };
         writeSession(worktreePath, session);
-        await notify(`Opened ${driver.name} tab with agent '${agent}'`);
-        return `✓ Opened ${driver.name} tab in worktree\n\nBranch: ${branchName}\nTerminal: ${driver.name}`;
+        const strategyNote = detection.strategy !== "env"
+            ? ` (detected via ${detection.strategy})`
+            : "";
+        await notify(`Opened ${driver.name} tab with agent '${agent}'${strategyNote}`);
+        return `✓ Opened ${driver.name} tab in worktree\n\nBranch: ${branchName}\nTerminal: ${driver.name}\nDetection: ${detection.strategy}${detection.detail ? ` — ${detection.detail}` : ""}`;
     }
     catch (error) {
         await notify(`Could not open terminal: ${error.message || error}`, "error");
-        const innerCmd = `cd "${worktreePath}" && "${opencodeBin}" --agent ${agent}`;
-        return `✗ Could not open terminal (${driver.name}). Manual command:\n  ${innerCmd}`;
+        // Escape all user-controlled inputs in the manual command to prevent injection
+        const safePath = shellEscape(worktreePath);
+        const safeBin = shellEscape(opencodeBin);
+        const safeAgent = shellEscape(agent);
+        const innerCmd = `cd "${safePath}" && "${safeBin}" --agent "${safeAgent}"`;
+        return `✗ Could not open terminal (${driver.name}, detected via ${detection.strategy}). Manual command:\n  ${innerCmd}`;
     }
 }
 // ─── Mode B: In-App PTY ─────────────────────────────────────────────────────
@@ -597,14 +608,14 @@ export function createLaunch(client, shell) {
             agent: tool.schema
                 .string()
                 .optional()
-                .describe("Agent to use in the new session (default: 'build')"),
+                .describe("Agent to use in the new session (default: 'implement')"),
             prompt: tool.schema
                 .string()
                 .optional()
                 .describe("Custom prompt for the new session (auto-generated from plan if omitted)"),
         },
         async execute(args, context) {
-            const { name, mode, plan: planFilename, agent = "build", prompt: customPrompt, } = args;
+            const { name, mode, plan: planFilename, agent = "implement", prompt: customPrompt, } = args;
             const worktreePath = path.join(context.worktree, WORKTREE_ROOT, name);
             const absoluteWorktreePath = path.resolve(worktreePath);
             // ── Validate worktree exists ───────────────────────────────

package/dist/utils/github.d.ts

@@ -0,0 +1,104 @@
+export interface GhStatus {
+    installed: boolean;
+    authenticated: boolean;
+    hasRemote: boolean;
+    repoOwner?: string;
+    repoName?: string;
+    projects: {
+        id: string;
+        number: number;
+        title: string;
+    }[];
+}
+export interface GitHubIssue {
+    number: number;
+    title: string;
+    state: string;
+    labels: string[];
+    assignees: string[];
+    milestone?: string;
+    body: string;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GitHubProjectItem {
+    id: string;
+    title: string;
+    type: "ISSUE" | "PULL_REQUEST" | "DRAFT_ISSUE";
+    status?: string;
+    assignees: string[];
+    labels: string[];
+    issueNumber?: number;
+    url?: string;
+    body?: string;
+}
+/**
+ * Check full GitHub CLI availability and repo context.
+ * Returns a status object with installation, authentication, and repo info.
+ */
+export declare function checkGhAvailability(cwd: string): Promise<GhStatus>;
+/**
+ * Parse a git remote URL to extract owner and repo name.
+ * Handles HTTPS, SSH, and GitHub CLI formats.
+ * Supports both github.com and GitHub Enterprise Server URLs (e.g., github.mycompany.com).
+ *
+ * The regex requires "github" to appear at a hostname boundary (after `//` or `@`)
+ * to prevent false positives like "notgithub.com" or "fakegithub.evil.com".
+ */
+export declare function parseRepoUrl(url: string): {
+    owner: string;
+    name: string;
+} | null;
+/**
+ * Truncate a string to the given length, appending "..." if truncated.
+ */
+export declare function truncate(str: string, maxLen: number): string;
+/**
+ * Format a single GitHub issue into a compact list entry.
+ * Used when presenting multiple issues for selection.
+ */
+export declare function formatIssueListEntry(issue: GitHubIssue): string;
+/**
+ * Format multiple issues into a numbered selection list.
+ */
+export declare function formatIssueList(issues: GitHubIssue[]): string;
+/**
+ * Format a GitHub issue into a planning-friendly markdown block.
+ * Used by the architect agent to seed plan content from selected issues.
+ */
+export declare function formatIssueForPlan(issue: GitHubIssue): string;
+/**
+ * Format a single GitHub Project item into a compact list entry.
+ */
+export declare function formatProjectItemEntry(item: GitHubProjectItem): string;
+/**
+ * Format multiple project items into a list.
+ */
+export declare function formatProjectItemList(items: GitHubProjectItem[]): string;
+/**
+ * Fetch GitHub projects associated with the repo owner.
+ */
+export declare function fetchProjects(cwd: string, owner: string): Promise<{
+    id: string;
+    number: number;
+    title: string;
+}[]>;
+/**
+ * Fetch issues from the current repository using gh CLI.
+ */
+export declare function fetchIssues(cwd: string, options?: {
+    state?: string;
+    labels?: string;
+    milestone?: string;
+    assignee?: string;
+    limit?: number;
+}): Promise<GitHubIssue[]>;
+/**
+ * Fetch project items from a specific GitHub Project.
+ */
+export declare function fetchProjectItems(cwd: string, owner: string, projectNumber: number, options?: {
+    status?: string;
+    limit?: number;
+}): Promise<GitHubProjectItem[]>;
+//# sourceMappingURL=github.d.ts.map

package/dist/utils/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../src/utils/github.ts"],"names":[],"mappings":"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"}