Skip to content
Open
Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
335ecdc
feat: add scope-aware framework bootstrap
papastanb Apr 13, 2026
bd8ca07
fix: address review findings
papastanb Apr 13, 2026
59f76bd
docs: add API docstrings
papastanb Apr 13, 2026
df3c97e
fix: address requested review changes
papastanb Apr 13, 2026
65cac00
fix: prevent uninstall from deleting pre-existing adopted files
papastanb Apr 13, 2026
70ec485
fix: address all CodeRabbit and Devin review findings
papastanb Apr 13, 2026
1506280
fix: harden framework bootstrap config handling
papastanb Apr 14, 2026
f4717a9
docs: add framework bootstrap docstrings
papastanb Apr 14, 2026
56af76c
fix: address remaining PR review findings
papastanb Apr 14, 2026
99ece10
fix: align remaining PR review feedback
papastanb Apr 14, 2026
3e9c6a3
fix: address remaining devin review findings
papastanb Apr 14, 2026
0ba3354
fix: tighten final framework edge cases
papastanb Apr 14, 2026
86340b1
fix: preserve config entries during bootstrap updates
papastanb Apr 14, 2026
a1bfe5f
fix: address remaining review edge cases
papastanb Apr 15, 2026
ccd5107
docs: add project index and roadmap ignores
papastanb Apr 15, 2026
e2bdd6f
fix: validate config drift and malformed bootstrap configs
papastanb Apr 15, 2026
3c3ba2d
refactor: harden framework config utilities
papastanb Apr 15, 2026
3298d43
fix: preserve ownership boundaries during uninstall
papastanb Apr 15, 2026
44cd7c4
chore: ignore local backlog and reflection notes
papastanb Apr 15, 2026
cd583d7
refactor: remove dead code and unused imports
papastanb Apr 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 1 addition & 20 deletions .opencode/plugins/super-opencode.ts
Original file line number Diff line number Diff line change
@@ -1,20 +1 @@
import type { Plugin } from "@opencode-ai/plugin"
import { createCommandHooks } from "./super-opencode/commands.js"
import { createCompactionHooks } from "./super-opencode/compaction.js"
import { createSystemHooks } from "./super-opencode/system.js"

export const SuperOpenCodePlugin: Plugin = async ({ client, worktree }) => {
await client.app.log({
body: {
service: "super-opencode",
level: "info",
message: "Super OpenCode plugin initialized",
},
})

return {
...createSystemHooks(),
...createCommandHooks(),
...createCompactionHooks(worktree),
}
}
export { SuperOpenCodePlugin } from "../../src/runtime/plugin.js"
31 changes: 1 addition & 30 deletions .opencode/plugins/super-opencode/commands.ts
Original file line number Diff line number Diff line change
@@ -1,30 +1 @@
import { commandPersistenceHint } from './memory.js'

const persistenceCommands = new Set(['sc-pm', 'sc-save', 'sc-load', 'sc-reflect'])
const checkpointCommands = new Set(['sc-save', 'sc-spawn', 'sc-workflow'])

