Stride for OpenCode

Task lifecycle skills, custom subagents, and automatic hook execution for Stride kanban — adapted for OpenCode.

This plugin provides three things:

1. A TypeScript plugin that intercepts Stride API calls and runs .stride.md hooks automatically (via tool.execute.before / tool.execute.after events).
2. Seven skills (stride-workflow orchestrator plus six phase-specific skills) loaded into .opencode/skills/ and invoked via OpenCode's native skill tool.
3. Four subagents (task-explorer, task-reviewer, task-decomposer, hook-diagnostician) loaded into .opencode/agents/ and invoked via @mention in chat.

Installation

Installation is two separate steps — the plugin and the skills/agents are distributed in the same repository but loaded by OpenCode through different mechanisms.

Step 1 — Install the plugin (for automatic hook execution)

Add the plugin to your project's opencode.json or global ~/.config/opencode/opencode.json:

{
  "plugin": ["github:cheezy/stride-opencode"]
}

OpenCode installs plugins automatically using Bun at startup, caching them under ~/.cache/opencode/node_modules/. See OpenCode's plugins docs for details.

npm package status: The opencode-stride npm package is not currently published. Use the github:cheezy/stride-opencode reference above. If you need pinning, add a ref: github:cheezy/stride-opencode#v1.4.0 (branch, tag, or commit SHA). OpenCode's docs only document npm package names in "plugin", but Bun resolves github:owner/repo references as npm-install targets, so this works.

Alternatively, if you prefer not to auto-install, clone the repo into a local plugin directory:

# Project-local plugin
git clone https://github.com/cheezy/stride-opencode.git .opencode/plugins/stride-opencode

# Or user-global plugin
git clone https://github.com/cheezy/stride-opencode.git ~/.config/opencode/plugins/stride-opencode

Step 2 — Install the skills and subagents (for the workflow itself)

Important: OpenCode does NOT auto-discover skills or agents from inside an installed plugin. They must live on disk at the documented paths below, regardless of whether the plugin is installed via github: or locally.

Clone the repo and copy the skills/agents into your project:

# Clone once somewhere
git clone https://github.com/cheezy/stride-opencode.git /tmp/stride-opencode

# Copy the 7 skills (each is a directory with a SKILL.md)
mkdir -p .opencode/skills
cp -R /tmp/stride-opencode/skills/. .opencode/skills/

