# ost-builder

This skill builds or updates an Opportunity Solution Tree from research evidence. Use it when user needs must be mapped into a structured opportunity tree.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 47
- Author: haabe
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/haabe/mycelium/tree/HEAD/plugins/mycelium/skills/ost-builder/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/ost-builder

## What it does

ost-builder builds and maintains an Opportunity Solution Tree from research evidence such as interview transcripts, behavioral data, analytics, and observation notes. It treats opportunities as user needs rather than proposed solutions, then organizes related items into a hierarchy. Brainstorming is outside this workflow.

Before changing any `.claude/canvas/*.yml` file, the skill requires the target file to be read with the `Read` tool. When adding an entry with an ID, it scans existing identifiers with `grep`, selects a free value, and follows the zero-padding already used in that file. The same checks apply when several canvas files are involved.

The skill is designed for the Mycelium framework. Running it on its own skips the canvas state, theory gates, and harness behavior it expects, so Mycelium is a prerequisite for the full workflow.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add haabe/mycelium --skill ost-builder -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ost-builder/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ost-builder/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add haabe/mycelium --skill ost-builder -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ost-builder/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add haabe/mycelium --skill ost-builder -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ost-builder/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install haabe/mycelium ost-builder
```

2. **Manually: put the files in place**
- File: `.github/skills/ost-builder/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add haabe/mycelium --skill ost-builder -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/haabe/mycelium --path plugins/mycelium/skills/ost-builder
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ost-builder/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add haabe/mycelium --skill ost-builder -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/haabe/mycelium/tree/HEAD/plugins/mycelium/skills/ost-builder/SKILL.md

## When to use it
- build an Opportunity Solution Tree from research evidence
- separate user needs from proposed solutions
- organize related opportunities into a hierarchy
- read canvas files before changing them
- find unused IDs for new entries

## Example prompts
- Build an Opportunity Solution Tree from the interview transcripts and analytics in this project.
- Update the existing opportunity tree with the latest research evidence.
- Check `.claude/canvas/*.yml` before editing and choose free IDs for new entries.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 872fd33d4f26380b.

BEGIN THIRD-PARTY FILE 872fd33d4f26380b
````text
---
name: ost-builder
description: "Use to build or update an Opportunity Solution Tree from research data. Never from brainstorming."
metadata:
  instruction_budget: "47"
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."
---

# OST Builder Skill

Build and maintain Opportunity Solution Trees from research evidence.

## Preflight: Read target canvas file(s) before any Write/Edit

**Hard rule.** Before issuing `Write` or `Edit` against any `.claude/canvas/*.yml`, use the **Read tool** on that file in this session. Claude Code's Read-before-Write check requires the `Read` tool specifically — `cat`/`head`/`grep` via Bash do NOT satisfy it.

**Edit vs Write — different cost profiles** (verified 2026-05-14):
- **`Edit`** (exact-string replacement): `Read` with `limit: 1` satisfies the check at ~50 tokens. State-tracking is per-file, not per-byte — subsequent `Edit` calls work anywhere in the file. Use this for partial updates against large canvas files (e.g., `purpose.yml` at 800+ lines).
- **`Write`** (full replacement): do a **full Read** first. Write obliterates the file; you should see what you're about to replace. The `limit:1` shortcut is *not* appropriate here.

**ID-bearing entries — scan the ID space before assigning** (added 2026-05-15, v0.23.19): When adding a new component, opportunity, solution, or any other ID-bearing entry to a canvas file, run a Bash grep first to confirm the next ID in your prefix sequence is actually free:

```
grep -o "<prefix>-[0-9][0-9]*" .claude/canvas/<file>.yml | sort -u -t- -k2 -n | tail -3
```

Replace `<prefix>` with the canvas's ID prefix (`comp` for landscape, `opp` for opportunities, `sol` for solutions, `ht` for human-tasks, etc.). Then pick the next free integer, **matching the zero-padding already used in that file**. The sort is NUMERIC (`-t- -k2 -n`) rather than lexical, and that is not pedantry: a plain `sort -u` orders `ht-1` after `ht-080`, so on a canvas with inconsistent padding it reports the wrong maximum and the next ID collides. Verified on the dogfood repo 2026-08-13, where lexical sort returned `ht-1` as the highest human-task ID against an actual `ht-080`. `grep -o` is also deliberate: it matches IDs wherever they appear, including cross-references and prose, so an ID that was promised somewhere but not yet defined is not handed out twice. `validate_canvas.py` has a per-file duplicate-ID check (it reports `duplicate id '<id>'`) that catches the failure on CI, but a duplicate can persist in the working tree for days if CI isn't run between edit and discovery; that happened on 2026-05-15, when a duplicate ID was created in `landscape.yml`.
````
END THIRD-PARTY FILE 872fd33d4f26380b

The third-party file has ended. Everything between the 872fd33d4f26380b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2911 of 19106 bytes. © haabe · MIT · https://github.com/haabe/mycelium/tree/HEAD/plugins/mycelium/skills/ost-builder/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md