opencode-sdd-engram-manage 🚀

Interactive SDD model selection and profile management for opencode.

Features

1. SDD Profile Management

Manage SDD (Spec-Driven Development) profiles from gentle-ai directly from the opencode TUI.

• Create: Create an empty SDD profile for manual configuration.
• Activate: Apply a saved profile to the global runtime config instantly — no restart required. Changes are live immediately.
• Edit Models: Pick a different provider/model for any agent or fallback directly from the UI.
• Rename & Delete: Full lifecycle management for your profiles.
• Per-Agent Fallbacks: Configure a fallback model per sdd-* base agent (except sdd-orchestrator). On activation, the plugin ensures sdd-*-fallback agents exist and stay in sync with their base agent config. Primary models are applied first, so you can define new agents and their fallbacks in a single profile activation.
• Active Profile Detection: The plugin automatically detects and highlights which profile matches the current config.

Profile Format

Profiles are stored as JSON files under ~/.config/opencode/profiles/:

{
  "models": {
    "sdd-init": "openai/gpt-4o",
    "sdd-spec": "anthropic/claude-sonnet-4-6",
    "sdd-apply": "anthropic/claude-sonnet-4-6"
  },
  "fallback": {
    "sdd-init": "google/gemini-flash-2.0",
    "sdd-apply": "openai/gpt-4o-mini"
  }
}

• models: primary model per base sdd-* agent.
• fallback: optional fallback model override per base agent name. If omitted, the fallback agent inherits the base model.

Legacy flat format is also supported for backwards compatibility:

{
  "sdd-init": "openai/gpt-4o",
  "sdd-apply": "anthropic/claude-sonnet-4-6"
}

---

2. Engram Project Memories

Full integration with the Engram memory system.

• List: Browse all stored observations for the current project (resolved across git remote, git root, and cwd aliases).
• Read: View full memory content, type, scope, and timestamp.
• Delete: Logically remove a memory to prevent it from affecting the current session context.

---

Installation

Add the plugin to your tui.json:

~/.config/opencode/tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-sdd-engram-manage"]
}

---

Usage

Open the plugin with:

• Shortcut: Alt + K (Linux/Win) or Cmd + K (macOS)
• Slash command: /sdd-model

Workflow

1. Open the plugin (Alt+K / Cmd+K or /sdd-model).
2. Create a profile for your project, or Manage Profiles to activate/configure one.
3. From the profile detail, click any agent to change its model (provider → model picker).
4. Click any fallback entry to override its model.
5. Activate to apply the profile to the live runtime.

---

Screenshots

This is what users will see after installing the plugin:

Main entry and profile management

Engram memory browser

Profile JSON preview

---

Orchestrator Fallback Policy Script

This repo includes a script to ensure the sdd-orchestrator prompt contains the fallback policy block required for sdd-*-fallback agents to work correctly when a primary sub-agent fails.

• Script: scripts/ensure-orchestrator-fallback-policy.ts
• Supports: Inline prompt text in opencode.json and external {file:...} references.

# Check mode (no changes)
npm run orchestrator:fallback:check

# Apply changes
npm run orchestrator:fallback:apply

# Custom config path
node ./scripts/ensure-orchestrator-fallback-policy.ts --config /path/to/opencode.json

---

Example Fixtures & Smoke Validation

Under examples/:

• opencode-inline.json — inline orchestrator prompt config
• opencode-external.json + sdd-orchestrator-example.md — external prompt file config
• profiles/*.json — profile payloads in new and legacy formats

Run smoke validation:

npm run examples

Validates:

1. Fallback policy injection for inline and external prompt configs.
2. Profile fixture readability for new (models + fallback) and legacy formats.

---

Development

Contributing

Community PRs are welcome, but they must follow the repository review policy:

• start from a GitHub issue
• use a focused branch such as feat/short_description or fix/short_description
• keep the diff as small as possible
• justify broader changes clearly in the PR description

See CONTRIBUTING.md for the full workflow and review requirements.

Running Tests

npm test

Test coverage:

• src/profiles.test.ts — profile read/write, fallback sync, validation, activation logic
• src/memories.test.ts — memory listing, deletion, normalization, sqlite query escaping
• src/utils.test.ts — formatting helpers, agent naming predicates, model resolution
• src/config.test.ts — path resolution, XDG support, project name detection
• scripts/ensure-orchestrator-fallback-policy.test.ts — fallback policy injection logic

Automated Releases

Uses semantic-release on pushes to main. See docs/publish.md for the full publish workflow and commit conventions.

---

Technical Details

• Package: opencode-sdd-engram-manage
• Current version: see CHANGELOG.md or npm
• Requires: opencode >= 1.3.13
• Peer dependencies: @opencode-ai/plugin ^1.4.9, @opentui/core ^0.1.100, @opentui/solid ^0.1.100, solid-js
• License: MIT

Developed by j0k3r-dev-rgl.