# Copy the 4 subagent markdown files
mkdir -p .opencode/agents
cp /tmp/stride-opencode/agents/*.md .opencode/agents/

# Copy the project-level AGENTS.md (orientation for the main agent)
cp /tmp/stride-opencode/AGENTS.md AGENTS.md

For a global install (available to every project), mirror the same copy into ~/.config/opencode/:

mkdir -p ~/.config/opencode/skills ~/.config/opencode/agents
cp -R /tmp/stride-opencode/skills/. ~/.config/opencode/skills/
cp /tmp/stride-opencode/agents/*.md ~/.config/opencode/agents/

Per OpenCode's skills docs, skills are also discovered from .claude/skills/ and .agents/skills/ — so a project that already uses the Claude Code stride plugin will pick these up from the same .claude/skills/ directory without a separate copy.

Step 3 — Create the Stride config files (one-time per project)

Create .stride_auth.md and .stride.md at your project root (see Setup below).

Setup

Before using the plugin, create two configuration files in your project root.

1. .stride_auth.md (required, never commit)

- **API URL:** `https://www.stridelikeaboss.com`
- **API Token:** `stride_dev_your_token_here`
- **User Email:** `your-email@example.com`

Add .stride_auth.md to your .gitignore — it contains secrets.

2. .stride.md (required, version controlled)

Define hook commands that run at each lifecycle point. Each section is a ## heading followed by a ```bash code block:

## before_doing

```bash
git pull origin main
mix deps.get
mix ecto.migrate
```

## after_doing

```bash
mix test --cover
mix format --check-formatted
mix credo --strict
```

## before_review

```bash
git fetch origin
git rebase origin/main
mix test
```

## after_review

```bash
git push origin main
```

Omit any sections you don't need.

Skill and Agent Discovery Paths

OpenCode walks up from the current working directory to the git worktree root looking for these directories. The first match wins per skill/agent name.

Resource	Project-local paths (in discovery order)	Global paths
Skills	.opencode/skills/<name>/SKILL.md, .claude/skills/<name>/SKILL.md, .agents/skills/<name>/SKILL.md	~/.config/opencode/skills/<name>/SKILL.md, ~/.claude/skills/<name>/SKILL.md, ~/.agents/skills/<name>/SKILL.md
Subagents	.opencode/agents/<name>.md	~/.config/opencode/agents/<name>.md
AGENTS.md	Any parent directory up to the git root	Not applicable

Mandatory Skill Chain

Every Stride skill is mandatory — not optional. Each skill contains required API fields, hook execution patterns, and validation rules that are only documented in that skill. Attempting to call Stride API endpoints without the corresponding skill results in API rejections.

Skill invocation

OpenCode skills are invoked explicitly via the native skill tool:

skill({ name: "stride-workflow" })

The agent reads the tool's description listing and invokes skills by name when their trigger condition matches. Start each Stride session by calling skill({ name: "stride-workflow" }) — that orchestrator walks through the full lifecycle (claim → explore → implement → review → complete) in one skill and references the other six as needed.

Workflow order

Recommended: orchestrator

stride-workflow                  ← Activate ONCE — handles claim → explore → implement → review → complete

Standalone mode (individual skills):

stride-claiming-tasks            ← BEFORE calling GET /api/tasks/next or POST /api/tasks/claim
    ↓
stride-subagent-workflow         ← AFTER claim succeeds, BEFORE implementation
    ↓
[implementation]
    ↓
stride-completing-tasks          ← BEFORE calling PATCH /api/tasks/:id/complete

When creating tasks or goals:

stride-creating-tasks            ← BEFORE calling POST /api/tasks (work/defect)
stride-creating-goals            ← BEFORE calling POST /api/tasks/batch (goals)
stride-enriching-tasks           ← WHEN a task has empty key_files/testing_strategy

Skills

Skill	Trigger	Purpose
stride-workflow	Starting task work	RECOMMENDED — Single orchestrator for the full lifecycle
stride-claiming-tasks	GET /api/tasks/next or POST /api/tasks/claim	Claim tasks with proper hook execution and before_doing result
stride-completing-tasks	PATCH /api/tasks/:id/complete	Complete tasks with after_doing/before_review hooks and all required fields
stride-creating-tasks	POST /api/tasks (work/defect)	Create tasks with correct field formats (object arrays, not strings)
stride-creating-goals	POST /api/tasks/batch	Create goals with batch format (root key must be "goals")
stride-enriching-tasks	Task has empty key_files/testing_strategy	Transform minimal specs into complete implementation-ready tasks
stride-subagent-workflow	After claiming, before implementation	Decision matrix for dispatching explorer/reviewer/decomposer agents

Each skill's frontmatter has a name (1–64 chars, lowercase alphanumeric with hyphens) matching its directory name and a description (1–1024 chars) that OpenCode surfaces in the skill tool listing so the agent can pick the right one.

Subagents

Agent	Mode	Purpose
task-explorer	subagent	Explore key_files and patterns before implementation
task-reviewer	subagent	Review changes against acceptance criteria before completion
task-decomposer	subagent	Break goals into dependency-ordered child tasks
hook-diagnostician	subagent	Diagnose hook failures with prioritized fix plans

Invoke agents via @mention in chat (e.g., @task-explorer) or automatically by the stride-subagent-workflow skill based on task complexity. See OpenCode's agents docs for the frontmatter fields supported (description, mode, model, temperature, permission).

Hook Execution

The plugin provides automatic hook execution — a native TypeScript implementation that intercepts Stride API calls and runs .stride.md commands without any external shell scripts or configuration files.

How it works

The plugin subscribes to OpenCode's tool.execute.before and tool.execute.after events. When an agent makes a Stride API call via curl or any shell command, the plugin:

1. Detects the Stride API endpoint in the command
2. Routes to the correct .stride.md section based on the endpoint and event timing
3. Executes each command from the section sequentially
4. Blocks the API call on failure (for pre-execution hooks) or logs warnings (for post-execution hooks)

Non-Stride commands pass through without any intervention.

Hook routing

API Call	Event	Hook Executed
POST /api/tasks/claim	tool.execute.after	before_doing
PATCH /api/tasks/:id/complete	tool.execute.before	after_doing (blocks on failure)
PATCH /api/tasks/:id/complete	tool.execute.after	before_review
PATCH /api/tasks/:id/mark_reviewed	tool.execute.after	after_review

Hook lifecycle

Hook	When	Blocking	Timeout
before_doing	After claiming a task	Yes	60s
after_doing	Before marking complete	Yes	120s
before_review	After marking complete	Yes	60s
after_review	After review approval	Yes	60s

Blocking hooks prevent the API call from proceeding if any command fails. The agent receives a structured error with the failed command, exit code, and output.

.stride.md parser rules

• Only the first ```bash block per section is executed
• Lines starting with # are treated as comments and skipped
• Blank lines are skipped
• Commands execute one at a time, stopping on first failure
• Both LF and CRLF line endings are supported
• Sections you don't need can be omitted entirely

Advantages over shell-based hooks

Unlike shell-script hooks used on other platforms, the OpenCode plugin approach offers:

• Cross-platform — runs on macOS, Linux, and Windows without separate .sh and .ps1 scripts
• Native JSON — parses API responses directly without jq dependency
• Single file — no external hook scripts, configuration files, or shell wrappers
• Structured errors — returns typed error objects instead of parsing stderr text
• Environment caching — automatically extracts task metadata from claim responses and makes it available as environment variables ($TASK_ID, $TASK_IDENTIFIER, $TASK_TITLE, etc.) in subsequent hooks

Manual hook execution (without the plugin)

If you skipped Step 1 of the install, the agent can still execute hooks manually by reading .stride.md and running each command line by line. Hooks are pre-authorized by the user who authored them — no confirmation prompts needed.

API Authorization

All Stride API calls are pre-authorized when the user initiates a Stride workflow. Agents should never prompt for permission to call Stride endpoints or execute hooks.

Tool Name Mapping

When skills reference tool names from other platforms, use OpenCode equivalents:

Skill Reference	OpenCode Tool
Read / read_file	read
Grep / grep_search	grep
Glob	glob
Bash / run_shell_command	bash
Edit / replace	edit
Write / write_file	write
Agent	@agent-name (subagent mention)

Troubleshooting

Plugin not loading

• Verify opencode.json has the plugin listed: "plugin": ["github:cheezy/stride-opencode"]
• Check that the repo reference resolves: run bun add github:cheezy/stride-opencode in a scratch directory to confirm Bun can pull it
• Look for Bun install errors in OpenCode's startup output

Hooks not firing

• Confirm the plugin (Step 1) is installed, not just the skills (Step 2). The skills alone don't execute hooks — they instruct the agent to do so.
• Confirm .stride.md exists in the project root
• Check that each hook section has a ```bash code block (not just prose)

Hook command fails

• The plugin executes commands sequentially and stops on first failure
• Check the error output for the specific command that failed
• Fix the issue and retry the API call — the hooks will fire again automatically

Missing environment variables in hooks

• Environment variables ($TASK_ID, $TASK_TITLE, etc.) are extracted from the claim API response
• They are only available after a successful claim in the same session
• If variables are missing, the claim response may not have included the expected fields

Skills not discovered

• Verify the skills are on disk at .opencode/skills/<name>/SKILL.md (project) or ~/.config/opencode/skills/<name>/SKILL.md (global). The github: plugin install does not place skills there — see Step 2.
• Skill names must match their directory name exactly (1–64 chars, lowercase alphanumeric with hyphens)
• Verify frontmatter has name: and description: fields; unknown fields are ignored

Subagents not available

• Verify agent files are at .opencode/agents/<name>.md or ~/.config/opencode/agents/<name>.md
• Invoke agents via @agent-name in chat
• Check frontmatter has description: and mode: subagent

npm package opencode-stride is missing

The npm package isn't currently published. Use the github:cheezy/stride-opencode reference in opencode.json instead, or install locally per Step 1. This README will be updated with the npm install form once the package ships.

License

MIT