cortex-agents 1.0.0

package/.opencode/skills/web-development/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: web-development
+description: Full-stack web development patterns, best practices, and architectural guidance for modern web applications
+license: Apache-2.0
+compatibility: opencode
+---
+
+# Web Development Skill
+
+This skill provides comprehensive guidance for building modern web applications.
+
+## When to Use
+
+Use this skill when:
+- Starting a new web project
+- Adding features to existing web apps
+- Refactoring frontend or backend code
+- Designing APIs
+- Choosing technology stack
+
+## Frontend Architecture
+
+### Component Design
+- Single Responsibility Principle
+- Composition over inheritance
+- Controlled vs uncontrolled components
+- Container/Presentational pattern
+- Custom hooks for reusable logic
+
+### State Management
+- Local state (useState, useReducer)
+- Global state (Redux, Zustand, Context)
+- Server state (React Query, SWR)
+- Form state (React Hook Form)
+- URL state (React Router)
+
+### Performance Optimization
+- Memoization (useMemo, useCallback, React.memo)
+- Code splitting and lazy loading
+- Virtualization for long lists
+- Image optimization
+- Bundle size monitoring
+
+### Styling Approaches
+- CSS-in-JS (styled-components, emotion)
+- Utility-first CSS (Tailwind)
+- CSS Modules
+- SCSS/Sass
+- CSS Variables for theming
+
+## Backend Architecture
+
+### API Design
+- RESTful principles
+- GraphQL schema design
+- Versioning strategies
+- Pagination patterns
+- Filtering and sorting
+
+### Database Patterns
+- Repository pattern
+- Unit of Work
+- CQRS (Command Query Responsibility Segregation)
+- Event sourcing
+- Database migrations
+
+### Authentication & Authorization
+- JWT implementation
+- Session-based auth
+- OAuth 2.0 / OpenID Connect
+- Role-based access control
+- API key management
+
+### Error Handling
+- Consistent error responses
+- HTTP status codes
+- Error logging and monitoring
+- User-friendly error messages
+- Retry strategies
+
+## Fullstack Patterns
+
+### Data Flow
+- Unidirectional data flow
+- State normalization
+- Optimistic updates
+- Real-time updates (WebSockets, SSE)
+- Offline-first architecture
+
+### Security
+- Input validation and sanitization
+- Output encoding
+- CSRF protection
+- Content Security Policy
+- Secure headers
+
+### Testing Strategy
+- Unit tests for business logic
+- Integration tests for APIs
+- Component tests for UI
+- E2E tests for critical paths
+- Visual regression testing
+
+## Technology Recommendations
+
+### Frontend Stacks
+- React + TypeScript + Vite + Tailwind
+- Vue 3 + TypeScript + Vite + Pinia
+- Next.js (fullstack React)
+- SvelteKit
+
+### Backend Stacks
+- Node.js + Express/Fastify/NestJS
+- Python + FastAPI/Django
+- Go + Gin/Echo
+- Rust + Actix/Axum
+
+### Databases
+- PostgreSQL (relational)
+- MongoDB (document)
+- Redis (cache/sessions)
+- Elasticsearch (search)

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2024 OpenCode K2P5 Agents Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,172 @@
+# cortex-agents
+
+Enhanced agents for [OpenCode](https://opencode.ai) with k2p5 model, worktree workflow, and plan persistence.
+
+## Features
+
+- **Pre-implementation workflow**: Build and Debug agents ask about branch/worktree before making changes
+- **Plan persistence**: Plans saved to `.cortex/plans/` with mermaid diagrams
+- **Session summaries**: Key decisions recorded in `.cortex/sessions/`
+- **Worktree support**: Create isolated worktrees in `../.worktrees/` for parallel development
+- **Agent handoff**: Plan agent hands off to Build/Debug with user confirmation
+
+## Installation
+
+### Option 1: Add to config (Recommended)
+
+Add the plugin to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["cortex-agents"]
+}
+```
+
+OpenCode will auto-install via Bun at startup.
+
+### Option 2: Use the CLI helper
+
+```bash
+npx cortex-agents install
+```
+
+This adds the plugin to your global `~/.config/opencode/opencode.json`.
+
+### Option 3: Global npm install
+
+```bash
+npm install -g cortex-agents
+cortex-agents install
+```
+
+## CLI Commands
+
+```bash
+npx cortex-agents install    # Add to opencode.json config
+npx cortex-agents uninstall  # Remove from config
+npx cortex-agents status     # Check installation status
+npx cortex-agents help       # Show help
+```
+
+## Agents
+
+### Primary Agents
+
+| Agent | Description |
+|-------|-------------|
+| **build** | Full-access development with branch/worktree workflow |
+| **plan** | Read-only analysis with plan persistence and handoff |
+| **debug** | Deep troubleshooting with hotfix workflow |
+
+### Subagents (@mention)
+
+| Agent | Description |
+|-------|-------------|
+| **@fullstack** | End-to-end feature implementation |
+| **@testing** | Test writing and coverage analysis |
+| **@security** | Security audit and vulnerability detection |
+| **@devops** | CI/CD and deployment automation |
+
+## Tools
+
+All tools are bundled with the plugin and available automatically.
+
+### Cortex Management
+- `cortex_init` - Initialize `.cortex` directory
+- `cortex_status` - Check cortex status
+
+### Branch Management
+- `branch_create` - Create feature/bugfix/hotfix branch
+- `branch_status` - Get current branch and status
+- `branch_switch` - Switch to existing branch
+
+### Worktree Management
+- `worktree_create` - Create worktree in `../.worktrees/`
+- `worktree_list` - List all worktrees
+- `worktree_remove` - Remove worktree
+- `worktree_open` - Get command to open terminal in worktree
+
+### Plan Management
+- `plan_save` - Save plan to `.cortex/plans/`
+- `plan_list` - List saved plans
+- `plan_load` - Load a plan
+- `plan_delete` - Delete a plan
+
+### Session Management
+- `session_save` - Save session summary with decisions
+- `session_list` - List recent sessions
+- `session_load` - Load a session summary
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| **web-development** | Full-stack patterns and best practices |
+| **testing-strategies** | Comprehensive testing approaches |
+| **security-hardening** | Security best practices |
+| **deployment-automation** | CI/CD and infrastructure |
+| **code-quality** | Refactoring and maintainability |
+| **git-workflow** | Branching and worktree workflows |
+
+## Workflow Example
+
+### Feature Development
+
+```
+1. User: "I want to add user authentication"
+
+2. Plan Agent:
+   - Analyzes codebase
+   - Creates plan with mermaid diagrams
+   - Saves to .cortex/plans/2024-02-22-feature-user-auth.md
+   - Asks: "Plan saved. Switch to Build agent?"
+
+3. User: "Yes"
+
+4. Build Agent:
+   - Loads plan from .cortex/plans/
+   - Checks git status (on main)
+   - Asks: "Create branch or worktree?"
+   - User: "Create branch"
+   - Creates feature/user-authentication
+   - Implements following the plan
+   - Saves session summary with decisions
+```
+
+## .cortex Directory
+
+```
+<project-root>/
+└── .cortex/
+    ├── config.json         # Project configuration
+    ├── .gitignore          # Ignores sessions, keeps plans
+    ├── plans/              # Implementation plans (git tracked)
+    │   └── YYYY-MM-DD-type-slug.md
+    └── sessions/           # Session summaries (gitignored)
+        └── YYYY-MM-DD-session-id.md
+```
+
+## Branch Naming
+
+| Type | Prefix | Example |
+|------|--------|---------|
+| Feature | `feature/` | `feature/user-authentication` |
+| Bugfix | `bugfix/` | `bugfix/login-validation` |
+| Hotfix | `hotfix/` | `hotfix/security-patch` |
+| Refactor | `refactor/` | `refactor/api-cleanup` |
+| Docs | `docs/` | `docs/api-reference` |
+
+## Configuration
+
+Default model: `kimi-for-coding/k2p5`
+
+## Requirements
+
+- OpenCode >= 1.0.0
+- Node.js >= 18.0.0
+- Git (for branch/worktree features)
+
+## License
+
+Apache-2.0

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import * as fs from "fs";
+import * as path from "path";
+const VERSION = "2.1.0";
+const PLUGIN_NAME = "cortex-agents";
+function findOpencodeConfig() {
+    // Check local first
+    const localPath = path.join(process.cwd(), "opencode.json");
+    if (fs.existsSync(localPath)) {
+        return { path: localPath, isGlobal: false };
+    }
+    // Check global
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+    const globalPath = path.join(homeDir, ".config", "opencode", "opencode.json");
+    if (fs.existsSync(globalPath)) {
+        return { path: globalPath, isGlobal: true };
+    }
+    return null;
+}
+function readConfig(configPath) {
+    try {
+        const content = fs.readFileSync(configPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+function writeConfig(configPath, config) {
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+function install() {
+    console.log(`Installing ${PLUGIN_NAME} v${VERSION}...\n`);
+    const configInfo = findOpencodeConfig();
+    if (!configInfo) {
+        // Create global config
+        const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+        const globalDir = path.join(homeDir, ".config", "opencode");
+        const globalPath = path.join(globalDir, "opencode.json");
+        if (!fs.existsSync(globalDir)) {
+            fs.mkdirSync(globalDir, { recursive: true });
+        }
+        const newConfig = {
+            $schema: "https://opencode.ai/config.json",
+            plugin: [PLUGIN_NAME],
+        };
+        writeConfig(globalPath, newConfig);
+        console.log(`Created global config: ${globalPath}`);
+        console.log(`Added plugin: ${PLUGIN_NAME}`);
+        console.log("\nRestart OpenCode to load the plugin.");
+        return;
+    }
+    const config = readConfig(configInfo.path);
+    // Ensure plugin array exists
+    if (!config.plugin) {
+        config.plugin = [];
+    }
+    // Check if already installed
+    if (config.plugin.includes(PLUGIN_NAME)) {
+        console.log(`Plugin already installed in ${configInfo.isGlobal ? "global" : "local"} config.`);
+        console.log(`Config: ${configInfo.path}`);
+        return;
+    }
+    // Add plugin
+    config.plugin.push(PLUGIN_NAME);
+    writeConfig(configInfo.path, config);
+    console.log(`Added plugin to ${configInfo.isGlobal ? "global" : "local"} config.`);
+    console.log(`Config: ${configInfo.path}`);
+    console.log("\nRestart OpenCode to load the plugin.");
+}
+function uninstall() {
+    console.log(`Uninstalling ${PLUGIN_NAME}...\n`);
+    const configInfo = findOpencodeConfig();
+    if (!configInfo) {
+        console.log("No OpenCode config found. Nothing to uninstall.");
+        return;
+    }
+    const config = readConfig(configInfo.path);
+    if (!config.plugin || !config.plugin.includes(PLUGIN_NAME)) {
+        console.log("Plugin not found in config. Nothing to uninstall.");
+        return;
+    }
+    // Remove plugin
+    config.plugin = config.plugin.filter((p) => p !== PLUGIN_NAME);
+    writeConfig(configInfo.path, config);
+    console.log(`Removed plugin from ${configInfo.isGlobal ? "global" : "local"} config.`);
+    console.log(`Config: ${configInfo.path}`);
+    console.log("\nRestart OpenCode to apply changes.");
+}
+function status() {
+    console.log(`${PLUGIN_NAME} v${VERSION}\n`);
+    const configInfo = findOpencodeConfig();
+    if (!configInfo) {
+        console.log("Status: NOT INSTALLED");
+        console.log("\nNo OpenCode config found.");
+        console.log("Run 'npx cortex-agents install' to set up.");
+        return;
+    }
+    const config = readConfig(configInfo.path);
+    const isInstalled = config.plugin?.includes(PLUGIN_NAME);
+    console.log(`Status: ${isInstalled ? "INSTALLED" : "NOT INSTALLED"}`);
+    console.log(`Config: ${configInfo.path} (${configInfo.isGlobal ? "global" : "local"})`);
+    if (isInstalled) {
+        console.log("\nPlugin is configured. OpenCode will auto-install via Bun at startup.");
+        console.log("\nIncluded components:");
+        console.log("  - 5 tool modules (cortex, worktree, branch, plan, session)");
+        console.log("  - 7 agents (build, plan, debug, fullstack, testing, security, devops)");
+        console.log("  - 6 skills (web-dev, testing, security, deployment, code-quality, git-workflow)");
+    }
+    else {
+        console.log("\nRun 'npx cortex-agents install' to add to config.");
+    }
+}
+function help() {
+    console.log(`${PLUGIN_NAME} v${VERSION}
+
+Enhanced agents for OpenCode with k2p5 model, worktree workflow, and plan persistence.
+
+USAGE:
+  npx ${PLUGIN_NAME} <command>
+
+COMMANDS:
+  install     Add plugin to opencode.json config
+  uninstall   Remove plugin from opencode.json config
+  status      Show plugin installation status
+  help        Show this help message
+
+EXAMPLES:
+  npx ${PLUGIN_NAME} install    # Add to config (OpenCode auto-installs)
+  npx ${PLUGIN_NAME} status     # Check if installed
+
+MANUAL INSTALLATION:
+  Add to your opencode.json:
+  {
+    "plugin": ["${PLUGIN_NAME}"]
+  }
+
+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
+
+INCLUDED AGENTS:
+  @build    - Pre-implementation workflow with branch/worktree prompts
+  @plan     - Create and save implementation plans with mermaid diagrams
+  @debug    - Pre-fix workflow with hotfix worktree support
+
+For more info: https://github.com/your-org/${PLUGIN_NAME}
+`);
+}
+// Parse command
+const command = process.argv[2] || "help";
+switch (command) {
+    case "install":
+        install();
+        break;
+    case "uninstall":
+        uninstall();
+        break;
+    case "status":
+        status();
+        break;
+    case "help":
+    case "--help":
+    case "-h":
+        help();
+        break;
+    default:
+        console.error(`Unknown command: ${command}`);
+        console.error("Run 'npx cortex-agents help' for usage.");
+        process.exit(1);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const K2P5AgentsPlugin: Plugin;
+export default K2P5AgentsPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AASlD,eAAO,MAAM,gBAAgB,EAAE,MAsC9B,CAAC;AAGF,eAAe,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,42 @@
+// Import all tool modules
+import * as cortex from "./tools/cortex";
+import * as worktree from "./tools/worktree";
+import * as branch from "./tools/branch";
+import * as plan from "./tools/plan";
+import * as session from "./tools/session";
+export const K2P5AgentsPlugin = async ({ client }) => {
+    await client.app.log({
+        body: {
+            service: "k2p5-agents",
+            level: "info",
+            message: "K2P5 Agents Plugin v2.1.0 initialized - tools, agents, and skills loaded",
+        },
+    });
+    return {
+        tool: {
+            // Cortex tools - .cortex directory management
+            cortex_init: cortex.init,
+            cortex_status: cortex.status,
+            // Worktree tools - git worktree management
+            worktree_create: worktree.create,
+            worktree_list: worktree.list,
+            worktree_remove: worktree.remove,
+            worktree_open: worktree.open,
+            // Branch tools - git branch operations
+            branch_create: branch.create,
+            branch_status: branch.status,
+            branch_switch: branch.switch_,
+            // Plan tools - implementation plan persistence
+            plan_save: plan.save,
+            plan_list: plan.list,
+            plan_load: plan.load,
+            plan_delete: plan.delete_,
+            // Session tools - session summaries with decisions
+            session_save: session.save,
+            session_list: session.list,
+            session_load: session.load,
+        },
+    };
+};
+// Default export for OpenCode plugin system
+export default K2P5AgentsPlugin;

package/dist/plugin.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":""}

package/dist/plugin.js

@@ -0,0 +1,3 @@
+"use strict";
+// Plugin configuration logic can be added here if needed
+// The agents and skills are auto-discovered from .opencode/ directory

package/dist/tools/branch.d.ts

@@ -0,0 +1,35 @@
+export declare const create: {
+    description: string;
+    args: {
+        name: import("zod").ZodString;
+        type: import("zod").ZodEnum<{
+            feature: "feature";
+            bugfix: "bugfix";
+            hotfix: "hotfix";
+            refactor: "refactor";
+            docs: "docs";
+            test: "test";
+            chore: "chore";
+        }>;
+    };
+    execute(args: {
+        name: string;
+        type: "feature" | "bugfix" | "hotfix" | "refactor" | "docs" | "test" | "chore";
+    }, 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>;
+};
+export declare const switch_: {
+    description: string;
+    args: {
+        branch: import("zod").ZodString;
+    };
+    execute(args: {
+        branch: string;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export { switch_ as switch };
+//# sourceMappingURL=branch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch.d.ts","sourceRoot":"","sources":["../../src/tools/branch.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;CA8CjB,CAAC;AAEH,eAAO,MAAM,MAAM;;;;CAiGjB,CAAC;AAEH,eAAO,MAAM,OAAO;;;;;;;;CAmClB,CAAC;AAGH,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC"}