@bluelovers/opencode-arise 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 opencode-arise contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+# opencode-arise
+
+> ⚔️ **ARISE!** A Solo Leveling themed orchestrator harness for OpenCode
+
+[![npm version](https://img.shields.io/npm/v/opencode-arise.svg)](https://www.npmjs.com/package/opencode-arise)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight, token-efficient orchestrator layer that extends [OpenCode](https://opencode.ai) with a shadow army of specialized AI agents. Inspired by Solo Leveling's Shadow Monarch, Sung Jinwoo.
+
+## Features
+
+- **Shadow Army** - 7 specialized agents for different tasks
+- **Smart Delegation** - Monarch orchestrates with minimal token usage
+- **Parallel Execution** - Background tasks for concurrent exploration
+- **Quality-Safe Output** - Never truncates errors or stack traces
+- **Configurable** - Customize models, disable shadows, tweak behavior
+
+## Installation
+
+```bash
+bunx opencode-arise install
+```
+
+This registers the plugin with OpenCode and creates a default config.
+
+**Verify installation:**
+```bash
+bunx opencode-arise doctor
+```
+
+## Quick Start
+
+After installation, just run OpenCode as usual:
+
+```bash
+opencode
+```
+
+You'll see the "ARISE!" banner, and the **Monarch** becomes your default agent. Talk naturally - the Monarch decides when to delegate to shadows.
+
+```
+You: "Find all React components using useState and add error boundaries"
+
+Monarch: "I'll have Beru scout the codebase, then Igris implement the changes."
+```
+
+## Shadow Army
+
+| Shadow | Role | Best For |
+|--------|------|----------|
+| 👑 **monarch** | Shadow Monarch | Orchestration, delegation decisions |
+| 🐜 **beru** | Ant King Scout | Fast codebase exploration, grep, file discovery |
+| ⚔️ **igris** | Loyal Knight | Precise implementation, code changes |
+| 🎖️ **bellion** | Grand Marshal | Strategic planning, architecture analysis |
+| 🎨 **tusk** | Creative Shadow | UI/UX, frontend, styling |
+| 🛡️ **tank** | Research Shadow | External docs, web search, examples |
+| 👁️ **shadow-sovereign** | Full Power | Deep reasoning, complex debugging |
+
+### Direct Summoning
+
+You can bypass the Monarch and summon shadows directly:
+
+```
+@beru find all TODO comments in src/
+
+@bellion plan a migration from REST to GraphQL
+
+@shadow-sovereign why is this recursive function causing a stack overflow?
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                        USER                              │
+│                          │                               │
+│                          ▼                               │
+│    ┌─────────────────────────────────────────────────┐  │
+│    │                👑 MONARCH                        │  │
+│    │           (Primary Orchestrator)                 │  │
+│    │                                                  │  │
+│    │     Assesses task → Delegates or handles        │  │
+│    └──────────────────────┬──────────────────────────┘  │
+│                           │                              │
+│       ┌───────┬───────────┼───────────┬───────┐         │
+│       ▼       ▼           ▼           ▼       ▼         │
+│     🐜      ⚔️          🎖️          🛡️      👁️        │
+│    BERU   IGRIS      BELLION       TANK   SOVEREIGN    │
+│    scout  implement    plan       research  reason      │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Monarch's Principles:**
+1. Assess intent before acting - don't over-delegate
+2. Handle trivial tasks directly
+3. Use parallel background tasks for exploration
+4. Only summon shadow-sovereign for complex problems
+5. Verify changes work before declaring done
+
+## Custom Tools
+
+The plugin provides these tools to the Monarch:
+
+| Tool | Description |
+|------|-------------|
+| `arise_summon` | Invoke a shadow (sync or background) |
+| `arise_background` | Launch parallel background task |
+| `arise_background_output` | Get result from background task |
+| `arise_background_status` | List all background tasks |
+| `arise_background_cancel` | Cancel a running task |
+
+## Hooks
+
+| Hook | Description |
+|------|-------------|
+| `arise-banner` | Shows "ARISE!" toast on session start |
+| `output-shaper` | Quality-safe output truncation (preserves errors) |
+| `compaction-preserver` | Preserves critical context during session compaction |
+| `todo-enforcer` | Reminds about incomplete TODOs on session idle |
+
+## Configuration
+
+Create `~/.config/opencode/opencode-arise.json`:
+
+```json
+{
+  "show_banner": true,
+  "disabled_shadows": [],
+  "disabled_hooks": [],
+  "agents": {
+    "monarch": {
+      "model": "opencode/big-pickle"
+    },
+    "beru": {
+      "model": "opencode/big-pickle"
+    },
+    "igris": {
+      "model": "opencode/big-pickle"
+    },
+    "bellion": {
+      "model": "opencode/big-pickle"
+    },
+    "tusk": {
+      "model": "opencode/big-pickle"
+    },
+    "tank": {
+      "model": "opencode/big-pickle"
+    },
+    "shadow-sovereign": {
+      "model": "opencode/big-pickle"
+    }
+  },
+  "output_shaping": {
+    "max_chars": 12000,
+    "preserve_errors": true
+  },
+  "compaction": {
+    "threshold_percent": 80,
+    "preserve_todos": true
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `show_banner` | boolean | `true` | Show "ARISE!" toast on session start |
+| `banner_every_session` | boolean | `false` | Show banner for every session (not just first) |
+| `disabled_shadows` | string[] | `[]` | Shadows to disable (e.g., `["tusk", "tank"]`) |
+| `disabled_hooks` | string[] | `[]` | Hooks to disable |
+| `agents.<name>.model` | string | varies | Override model for a shadow |
+| `agents.<name>.disabled` | boolean | `false` | Disable specific shadow |
+| `output_shaping.max_chars` | number | `12000` | Max output length before truncation |
+| `output_shaping.preserve_errors` | boolean | `true` | Never truncate error outputs |
+| `compaction.threshold_percent` | number | `80` | Context threshold for compaction |
+| `compaction.preserve_todos` | boolean | `true` | Keep TODOs during compaction |
+
+### Project-Level Config
+
+You can also create `.opencode/opencode-arise.json` in your project root. Project config merges with (and overrides) global config.
+
+## Default Models
+
+| Shadow | Default Model |
+|--------|---------------|
+| monarch | `anthropic/claude-opus-4-5` |
+| beru | `anthropic/claude-haiku-4-5` |
+| igris | `zai-coding-plan/glm-4.7` |
+| bellion | `openai/gpt-5.2` |
+| tusk | `google/gemini-3-pro-preview` |
+| tank | `zai-coding-plan/glm-4.7` |
+| shadow-sovereign | `openai/gpt-5.2` (high reasoning) |
+
+## Examples
+
+### Parallel Codebase Exploration
+
+```
+You: "I need to understand how authentication works and find security best practices"
+
+Monarch: *launches beru (codebase) and tank (research) in background*
+         "Beru is exploring the auth implementation while Tank researches
+          security best practices. I'll compile their findings."
+```
+
+### Complex Refactoring
+
+```
+You: "Refactor the payment module to use the new Stripe API"
+
+Monarch: "This requires planning. Let me consult Bellion first."
+
+Bellion: *analyzes codebase, creates migration plan*
+
+Monarch: "Bellion's plan looks good. Igris will implement it step by step."
+
+Igris: *implements changes, runs tests after each step*
+```
+
+### Deep Debugging
+
+```
+You: "This async function is causing race conditions but I can't figure out why"
+
+Monarch: "This needs deep analysis. Summoning the Shadow Sovereign."
+
+Shadow-Sovereign: *deep reasoning analysis*
+                  "The issue is a closure capturing a stale reference..."
+```
+
+## Uninstall
+
+Remove from OpenCode config:
+
+```bash
+# Edit ~/.config/opencode/opencode.json
+# Remove "opencode-arise" from the "plugin" array
+```
+
+Or manually:
+```bash
+# Remove config
+rm ~/.config/opencode/opencode-arise.json
+```
+
+## Requirements
+
+- [OpenCode](https://opencode.ai) CLI installed
+- [Bun](https://bun.sh) runtime (v1.0.0+)
+
+## Philosophy
+
+- **Minimal sufficient delegation** - Don't over-delegate simple tasks
+- **Parallel exploration** - Use background tasks for concurrent scouting
+- **Quality-safe truncation** - Never lose errors, tracebacks, or critical output
+- **Token efficiency** - Lean prompts, smart delegation patterns
+
+## Contributing
+
+Contributions are welcome! Please read the contributing guidelines first.
+
+```bash
+# Clone the repo
+git clone https://github.com/moinulmoin/opencode-arise.git
+cd opencode-arise
+
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Build
+bun run build
+```
+
+## License
+
+[MIT](LICENSE) © moinulmoin
+
+---
+
+<p align="center">
+  <i>"I alone level up."</i> - Sung Jinwoo
+</p>

package/assets/arise-banner.txt

@@ -0,0 +1,13 @@
+
+    ╔═══════════════════════════════════════════════════════╗
+    ║                                                       ║
+    ║               ⚔️  A R I S E !  ⚔️                     ║
+    ║                                                       ║
+    ║         ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░           ║
+    ║         ░░    Shadow Army Assembled    ░░░           ║
+    ║         ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░           ║
+    ║                                                       ║
+    ║   Monarch ready. Shadows await your command.          ║
+    ║                                                       ║
+    ╚═══════════════════════════════════════════════════════╝
+

package/dist/agents/index.d.ts

@@ -0,0 +1 @@
+export { SHADOW_AGENTS, OPENCODE_OVERRIDES, type ShadowAgent } from "./shadows";

package/dist/agents/index.js

@@ -0,0 +1,2 @@
+export { SHADOW_AGENTS, OPENCODE_OVERRIDES } from "./shadows";
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAoB,MAAM,WAAW,CAAC"}

package/dist/agents/shadows.d.ts

@@ -0,0 +1,28 @@
+export interface ShadowAgent {
+    name: string;
+    description: string;
+    mode: "primary" | "subagent" | "all";
+    model: string;
+    steps: number;
+    prompt?: string;
+    permission?: Record<string, "allow" | "deny" | "ask">;
+    options?: Record<string, unknown>;
+}
+export declare const SHADOW_AGENTS: Record<string, ShadowAgent>;
+export declare const OPENCODE_OVERRIDES: {
+    build: {
+        mode: "all";
+        model: string;
+    };
+    plan: {
+        mode: "all";
+        model: string;
+    };
+    explore: {
+        description: string;
+        hidden: boolean;
+    };
+    general: {
+        hidden: boolean;
+    };
+};

package/dist/agents/shadows.js

@@ -0,0 +1,182 @@
+export const SHADOW_AGENTS = {
+    monarch: {
+        name: "monarch",
+        description: "Shadow Monarch - Orchestrator (Sung Jinwoo)",
+        mode: "primary",
+        model: "anthropic/claude-opus-4-5",
+        steps: 16,
+        prompt: `You are the Shadow Monarch (opencode-arise).
+
+Your role: Interpret user requests and delegate to your shadow army with MINIMAL SUFFICIENT effort.
+
+## Your Shadows (invoke via @mention or arise_summon tool)
+- @beru - Fastest scout. Codebase exploration, file discovery, pattern search.
+- @igris - Loyal knight. Implementation, code changes, running commands.
+- @bellion - Grand Marshal. Complex planning, architecture analysis.
+- @tusk - Creative specialist. UI/UX, frontend work.
+- @tank - Research shadow. External docs, web search, examples.
+- @shadow-sovereign - Full power. Deep reasoning, recovery after failures.
+
+## Tools
+- arise_summon: Invoke a shadow synchronously or in background
+- arise_background: Launch shadow as background task (parallel)
+- arise_background_output: Get result from background task
+- arise_background_status: List all background tasks
+- task: OpenCode's built-in for complex multi-step delegation
+
+## Principles
+1. Assess intent before acting. Don't over-delegate.
+2. For trivial tasks, handle directly without summoning shadows.
+3. Keep a short TODO list. Mark items in_progress → completed.
+4. Use background tasks for parallel exploration (beru, tank).
+5. Only summon @shadow-sovereign when stuck or for complex architecture.
+6. Verify changes work before declaring done.
+
+ARISE and lead your shadows to victory.`,
+    },
+    beru: {
+        name: "beru",
+        description: "Ant King - Fastest codebase scout",
+        mode: "subagent",
+        model: "anthropic/claude-haiku-4-5",
+        steps: 12,
+        permission: {
+            edit: "deny",
+            write: "deny",
+        },
+        prompt: `You are Beru, the Ant King shadow - fastest scout in the shadow army.
+
+Your role: Rapidly explore the codebase. Find files, patterns, and answer questions about code structure.
+
+Tools you excel at: glob, grep, read, list.
+You CANNOT edit files - report findings back to the Monarch.
+
+Be thorough but fast. Search multiple patterns if needed. Return clear, actionable findings.`,
+    },
+    igris: {
+        name: "igris",
+        description: "Loyal Knight - Precise implementation",
+        mode: "subagent",
+        model: "zai-coding-plan/glm-4.7",
+        steps: 20,
+        prompt: `You are Igris, the loyal knight shadow - precise and reliable implementer.
+
+Your role: Execute code changes with precision. Edit files, run commands, verify results.
+
+Principles:
+1. Make minimal, focused changes.
+2. Follow existing code patterns.
+3. Verify changes with appropriate commands (tests, typecheck, lint).
+4. Report results clearly to the Monarch.
+
+Execute with honor.`,
+    },
+    bellion: {
+        name: "bellion",
+        description: "Grand Marshal - Strategy and planning",
+        mode: "subagent",
+        model: "openai/gpt-5.2",
+        steps: 12,
+        permission: {
+            edit: "deny",
+            write: "deny",
+            bash: "ask",
+        },
+        prompt: `You are Bellion, Grand Marshal of the shadow army - master strategist.
+
+Your role: Analyze complex problems and create detailed plans. You do NOT implement - you plan.
+
+Output format:
+1. Problem analysis
+2. Proposed approach (with alternatives if relevant)
+3. Step-by-step plan
+4. Risks and mitigations
+5. Files likely to be touched
+
+Think deeply, plan carefully.`,
+    },
+    tusk: {
+        name: "tusk",
+        description: "Creative shadow - UI/UX specialist",
+        mode: "subagent",
+        model: "google/gemini-3-pro-preview",
+        steps: 18,
+        prompt: `You are Tusk, the creative shadow - UI/UX and frontend specialist.
+
+Your role: Handle all visual and frontend work. Components, styling, layouts, animations.
+
+Principles:
+1. Follow existing design patterns and component libraries.
+2. Ensure accessibility (aria labels, keyboard nav).
+3. Keep styling consistent with the codebase.
+4. Test visual changes where possible.
+
+Create with artistry.`,
+    },
+    tank: {
+        name: "tank",
+        description: "Research shadow - External knowledge gatherer",
+        mode: "subagent",
+        model: "zai-coding-plan/glm-4.7",
+        steps: 18,
+        permission: {
+            edit: "deny",
+            write: "deny",
+        },
+        prompt: `You are Tank, the research shadow - gatherer of external knowledge.
+
+Your role: Find information from outside the codebase. Documentation, examples, best practices.
+
+You have access to: web search, web fetch, MCP tools, deepwiki.
+
+Return findings in a structured format:
+1. Source (URL/doc)
+2. Key information
+3. How it applies to the current task
+4. Code examples if relevant
+
+Research thoroughly, report concisely.`,
+    },
+    "shadow-sovereign": {
+        name: "shadow-sovereign",
+        description: "Full power mode - Deep reasoning and recovery",
+        mode: "subagent",
+        model: "openai/gpt-5.2",
+        steps: 24,
+        options: {
+            reasoningEffort: "high",
+        },
+        permission: {
+            edit: "deny",
+            write: "deny",
+        },
+        prompt: `You are the Shadow Sovereign - the Monarch's full power manifestation.
+
+You are summoned only for:
+1. Complex architectural decisions
+2. Debugging after multiple failed attempts
+3. Deep analysis requiring extended reasoning
+
+Think deeply. Consider all angles. Provide comprehensive analysis with clear recommendations.
+
+Your wisdom guides the shadow army through the most challenging battles.`,
+    },
+};
+export const OPENCODE_OVERRIDES = {
+    build: {
+        mode: "all",
+        model: "zai-coding-plan/glm-4.7",
+    },
+    plan: {
+        mode: "all",
+        model: "anthropic/claude-opus-4-5",
+    },
+    explore: {
+        description: "OpenCode explore (use @beru for arise)",
+        hidden: true,
+    },
+    general: {
+        hidden: true,
+    },
+};
+//# sourceMappingURL=shadows.js.map

package/dist/agents/shadows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadows.js","sourceRoot":"","sources":["../../src/agents/shadows.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,aAAa,GAAgC;IACxD,OAAO,EAAE;QACP,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,6CAA6C;QAC1D,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,2BAA2B;QAClC,KAAK,EAAE,EAAE;QACT,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;wCA2B4B;KACrC;IAED,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,mCAAmC;QAChD,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,4BAA4B;QACnC,KAAK,EAAE,EAAE;QACT,UAAU,EAAE;YACV,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,MAAM;SACd;QACD,MAAM,EAAE;;;;;;;6FAOiF;KAC1F;IAED,KAAK,EAAE;QACL,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,uCAAuC;QACpD,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,yBAAyB;QAChC,KAAK,EAAE,EAAE;QACT,MAAM,EAAE;;;;;;;;;;oBAUQ;KACjB;IAED,OAAO,EAAE;QACP,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,uCAAuC;QACpD,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,gBAAgB;QACvB,KAAK,EAAE,EAAE;QACT,UAAU,EAAE;YACV,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,MAAM;YACb,IAAI,EAAE,KAAK;SACZ;QACD,MAAM,EAAE;;;;;;;;;;;8BAWkB;KAC3B;IAED,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,oCAAoC;QACjD,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,6BAA6B;QACpC,KAAK,EAAE,EAAE;QACT,MAAM,EAAE;;;;;;;;;;sBAUU;KACnB;IAED,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,+CAA+C;QAC5D,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,yBAAyB;QAChC,KAAK,EAAE,EAAE;QACT,UAAU,EAAE;YACV,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,MAAM;SACd;QACD,MAAM,EAAE;;;;;;;;;;;;uCAY2B;KACpC;IAED,kBAAkB,EAAE;QAClB,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,+CAA+C;QAC5D,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,gBAAgB;QACvB,KAAK,EAAE,EAAE;QACT,OAAO,EAAE;YACP,eAAe,EAAE,MAAM;SACxB;QACD,UAAU,EAAE;YACV,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,MAAM;SACd;QACD,MAAM,EAAE;;;;;;;;;yEAS6D;KACtE;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE;QACL,IAAI,EAAE,KAAc;QACpB,KAAK,EAAE,yBAAyB;KACjC;IACD,IAAI,EAAE;QACJ,IAAI,EAAE,KAAc;QACpB,KAAK,EAAE,2BAA2B;KACnC;IACD,OAAO,EAAE;QACP,WAAW,EAAE,wCAAwC;QACrD,MAAM,EAAE,IAAI;KACb;IACD,OAAO,EAAE;QACP,MAAM,EAAE,IAAI;KACb;CACF,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};