export const createCommandHooks = () => ({
'command.execute.before': async (input: { command: string; sessionID: string }, output: { parts: unknown[] }) => {
const normalized = input.command.replace(/^\//, '')

if (persistenceCommands.has(normalized)) {
output.parts.push({
id: 'super-opencode-persistence-hint',
sessionID: input.sessionID,
messageID: '',
type: 'text',
text: commandPersistenceHint,
})
}

if (checkpointCommands.has(normalized) && normalized !== 'sc-save') {
output.parts.push({
id: 'super-opencode-checkpoint-hint',
sessionID: input.sessionID,
messageID: '',
type: 'text',
text: 'Consider using `/sc-save` to create a checkpoint before proceeding with long operations.',
})
}
},
})
export { createCommandHooks } from "../../../src/runtime/hooks.js"
15 changes: 1 addition & 14 deletions .opencode/plugins/super-opencode/compaction.ts
Original file line number Diff line number Diff line change
@@ -1,14 +1 @@
import { persistenceContract, autoCheckpointHint } from './memory.js'

export const createCompactionHooks = (worktree: string) => ({
'experimental.session.compacting': async (_input: unknown, output: { context: string[] }) => {
output.context.push(
[
'## Super OpenCode Memory',
`Worktree: ${worktree}`,
autoCheckpointHint,
persistenceContract,
].join('\n'),
)
},
})
export { createCompactionHooks } from "../../../src/runtime/hooks.js"
18 changes: 1 addition & 17 deletions .opencode/plugins/super-opencode/memory.ts
Original file line number Diff line number Diff line change
@@ -1,17 +1 @@
export const persistenceContract = [
'Serena is the persistence source of truth for this project.',
'Use Serena memory keys `pm_context`, `current_plan`, `last_session`, `next_actions`, `checkpoint`, `decision`, and `summary` when relevant.',
'For hierarchical task tracking: plan_[timestamp], phase_[1-5], task_[phase].[number], todo_[task].[number], checkpoint_[timestamp].',
'When Serena is unavailable, state clearly that the session is operating in degraded persistence mode.',
].join(' ')

export const commandPersistenceHint = [
'For `/sc-pm`, `/sc-save`, `/sc-load`, and `/sc-reflect`, prefer Serena memory tools first.',
'For complex tasks: write_memory("plan_[timestamp]", goal_statement) → write_memory("phase_X", milestone) → write_memory("task_X.Y", deliverable).',
'Use repo files only for public, durable documentation; keep session continuity in Serena rather than committed scratch files.',
].join(' ')

export const autoCheckpointHint = [
'Consider creating a checkpoint with `/sc-save` every 30 minutes for long operations.',
'Use `/sc-pm` to summarize current progress before pausing.',
].join(' ')
export { autoCheckpointHint, commandPersistenceHint, persistenceContract } from "../../../src/runtime/memory.js"
8 changes: 1 addition & 7 deletions .opencode/plugins/super-opencode/system.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1 @@
import { persistenceContract } from './memory.js'

export const createSystemHooks = () => ({
'experimental.chat.system.transform': async (_input: unknown, output: { system: string[] }) => {
output.system.push(persistenceContract)
},
})
export { createSystemHooks } from "../../../src/runtime/hooks.js"
73 changes: 58 additions & 15 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,14 @@

## Overview

Super OpenCode is an npm-installable OpenCode plugin package.
Super OpenCode is a bi-target npm-installable OpenCode plugin package.

It packages a plugin runtime plus bundled command prompts, agent prompts, mode skills, and instruction files that together port key SuperClaude workflow ideas into the OpenCode ecosystem.
It packages:

- a server runtime plugin for hooks
- a TUI plugin for Plugin Manager visibility, bootstrap UI, and diagnostics
- a shared manifest-driven bootstrap engine
- bundled command prompts, agent prompts, mode skills, and instruction files

At runtime, the high-level flow is:

Expand Down Expand Up @@ -58,41 +63,79 @@ These provide minimal but explicit support for the corresponding SuperClaude-ins

### Plugin Layer

Lives in `.opencode/plugins/`.
The runtime plugin is published through the npm package `./server` target.

The local repo also keeps `.opencode/plugins/` wrappers for self-hosting during framework development, but the installer does not copy those plugin source files into user projects by default.

The plugin layer provides local behavior for:
The runtime layer provides:

- persistence guidance
- command hints
- compaction/checkpoint hints
- shared runtime glue
- duplicate-load protection so hooks stay single-active even if npm and local plugin copies coexist

### TUI Layer

The TUI target is published through `./tui`.

It is responsible for:

- Plugin Manager visibility
- first-load bootstrap prompting
- scope selection (`global` or `project`)
- install/status/update/uninstall UI
- final bootstrap reporting

### Bootstrap Layer

The shared bootstrap engine is the product-critical layer for installation correctness.

It is manifest-driven and used by:

- the npm TUI plugin
- the CLI entrypoint
- future maintenance flows

It handles:

This is the runtime plugin layer exposed by the npm package, not just internal repo code.
- scope resolution
- asset sync for commands, agents, skills, and instructions
- `opencode.json` merge for plugin, instructions, and MCP config
- `tui.json` merge for TUI plugin registration
- MCP prerequisite diagnostics
- managed-file hashes for idempotent update and safe uninstall

### MCP Layer

Configured through `opencode.json` in the consuming project.
Configured through `opencode.json` in the chosen scope.

Expected strategy:
Current policy:

- `serena`: required for the full persistence workflow
- `context7`: recommended
- `sequential`: recommended
- `playwright`, `chrome-devtools`, `tavily`, `morph`: optional
- `serena`: enabled only when `uvx` is available
- `context7`: enabled only when `CONTEXT7_API_KEY` is present
- `sequential`: enabled only when `npx` is available
- `playwright`: enabled only when `npx` is available
- `chrome-devtools`: enabled only when `npx` is available
- `tavily`: enabled only when `npx` and `TAVILY_API_KEY` are present
- `morph`: enabled only when `npx` and `MORPH_API_KEY` are present

Super OpenCode is designed to degrade gracefully when optional MCPs are absent. Serena is the main exception because it underpins the intended persistence model.

## Published Package Surface

The npm package publishes the plugin runtime and bundled assets:
The npm package publishes:

- `./server`
- `./tui`
- the shared bootstrap engine
- `framework.manifest.json`
- `.opencode/commands/**/*.md`
- `.opencode/agents/**/*.md`
- `.opencode/skills/**/SKILL.md`
- `.opencode/plugins/**/*.ts`
- `.opencode/examples/*.json`
- `.opencode/instructions/*.md`
- installer script and package metadata
- the CLI wrapper and package metadata

Repo-internal planning and memory files are not part of the public package contract.

Expand All @@ -102,7 +145,7 @@ Repo-internal planning and memory files are not part of the public package contr
- Bun 1.3.9+
- OpenCode

The public contract is intentionally modest: the package ships an OpenCode plugin runtime together with bundled `/sc-*` assets, and does not rely on a standalone executable runtime of its own.
The public contract is now explicit: the package ships an OpenCode server plugin, an OpenCode TUI plugin, and a bootstrap engine that materializes the framework assets into either global or project scope.

## Design Principles

Expand Down
91 changes: 51 additions & 40 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,18 @@
4. Press `Shift+I` to install from npm.
5. Enter `super-opencode-framework`.

This is the preferred path when you want to install the package as an OpenCode plugin from the editor UX.
This is the preferred path when you want to install the package from the OpenCode UX.

What this installs:
What happens now:

- the npm plugin package itself
- the runtime plugin hooks exported by the package
- the bundled `/sc-*` commands, agents, skills, plugin files, and runtime instruction files that ship with the package
1. OpenCode installs the npm package.
2. Plugin Manager sees the package because it exposes both `./server` and `./tui`.
3. The TUI bootstrap asks you to confirm `project` or `global` scope.
4. The bootstrap syncs commands, agents, skills, instructions, `opencode.json`, and `tui.json` for that scope.
5. MCP config is merged and validated.
6. A final report explains what was installed, updated, skipped, or blocked.

If you want those bundled assets materialized as local files in your project, use the manual sync flow below.

## Manual Install And Local Asset Sync
## Manual Install And Bootstrap

### 1. Install The Package

Expand All @@ -47,55 +48,71 @@ npm install -D super-opencode-framework
With Bun:

```bash
bunx super-opencode-framework install
bunx super-opencode-framework install --scope project
bunx super-opencode-framework install --scope global
```

With npm:

```bash
npx super-opencode-framework install
npx super-opencode-framework install --scope project
npx super-opencode-framework install --scope global
```

Optional flags:
Maintenance commands:

With Bun:

```bash
bunx super-opencode-framework install --target /path/to/project
bunx super-opencode-framework install --force
bunx super-opencode-framework status --scope project
bunx super-opencode-framework update --scope project
bunx super-opencode-framework uninstall --scope project
bunx super-opencode-framework install --scope project --force
bunx super-opencode-framework install --scope global --force
```

With npm:

```bash
npx super-opencode-framework install --target /path/to/project
npx super-opencode-framework install --force
npx super-opencode-framework status --scope project
npx super-opencode-framework update --scope project
npx super-opencode-framework uninstall --scope project
npx super-opencode-framework install --scope project --force
npx super-opencode-framework install --scope global --force
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

### 3. Verify Your Project Config

The sync command copies the bundled OpenCode assets into your project and updates `opencode.json` when it already exists.
### 3. Scope Behavior

Review these locations after installation:
Project scope writes only to the current repository:

- `.opencode/commands`
- `.opencode/agents`
- `.opencode/skills`
- `.opencode/plugins`
- `.opencode/instructions/opencode-core.md`
- `.opencode/instructions`
- `opencode.json`
- `tui.json`

### 4. Configure MCPs
Global scope writes only to the OpenCode global config directory:

Super OpenCode expects Serena for the full persistence workflow.
- `~/.config/opencode/commands`
- `~/.config/opencode/agents`
- `~/.config/opencode/skills`
- `~/.config/opencode/instructions`
- `~/.config/opencode/opencode.json`
- `~/.config/opencode/tui.json`

Recommended MCP strategy:
The scope is always explicit. If both global and project are installed, project assets override global assets.

### 4. Configure MCPs

- `serena`: enabled
- `context7`: optional, recommended
- `sequential`: optional, recommended
- `playwright`, `chrome-devtools`, `tavily`, `morph`: optional
The bootstrap always merges framework MCP definitions into `opencode.json` and evaluates prerequisites before enabling them.

Check the example config in `.opencode/examples/opencode.example.json`.
Reported states:

- `configured and enabled`
- `configured but disabled by missing env`
- `configured but disabled by missing binary`
- `configured but requires auth/manual setup`

### 5. Start OpenCode

Expand Down Expand Up @@ -127,28 +144,22 @@ If Node.js 24+ or Bun is missing, install them first and rerun the installer.

### No `opencode.json` In The Target Project

The sync command can copy the bundled assets without `opencode.json`, but it cannot update instructions automatically.

Add this path manually to your OpenCode config:

```json
{
"instructions": [".opencode/instructions/opencode-core.md"]
}
```
The bootstrap creates `opencode.json` and `tui.json` when they do not already exist.

### Re-Sync The Bundled Assets

With Bun:

```bash
bunx super-opencode-framework install --force
bunx super-opencode-framework update --scope project
bunx super-opencode-framework install --scope project --force
```

With npm:

```bash
npx super-opencode-framework install --force
npx super-opencode-framework update --scope project
npx super-opencode-framework install --scope project --force
```

### Validate The Package Locally
Expand Down
Loading