cortex-agents 1.0.0

package/dist/tools/branch.js

@@ -0,0 +1,176 @@
+import { tool } from "@opencode-ai/plugin";
+const PROTECTED_BRANCHES = ["main", "master", "develop", "production", "staging"];
+export const create = tool({
+    description: "Create and checkout a new git branch with proper naming convention",
+    args: {
+        name: tool.schema
+            .string()
+            .describe("Branch name slug (e.g., 'user-authentication', 'fix-login')"),
+        type: tool.schema
+            .enum(["feature", "bugfix", "hotfix", "refactor", "docs", "test", "chore"])
+            .describe("Branch type - determines prefix"),
+    },
+    async execute(args, context) {
+        const { name, type } = args;
+        const branchName = `${type}/${name}`;
+        // Check if we're in a git repository
+        try {
+            await Bun.$ `git rev-parse --git-dir`.cwd(context.worktree).text();
+        }
+        catch {
+            return "✗ Error: Not in a git repository";
+        }
+        // Check if branch already exists
+        try {
+            const branches = await Bun.$ `git branch --list ${branchName}`.cwd(context.worktree).text();
+            if (branches.trim()) {
+                return `✗ Error: Branch '${branchName}' already exists.
+
+Use branch_switch to switch to it, or choose a different name.`;
+            }
+        }
+        catch {
+            // Ignore error, branch check is optional
+        }
+        // Create and checkout the branch
+        try {
+            await Bun.$ `git checkout -b ${branchName}`.cwd(context.worktree);
+        }
+        catch (error) {
+            return `✗ Error creating branch: ${error.message || error}`;
+        }
+        return `✓ Created and switched to branch: ${branchName}
+
+You are now on branch '${branchName}'.
+Make your changes and commit when ready.`;
+    },
+});
+export const status = tool({
+    description: "Get current git branch status - branch name, uncommitted changes, and whether on protected branch",
+    args: {},
+    async execute(args, context) {
+        // Check if we're in a git repository
+        try {
+            await Bun.$ `git rev-parse --git-dir`.cwd(context.worktree).text();
+        }
+        catch {
+            return "✗ Not in a git repository";
+        }
+        let currentBranch = "";
+        let hasChanges = false;
+        let stagedChanges = false;
+        let untrackedFiles = false;
+        let isProtected = false;
+        let aheadBehind = "";
+        // Get current branch
+        try {
+            currentBranch = (await Bun.$ `git branch --show-current`.cwd(context.worktree).text()).trim();
+            if (!currentBranch) {
+                currentBranch = "(detached HEAD)";
+            }
+        }
+        catch {
+            currentBranch = "(unknown)";
+        }
+        // Check if protected
+        isProtected = PROTECTED_BRANCHES.includes(currentBranch);
+        // Check for changes
+        try {
+            const statusOutput = await Bun.$ `git status --porcelain`.cwd(context.worktree).text();
+            const lines = statusOutput.trim().split("\n").filter((l) => l);
+            for (const line of lines) {
+                const status = line.substring(0, 2);
+                if (status[0] !== " " && status[0] !== "?") {
+                    stagedChanges = true;
+                }
+                if (status[1] !== " " && status[1] !== "?") {
+                    hasChanges = true;
+                }
+                if (status === "??") {
+                    untrackedFiles = true;
+                }
+            }
+        }
+        catch {
+            // Ignore error
+        }
+        // Check ahead/behind
+        try {
+            const result = await Bun.$ `git rev-list --left-right --count HEAD...@{upstream}`.cwd(context.worktree).text();
+            const [ahead, behind] = result.trim().split(/\s+/);
+            if (parseInt(ahead) > 0 || parseInt(behind) > 0) {
+                aheadBehind = `Ahead: ${ahead}, Behind: ${behind}`;
+            }
+        }
+        catch {
+            // No upstream or error
+        }
+        // Build output
+        let output = `Git Status:
+
+Branch: ${currentBranch}`;
+        if (isProtected) {
+            output += ` ⚠️  PROTECTED`;
+        }
+        output += `\n`;
+        if (stagedChanges || hasChanges || untrackedFiles) {
+            output += `\nChanges:`;
+            if (stagedChanges)
+                output += `\n  • Staged changes (ready to commit)`;
+            if (hasChanges)
+                output += `\n  • Unstaged changes`;
+            if (untrackedFiles)
+                output += `\n  • Untracked files`;
+        }
+        else {
+            output += `\nWorking tree clean.`;
+        }
+        if (aheadBehind) {
+            output += `\n\n${aheadBehind}`;
+        }
+        if (isProtected) {
+            output += `\n
+⚠️  You are on a protected branch (${currentBranch}).
+    Consider creating a feature/bugfix branch before making changes.
+    Use branch_create or worktree_create.`;
+        }
+        return output;
+    },
+});
+export const switch_ = tool({
+    description: "Switch to an existing git branch",
+    args: {
+        branch: tool.schema.string().describe("Branch name to switch to"),
+    },
+    async execute(args, context) {
+        const { branch } = args;
+        // Check if branch exists
+        try {
+            const branches = await Bun.$ `git branch --list ${branch}`.cwd(context.worktree).text();
+            if (!branches.trim()) {
+                // Try remote branch
+                const remoteBranches = await Bun.$ `git branch -r --list origin/${branch}`.cwd(context.worktree).text();
+                if (!remoteBranches.trim()) {
+                    return `✗ Error: Branch '${branch}' not found locally or on origin.
+
+Use branch_create to create a new branch.`;
+                }
+            }
+        }
+        catch {
+            // Ignore error, try checkout anyway
+        }
+        // Switch to branch
+        try {
+            await Bun.$ `git checkout ${branch}`.cwd(context.worktree);
+        }
+        catch (error) {
+            return `✗ Error switching branch: ${error.message || error}
+
+You may have uncommitted changes. Commit or stash them first.`;
+        }
+        return `✓ Switched to branch: ${branch}`;
+    },
+});
+// Export with underscore suffix to avoid reserved word
+export { switch_ as switch };

