cortex-agents 2.1.0 → 2.2.0

package/dist/cli.js

@@ -4,7 +4,7 @@ import * as path from "path";
 import { fileURLToPath } from "url";
 import prompts from "prompts";
 import { PRIMARY_AGENTS, SUBAGENTS, ALL_AGENTS, getPrimaryChoices, getSubagentChoices, } from "./registry.js";
-const VERSION = "2.1.0";
+const VERSION = "2.2.0";
 const PLUGIN_NAME = "cortex-agents";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -387,8 +387,8 @@ function status() {
 function help() {
     console.log(`${PLUGIN_NAME} v${VERSION}
 
-Cortex agents for OpenCode — agent handover notifications, mermaid documentation,
-worktree workflow, plan persistence, and session management.
+Supercharge OpenCode with structured workflows, intelligent agents,
+and automated development practices.
 
 USAGE:
   npx ${PLUGIN_NAME} <command> [options]
@@ -407,28 +407,34 @@ EXAMPLES:
   npx ${PLUGIN_NAME} configure --reset # Reset to default models
   npx ${PLUGIN_NAME} status            # Check status
 
-AGENT TIERS:
-  Primary agents (build, plan, debug):
+AGENTS:
+  Primary (build, plan, debug):
     Handle complex tasks — select your best model.
 
   Subagents (fullstack, testing, security, devops):
     Handle focused tasks — a fast/cheap model works great.
 
-INCLUDED TOOLS:
-  cortex_init, cortex_status    - .cortex directory management
-  worktree_create, worktree_list, worktree_remove, worktree_open
-  branch_create, branch_status, branch_switch
-  plan_save, plan_list, plan_load, plan_delete
-  session_save, session_list, session_load
-  docs_init, docs_save, docs_list, docs_index  - mermaid documentation
+TOOLS (22):
+  cortex_init, cortex_status      .cortex directory management
+  worktree_create, worktree_list  Git worktree management
+  worktree_remove, worktree_open
+  worktree_launch                 Launch worktree (terminal/PTY/background)
+  branch_create, branch_status    Git branch operations
+  branch_switch
+  plan_save, plan_list            Plan persistence
+  plan_load, plan_delete
+  session_save, session_list      Session management
+  session_load
+  docs_init, docs_save            Mermaid documentation
+  docs_list, docs_index
+  task_finalize                   Commit, push, and create PR
 
-FEATURES:
-  Agent handover notifications  - Toast alerts when agents switch
-  Mermaid documentation system  - Auto-prompted docs with diagrams
-
-INCLUDED SKILLS:
-  web-development, testing-strategies, security-hardening,
-  deployment-automation, code-quality, git-workflow
+SKILLS (14):
+  web-development, frontend-development, backend-development,
+  mobile-development, desktop-development, database-design,
+  api-design, architecture-patterns, design-patterns,
+  testing-strategies, security-hardening, deployment-automation,
+  performance-optimization, code-quality, git-workflow
 `);
 }
 // ─── CLI Entry Point ─────────────────────────────────────────────────────────

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAqBlD,eAAO,MAAM,YAAY,EAAE,MA8D1B,CAAC;AAGF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAsBlD,eAAO,MAAM,YAAY,EAAE,MAmE1B,CAAC;AAGF,eAAe,YAAY,CAAC"}

package/dist/index.js

@@ -5,6 +5,7 @@ import * as branch from "./tools/branch";
 import * as plan from "./tools/plan";
 import * as session from "./tools/session";
 import * as docs from "./tools/docs";
+import * as task from "./tools/task";
 // Agent descriptions for handover toast notifications
 const AGENT_DESCRIPTIONS = {
     build: "Development mode — ready to implement",
@@ -26,6 +27,8 @@ export const CortexPlugin = async (ctx) => {
             worktree_list: worktree.list,
             worktree_remove: worktree.remove,
             worktree_open: worktree.open,
+            // Dynamic tool: needs client + shell via factory (closure injection)
+            worktree_launch: worktree.createLaunch(ctx.client, ctx.$),
             // Branch tools - git branch operations
             branch_create: branch.create,
             branch_status: branch.status,
@@ -44,6 +47,8 @@ export const CortexPlugin = async (ctx) => {
             docs_save: docs.save,
             docs_list: docs.list,
             docs_index: docs.index,
+            // Task tools - finalize workflow (commit, push, PR)
+            task_finalize: task.finalize,
         },
         // Agent handover toast notifications
         async event({ event }) {

package/dist/tools/cortex.js

@@ -5,7 +5,7 @@ const CORTEX_DIR = ".cortex";
 const DEFAULT_CONFIG = {
     version: "1.0.0",
     worktree: {
-        root: "../.worktrees",
+        root: ".worktrees",
         autoCleanup: false,
     },
     branches: {

package/dist/tools/task.d.ts

@@ -0,0 +1,20 @@
+export declare const finalize: {
+    description: string;
+    args: {
+        commitMessage: import("zod").ZodString;
+        prTitle: import("zod").ZodOptional<import("zod").ZodString>;
+        prBody: import("zod").ZodOptional<import("zod").ZodString>;
+        baseBranch: import("zod").ZodOptional<import("zod").ZodString>;
+        planFilename: import("zod").ZodOptional<import("zod").ZodString>;
+        draft: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    execute(args: {
+        commitMessage: string;
+        prTitle?: string | undefined;
+        prBody?: string | undefined;
+        baseBranch?: string | undefined;
+        planFilename?: string | undefined;
+        draft?: boolean | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+//# sourceMappingURL=task.d.ts.map

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

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

package/dist/tools/task.js

@@ -0,0 +1,302 @@
+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";
+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
+    try {
+        await Bun.$ `which gh`.quiet().text();
+    }
+    catch {
+        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 Bun.$ `gh auth status`.cwd(cwd).quiet().text();
+    }
+    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.
+ */
+async function checkRemote(cwd) {
+    try {
+        const remotes = await Bun.$ `git -C ${cwd} remote -v`.quiet().text();
+        if (!remotes.includes("origin")) {
+            return {
+                ok: false,
+                error: "No 'origin' remote configured. Add one with: git remote add origin <url>",
+            };
+        }
+        return { ok: true };
+    }
+    catch {
+        return { ok: false, error: "Could not check git remotes." };
+    }
+}
+/**
+ * Check whether docs/ has any content beyond .gitkeep files.
+ */
+function checkDocsExist(worktree) {
+    const docsRoot = path.join(worktree, DOCS_DIR);
+    if (!fs.existsSync(docsRoot)) {
+        return { exists: false, count: 0 };
+    }
+    let count = 0;
+    const subDirs = ["decisions", "features", "flows"];
+    for (const sub of subDirs) {
+        const subPath = path.join(docsRoot, sub);
+        if (fs.existsSync(subPath)) {
+            const files = fs.readdirSync(subPath).filter((f) => f.endsWith(".md") && f !== ".gitkeep");
+            count += files.length;
+        }
+    }
+    return { exists: count > 0, count };
+}
+/**
+ * Get a summary of commits that will be in the PR (commits ahead of base).
+ */
+async function getCommitLog(cwd, baseBranch) {
+    try {
+        const log = await Bun.$ `git -C ${cwd} log ${baseBranch}..HEAD --oneline`.quiet().text();
+        return log.trim();
+    }
+    catch {
+        // If base branch doesn't exist locally, try origin/<base>
+        try {
+            const log = await Bun.$ `git -C ${cwd} log origin/${baseBranch}..HEAD --oneline`.quiet().text();
+            return log.trim();
+        }
+        catch {
+            return "";
+        }
+    }
+}
+// ─── Tool ────────────────────────────────────────────────────────────────────
+export const finalize = tool({
+    description: "Finalize a completed task: stage all changes, commit, push to origin, and create a PR via GitHub CLI. " +
+        "Auto-detects worktrees and targets the main branch. " +
+        "Auto-populates the PR body from .cortex/plans/ if a plan exists. " +
+        "Run docs_list and session_save BEFORE calling this tool.",
+    args: {
+        commitMessage: tool.schema
+            .string()
+            .describe("Commit message in conventional format (e.g., 'feat: add worktree launch tool')"),
+        prTitle: tool.schema
+            .string()
+            .optional()
+            .describe("PR title (defaults to the commit message)"),
+        prBody: tool.schema
+            .string()
+            .optional()
+            .describe("Custom PR body in markdown. If omitted, auto-generated from .cortex/plans/ or commit log."),
+        baseBranch: tool.schema
+            .string()
+            .optional()
+            .describe("Target branch for PR (auto-detected: 'main' for worktrees, default branch otherwise)"),
+        planFilename: tool.schema
+            .string()
+            .optional()
+            .describe("Plan filename from .cortex/plans/ to include in PR body"),
+        draft: tool.schema
+            .boolean()
+            .optional()
+            .describe("Create as draft PR (default: false)"),
+    },
+    async execute(args, context) {
+        const { commitMessage, prTitle, prBody: customPrBody, baseBranch: customBaseBranch, planFilename, draft = false, } = args;
+        const cwd = context.worktree;
+        const output = [];
+        const warnings = [];
+        // ── 1. Validate: git repo ─────────────────────────────────
+        try {
+            await Bun.$ `git -C ${cwd} rev-parse --git-dir`.quiet().text();
+        }
+        catch {
+            return "✗ Error: Not in a git repository.";
+        }
+        // ── 2. Detect worktree + branch ───────────────────────────
+        const wtInfo = await detectWorktreeInfo(cwd);
+        const branchName = wtInfo.currentBranch;
+        if (!branchName || branchName === "(unknown)") {
+            return "✗ Error: Could not determine current branch.";
+        }
+        if (PROTECTED_BRANCHES.includes(branchName)) {
+            return `✗ Error: Cannot finalize on protected branch '${branchName}'.
+Create a feature/bugfix branch first with branch_create or worktree_create.`;
+        }
+        // ── 3. Determine base branch ──────────────────────────────
+        let baseBranch = customBaseBranch || "";
+        if (!baseBranch) {
+            if (wtInfo.isWorktree) {
+                baseBranch = "main";
+            }
+            else {
+                // Try to detect default branch from origin
+                try {
+                    const defaultRef = await Bun.$ `git -C ${cwd} symbolic-ref refs/remotes/origin/HEAD`.quiet().text();
+                    baseBranch = defaultRef.trim().replace("refs/remotes/origin/", "");
+                }
+                catch {
+                    baseBranch = "main"; // Sensible default
+                }
+            }
+        }
+        output.push(`Branch: ${branchName} → ${baseBranch}`);
+        if (wtInfo.isWorktree) {
+            output.push(`Worktree detected (main tree: ${wtInfo.mainWorktreePath})`);
+        }
+        // ── 4. Check prerequisites ────────────────────────────────
+        const ghCheck = await checkGhCli(cwd);
+        if (!ghCheck.ok) {
+            return `✗ ${ghCheck.error}`;
+        }
+        const remoteCheck = await checkRemote(cwd);
+        if (!remoteCheck.ok) {
+            return `✗ ${remoteCheck.error}`;
+        }
+        // ── 5. Check docs (warning only) ─────────────────────────
+        const docsCheck = checkDocsExist(cwd);
+        if (!docsCheck.exists) {
+            warnings.push("No documentation found in docs/. Consider creating docs with docs_save before finalizing.");
+        }
+        else {
+            output.push(`Documentation: ${docsCheck.count} doc(s) found`);
+        }
+        // ── 6. Stage all changes ──────────────────────────────────
+        try {
+            await Bun.$ `git -C ${cwd} add -A`.quiet();
+        }
+        catch (error) {
+            return `✗ Error staging changes: ${error.message || error}`;
+        }
+        // ── 7. Commit ─────────────────────────────────────────────
+        let commitHash = "";
+        let commitSkipped = false;
+        try {
+            // Check if there's anything to commit
+            const status = await Bun.$ `git -C ${cwd} status --porcelain`.quiet().text();
+            if (!status.trim()) {
+                commitSkipped = true;
+                output.push("No new changes to commit (working tree clean)");
+            }
+            else {
+                await Bun.$ `git -C ${cwd} commit -m ${commitMessage}`.quiet();
+                const hash = await Bun.$ `git -C ${cwd} rev-parse --short HEAD`.quiet().text();
+                commitHash = hash.trim();
+                output.push(`Committed: ${commitHash} — ${commitMessage}`);
+            }
+        }
+        catch (error) {
+            return `✗ Error committing: ${error.message || error}`;
+        }
+        // ── 8. Push to origin ─────────────────────────────────────
+        try {
+            await Bun.$ `git -C ${cwd} push -u origin ${branchName}`.quiet();
+            output.push(`Pushed to origin/${branchName}`);
+        }
+        catch (error) {
+            return `✗ Error pushing to origin: ${error.message || error}
+
+All previous steps succeeded (changes committed). Try pushing manually:
+  git push -u origin ${branchName}`;
+        }
+        // ── 9. Build PR body ──────────────────────────────────────
+        let prBodyContent = customPrBody || "";
+        if (!prBodyContent) {
+            // Try to build from plan
+            const plan = findPlanContent(cwd, planFilename, branchName);
+            if (plan) {
+                const sections = extractPlanSections(plan.content, plan.filename);
+                prBodyContent = buildPrBodyFromPlan(sections);
+                output.push(`PR body generated from plan: ${plan.filename}`);
+            }
+            else {
+                // Fall back to commit log
+                const commitLog = await getCommitLog(cwd, baseBranch);
+                if (commitLog) {
+                    prBodyContent = `## Changes\n\n\`\`\`\n${commitLog}\n\`\`\``;
+                }
+                else {
+                    prBodyContent = `Implementation on branch \`${branchName}\``;
+                }
+            }
+        }
+        // ── 10. Create PR via gh ──────────────────────────────────
+        const finalPrTitle = prTitle || commitMessage;
+        let prUrl = "";
+        try {
+            // Check if PR already exists for this branch
+            const existingPr = await Bun.$ `gh pr view ${branchName} --json url --jq .url`
+                .cwd(cwd).quiet().nothrow().text();
+            if (existingPr.trim()) {
+                prUrl = existingPr.trim();
+                output.push(`PR already exists: ${prUrl}`);
+            }
+            else {
+                // Create new PR
+                const draftFlag = draft ? "--draft" : "";
+                // Use a heredoc-style approach via stdin to handle complex body content
+                const bodyFile = path.join(cwd, ".cortex", ".pr-body-tmp.md");
+                const cortexDir = path.join(cwd, ".cortex");
+                if (!fs.existsSync(cortexDir)) {
+                    fs.mkdirSync(cortexDir, { recursive: true });
+                }
+                fs.writeFileSync(bodyFile, prBodyContent);
+                try {
+                    const createArgs = [
+                        "gh", "pr", "create",
+                        "--base", baseBranch,
+                        "--title", finalPrTitle,
+                        "--body-file", bodyFile,
+                    ];
+                    if (draft)
+                        createArgs.push("--draft");
+                    const result = await Bun.$ `gh pr create --base ${baseBranch} --title ${finalPrTitle} --body-file ${bodyFile} ${draft ? "--draft" : ""}`.cwd(cwd).quiet().text();
+                    prUrl = result.trim();
+                    output.push(`PR created: ${prUrl}`);
+                }
+                finally {
+                    // Clean up temp file
+                    if (fs.existsSync(bodyFile)) {
+                        fs.unlinkSync(bodyFile);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // PR creation failed but everything else succeeded
+            output.push(`⚠ PR creation failed: ${error.message || error}`);
+            output.push("");
+            output.push("Changes are committed and pushed. Create the PR manually:");
+            output.push(`  gh pr create --base ${baseBranch} --title "${finalPrTitle}"`);
+        }
+        // ── Build final output ────────────────────────────────────
+        let finalOutput = `✓ Task finalized\n\n`;
+        finalOutput += output.join("\n");
+        if (warnings.length > 0) {
+            finalOutput += `\n\nWarnings:\n${warnings.map((w) => `  ⚠ ${w}`).join("\n")}`;
+        }
+        if (wtInfo.isWorktree) {
+            finalOutput += `\n\nThis is a worktree. When the PR is merged, you can clean up with:
+  worktree_remove (name: "${path.basename(cwd)}", deleteBranch: true)`;
+        }
+        return finalOutput;
+    },
+});

package/dist/tools/worktree.d.ts

@@ -1,3 +1,6 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+type Client = PluginInput["client"];
+type Shell = PluginInput["$"];
 export declare const create: {
     description: string;
     args: {
@@ -42,4 +45,33 @@ export declare const open: {
         name: string;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
+/**
+ * Factory function that creates the worktree_launch tool with access
+ * to the OpenCode client (for PTY and toast) and shell.
+ *
+ * This uses a closure to capture `client` and `shell` since ToolContext
+ * does not provide access to the OpenCode client API.
+ */
+export declare function createLaunch(client: Client, shell: Shell): {
+    description: string;
+    args: {
+        name: import("zod").ZodString;
+        mode: import("zod").ZodEnum<{
+            terminal: "terminal";
+            pty: "pty";
+            background: "background";
+        }>;
+        plan: import("zod").ZodOptional<import("zod").ZodString>;
+        agent: import("zod").ZodOptional<import("zod").ZodString>;
+        prompt: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        name: string;
+        mode: "terminal" | "pty" | "background";
+        plan?: string | undefined;
+        agent?: string | undefined;
+        prompt?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export {};
 //# sourceMappingURL=worktree.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;CA8DjB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;CAiCf,CAAC;AAEH,eAAO,MAAM,MAAM;;;;;;;;;;CA4DjB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;CAgDf,CAAC"}
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAQvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AACpC,KAAK,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAE9B,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;CA8DjB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;CAiCf,CAAC;AAEH,eAAO,MAAM,MAAM;;;;;;;;;;CA4DjB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;CAgDf,CAAC;AA4VH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;;;;;;;;;;EAoIxD"}