package/dist/tools/cortex.d.ts

@@ -0,0 +1,11 @@
+export declare const init: {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export declare const status: {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+//# sourceMappingURL=cortex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cortex.d.ts","sourceRoot":"","sources":["../../src/tools/cortex.ts"],"names":[],"mappings":"AAmEA,eAAO,MAAM,IAAI;;;;CAkDf,CAAC;AAEH,eAAO,MAAM,MAAM;;;;CAyDjB,CAAC"}

package/dist/tools/cortex.js

@@ -0,0 +1,149 @@
+import { tool } from "@opencode-ai/plugin";
+import * as fs from "fs";
+import * as path from "path";
+const CORTEX_DIR = ".cortex";
+const DEFAULT_CONFIG = {
+    $schema: "https://k2p5.dev/cortex-config.json",
+    version: "1.0.0",
+    worktree: {
+        root: "../.worktrees",
+        autoCleanup: false,
+    },
+    branches: {
+        protected: ["main", "master", "develop"],
+        defaultType: "feature",
+    },
+    plans: {
+        namingPattern: "{date}-{type}-{slug}",
+        includeMermaid: true,
+    },
+    sessions: {
+        retention: 30,
+        includeDecisions: true,
+    },
+};
+const GITIGNORE_CONTENT = `# Keep plans (they're valuable documentation)
+!plans/
+
+# Ignore session files (local context)
+sessions/
+
+# Ignore local config overrides
+config.local.json
+`;
+const README_CONTENT = `# .cortex
+
+This directory contains project context for the K2P5 development agents.
+
+## Structure
+
+- \`plans/\` - Saved implementation plans (version controlled)
+- \`sessions/\` - Session summaries (gitignored)
+- \`config.json\` - Project configuration
+
+## Plans
+
+Plans are saved by the Plan agent and can be loaded by Build/Debug agents.
+They include:
+- Architecture diagrams (mermaid)
+- Task breakdowns
+- Technical decisions
+
+## Sessions
+
+Session summaries capture key decisions made during development.
+They are gitignored by default but can be kept if needed.
+
+## Usage
+
+The K2P5 agents will automatically use this directory for:
+- Saving implementation plans before coding
+- Recording session summaries with key decisions
+- Managing worktree and branch workflows
+`;
+export const init = tool({
+    description: "Initialize .cortex directory in project root for plan storage, session history, and configuration",
+    args: {},
+    async execute(args, context) {
+        const cortexPath = path.join(context.worktree, CORTEX_DIR);
+        const plansPath = path.join(cortexPath, "plans");
+        const sessionsPath = path.join(cortexPath, "sessions");
+        // Check if already exists
+        if (fs.existsSync(cortexPath)) {
+            const hasConfig = fs.existsSync(path.join(cortexPath, "config.json"));
+            const hasPlans = fs.existsSync(plansPath);
+            const hasSessions = fs.existsSync(sessionsPath);
+            if (hasConfig && hasPlans && hasSessions) {
+                return `✓ .cortex directory already initialized at ${cortexPath}`;
+            }
+        }
+        // Create directories
+        fs.mkdirSync(plansPath, { recursive: true });
+        fs.mkdirSync(sessionsPath, { recursive: true });
+        // Create config.json
+        fs.writeFileSync(path.join(cortexPath, "config.json"), JSON.stringify(DEFAULT_CONFIG, null, 2));
+        // Create .gitignore
+        fs.writeFileSync(path.join(cortexPath, ".gitignore"), GITIGNORE_CONTENT);
+        // Create README.md
+        fs.writeFileSync(path.join(cortexPath, "README.md"), README_CONTENT);
+        // Create .gitkeep in plans to ensure it's tracked
+        fs.writeFileSync(path.join(plansPath, ".gitkeep"), "");
+        return `✓ Initialized .cortex directory at ${cortexPath}
+
+Created:
+- .cortex/config.json (configuration)
+- .cortex/plans/ (implementation plans)
+- .cortex/sessions/ (session summaries)
+- .cortex/.gitignore (ignores sessions, keeps plans)
+- .cortex/README.md (documentation)
+
+Plans will be version controlled. Sessions are gitignored by default.`;
+    },
+});
+export const status = tool({
+    description: "Check .cortex directory status - whether it exists, plan count, session count",
+    args: {},
+    async execute(args, context) {
+        const cortexPath = path.join(context.worktree, CORTEX_DIR);
+        if (!fs.existsSync(cortexPath)) {
+            return `✗ .cortex directory not found at ${cortexPath}
+
+Run cortex_init to initialize.`;
+        }
+        const plansPath = path.join(cortexPath, "plans");
+        const sessionsPath = path.join(cortexPath, "sessions");
+        let planCount = 0;
+        let sessionCount = 0;
+        let recentPlans = [];
+        let recentSessions = [];
+        if (fs.existsSync(plansPath)) {
+            const plans = fs
+                .readdirSync(plansPath)
+                .filter((f) => f.endsWith(".md"))
+                .sort()
+                .reverse();
+            planCount = plans.length;
+            recentPlans = plans.slice(0, 3);
+        }
+        if (fs.existsSync(sessionsPath)) {
+            const sessions = fs
+                .readdirSync(sessionsPath)
+                .filter((f) => f.endsWith(".md"))
+                .sort()
+                .reverse();
+            sessionCount = sessions.length;
+            recentSessions = sessions.slice(0, 3);
+        }
+        let output = `✓ .cortex directory found at ${cortexPath}
+
+Plans: ${planCount}`;
+        if (recentPlans.length > 0) {
+            output += `\n  Recent: ${recentPlans.join(", ")}`;
+        }
+        output += `\n\nSessions: ${sessionCount}`;
+        if (recentSessions.length > 0) {
+            output += `\n  Recent: ${recentSessions.join(", ")}`;
+        }
+        return output;
+    },
+});

package/dist/tools/plan.d.ts

@@ -0,0 +1,59 @@
+export declare const save: {
+    description: string;
+    args: {
+        title: import("zod").ZodString;
+        type: import("zod").ZodEnum<{
+            feature: "feature";
+            bugfix: "bugfix";
+            refactor: "refactor";
+            spike: "spike";
+            docs: "docs";
+            architecture: "architecture";
+        }>;
+        content: import("zod").ZodString;
+        tasks: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+    };
+    execute(args: {
+        title: string;
+        type: "feature" | "bugfix" | "refactor" | "spike" | "docs" | "architecture";
+        content: string;
+        tasks?: string[] | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export declare const list: {
+    description: string;
+    args: {
+        type: import("zod").ZodOptional<import("zod").ZodEnum<{
+            feature: "feature";
+            bugfix: "bugfix";
+            refactor: "refactor";
+            spike: "spike";
+            docs: "docs";
+            architecture: "architecture";
+            all: "all";
+        }>>;
+    };
+    execute(args: {
+        type?: "feature" | "bugfix" | "refactor" | "spike" | "docs" | "architecture" | "all" | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export declare const load: {
+    description: string;
+    args: {
+        filename: import("zod").ZodString;
+    };
+    execute(args: {
+        filename: string;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export declare const delete_: {
+    description: string;
+    args: {
+        filename: import("zod").ZodString;
+    };
+    execute(args: {
+        filename: string;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export { delete_ as delete };
+//# sourceMappingURL=plan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;CA2Df,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;CAkEf,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;CAuBf,CAAC;AAEH,eAAO,MAAM,OAAO;;;;;;;;CAkBlB,CAAC;AAGH,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC"}

package/dist/tools/plan.js

@@ -0,0 +1,177 @@
+import { tool } from "@opencode-ai/plugin";
+import * as fs from "fs";
+import * as path from "path";
+const CORTEX_DIR = ".cortex";
+const PLANS_DIR = "plans";
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .substring(0, 50);
+}
+function getDatePrefix() {
+    const now = new Date();
+    return now.toISOString().split("T")[0]; // YYYY-MM-DD
+}
+function ensureCortexDir(worktree) {
+    const cortexPath = path.join(worktree, CORTEX_DIR);
+    const plansPath = path.join(cortexPath, PLANS_DIR);
+    if (!fs.existsSync(plansPath)) {
+        fs.mkdirSync(plansPath, { recursive: true });
+    }
+    return plansPath;
+}
+export const save = tool({
+    description: "Save an implementation plan to .cortex/plans/ with mermaid diagram support",
+    args: {
+        title: tool.schema.string().describe("Plan title (e.g., 'User Authentication System')"),
+        type: tool.schema
+            .enum(["feature", "bugfix", "refactor", "architecture", "spike", "docs"])
+            .describe("Plan type"),
+        content: tool.schema
+            .string()
+            .describe("Full plan content in markdown (can include mermaid diagrams)"),
+        tasks: tool.schema
+            .array(tool.schema.string())
+            .optional()
+            .describe("Optional list of tasks"),
+    },
+    async execute(args, context) {
+        const { title, type, content, tasks } = args;
+        const plansPath = ensureCortexDir(context.worktree);
+        const datePrefix = getDatePrefix();
+        const slug = slugify(title);
+        const filename = `${datePrefix}-${type}-${slug}.md`;
+        const filepath = path.join(plansPath, filename);
+        // Build frontmatter
+        const frontmatter = `---
+title: "${title}"
+type: ${type}
+created: ${new Date().toISOString()}
+status: draft
+---
+
+`;
+        // Build task list if provided
+        let taskSection = "";
+        if (tasks && tasks.length > 0) {
+            taskSection = `\n## Tasks\n\n${tasks.map((t) => `- [ ] ${t}`).join("\n")}\n`;
+        }
+        // Combine content
+        const fullContent = frontmatter + `# ${title}\n\n` + content + taskSection;
+        // Write file
+        fs.writeFileSync(filepath, fullContent);
+        return `✓ Plan saved successfully
+
+File: ${filename}
+Path: ${filepath}
+
+The plan includes:
+- Title: ${title}
+- Type: ${type}
+- Tasks: ${tasks?.length || 0}
+
+You can load this plan later with plan_load or view all plans with plan_list.`;
+    },
+});
+export const list = tool({
+    description: "List all saved plans in .cortex/plans/",
+    args: {
+        type: tool.schema
+            .enum(["feature", "bugfix", "refactor", "architecture", "spike", "docs", "all"])
+            .optional()
+            .describe("Filter by plan type (default: all)"),
+    },
+    async execute(args, context) {
+        const { type = "all" } = args;
+        const plansPath = path.join(context.worktree, CORTEX_DIR, PLANS_DIR);
+        if (!fs.existsSync(plansPath)) {
+            return `No plans found. The .cortex/plans/ directory doesn't exist.
+
+Use plan_save to create your first plan, or cortex_init to initialize the directory.`;
+        }
+        const files = fs
+            .readdirSync(plansPath)
+            .filter((f) => f.endsWith(".md") && f !== ".gitkeep")
+            .sort()
+            .reverse();
+        if (files.length === 0) {
+            return "No plans found in .cortex/plans/";
+        }
+        let output = "📋 Saved Plans:\n\n";
+        for (const file of files) {
+            const filepath = path.join(plansPath, file);
+            const content = fs.readFileSync(filepath, "utf-8");
+            // Parse frontmatter
+            let title = file;
+            let planType = "unknown";
+            let created = "";
+            let status = "draft";
+            const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+            if (frontmatterMatch) {
+                const fm = frontmatterMatch[1];
+                const titleMatch = fm.match(/title:\s*"?([^"\n]+)"?/);
+                const typeMatch = fm.match(/type:\s*(\w+)/);
+                const createdMatch = fm.match(/created:\s*(\S+)/);
+                const statusMatch = fm.match(/status:\s*(\w+)/);
+                if (titleMatch)
+                    title = titleMatch[1];
+                if (typeMatch)
+                    planType = typeMatch[1];
+                if (createdMatch)
+                    created = createdMatch[1].split("T")[0];
+                if (statusMatch)
+                    status = statusMatch[1];
+            }
+            // Filter by type if specified
+            if (type !== "all" && planType !== type) {
+                continue;
+            }
+            output += `• ${title}\n`;
+            output += `  File: ${file}\n`;
+            output += `  Type: ${planType} | Created: ${created} | Status: ${status}\n\n`;
+        }
+        return output.trim();
+    },
+});
+export const load = tool({
+    description: "Load a saved plan by filename",
+    args: {
+        filename: tool.schema.string().describe("Plan filename (e.g., '2024-02-22-feature-auth.md')"),
+    },
+    async execute(args, context) {
+        const { filename } = args;
+        const plansPath = path.join(context.worktree, CORTEX_DIR, PLANS_DIR);
+        const filepath = path.join(plansPath, filename);
+        if (!fs.existsSync(filepath)) {
+            return `✗ Plan not found: ${filename}
+
+Use plan_list to see available plans.`;
+        }
+        const content = fs.readFileSync(filepath, "utf-8");
+        return `📋 Plan: ${filename}
+${"=".repeat(50)}
+
+${content}`;
+    },
+});
+export const delete_ = tool({
+    description: "Delete a saved plan",
+    args: {
+        filename: tool.schema.string().describe("Plan filename to delete"),
+    },
+    async execute(args, context) {
+        const { filename } = args;
+        const plansPath = path.join(context.worktree, CORTEX_DIR, PLANS_DIR);
+        const filepath = path.join(plansPath, filename);
+        if (!fs.existsSync(filepath)) {
+            return `✗ Plan not found: ${filename}`;
+        }
+        fs.unlinkSync(filepath);
+        return `✓ Deleted plan: ${filename}`;
+    },
+});
+// Export with underscore suffix to avoid reserved word
+export { delete_ as delete };

package/dist/tools/session.d.ts

@@ -0,0 +1,36 @@
+export declare const save: {
+    description: string;
+    args: {
+        summary: import("zod").ZodString;
+        decisions: import("zod").ZodArray<import("zod").ZodString>;
+        filesChanged: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        relatedPlan: import("zod").ZodOptional<import("zod").ZodString>;
+        branch: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        summary: string;
+        decisions: string[];
+        filesChanged?: string[] | undefined;
+        relatedPlan?: string | undefined;
+        branch?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export declare const list: {
+    description: string;
+    args: {
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        limit?: number | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export declare const load: {
+    description: string;
+    args: {
+        filename: import("zod").ZodString;
+    };
+    execute(args: {
+        filename: string;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/tools/session.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;CAsFf,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;CA8Df,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;CAuBf,CAAC"}