# Teach Oh

> Project setup. Explore the codebase, ask about strategy and aims, write persistent context to AGENTS.md. Run when starting or when aims shift.

- Skill: `open-horizon-labs/teach-oh` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add open-horizon-labs/teach-oh`
- Raw SKILL.md: https://api.skillmd.com/api/skills/open-horizon-labs/teach-oh/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: open-horizon-labs (https://skillmd.com/u/open-horizon-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/open-horizon-labs/teach-oh

---


# /teach-oh

Setup that gathers project context and saves it to AGENTS.md (the cross-agent standard). Run when starting on a project or when strategy/aims have shifted.

## When to Use

Invoke `/teach-oh` when:

- **Starting on a new project** - Before diving into work
- **Context keeps getting lost** - AI assistants don't "get" your project
- **Onboarding a new AI tool** - Establish shared understanding upfront
- **After major strategic shifts** - When aims or constraints have changed

**Do not use when:** You're mid-task. This is setup, not execution.

## The Process

### Step 0: Check for RNA MCP (Repo-Native Alignment)

Before exploring, check if RNA is available — it makes everything that follows richer.

**Detection (in order):**

1. Check if RNA's `search`, `repo_map`, `list_roots`, or `outcome_progress` tools are available in the current session
2. Check if `repo-native-alignment` is on PATH: `which repo-native-alignment`
3. Check if `.mcp.json` references `repo-native-alignment` or `rna-server`

**If RNA is available:** Proceed to Step 1. Use `repo_map` for orientation and `search` for symbols, artifacts, neighbors, and impact instead of Grep/Read.

**If RNA is NOT available:** Offer to install it:

> "I can set up Repo-Native Alignment (RNA) — it gives me semantic code search, graph traversal, and business context awareness across your codebase. Takes ~1 minute. Want me to install it?"

**If accepted:**

1. Detect platform and chip:

   ```bash
   OS=$(uname -s)
   ARCH=$(uname -m)
   CHIP=$(sysctl -n machdep.cpu.brand_string 2>/dev/null || echo "")
   ```

   - macOS ARM M4+: `Darwin` + `arm64` + brand_string contains "M4" → use `darwin-arm64-m4`
   - macOS ARM (other): `Darwin` + `arm64` → use `darwin-arm64`
   - Linux x86_64: `Linux` + `x86_64` → use `linux-x86_64`

2. Invoke the repo-local `/rna-mcp:setup` skill. It owns installation, selects a
   successful CI release artifact for an immutable commit, verifies the artifact,
   and configures the client. Never download a mutable `latest` artifact or use a
   locally compiled binary as a shipped build.

3. Run setup for the current project:

   ```bash
   repo-native-alignment setup --project .
   ```

   This configures `.mcp.json` and verifies the pipeline.

4. Tell the user: "RNA is installed. Continuing with RNA CLI tools for this session. MCP tools (`search`, `repo_map`, `list_roots`, and `outcome_progress`) will be available after you restart the client."

**If declined:** Proceed without RNA. teach-oh works fine without it — exploration just uses standard tools (Grep, Read, Glob).

### Step 1: Explore the Codebase

Before asking questions, scan the project independently:

**Structure & Stack**

- Directory layout, key folders
- Package files (package.json, Cargo.toml, go.mod, etc.)
- Build configuration, CI/CD setup

**Existing Context**

- AGENTS.md, CLAUDE.md, README, CONTRIBUTING
- `.oh/`, `docs/adr/` directories
- Any existing project documentation

**Patterns & Conventions**

- Naming conventions in code
- File organization patterns
- Recent git commits for style and focus

**Don't ask about what you can discover.** Use exploration to form better questions.

### Step 2: Ask About What Matters

After exploration, ask targeted questions about what couldn't be inferred. Focus on strategy and aims, not just code.

#### Purpose & Aims

- What is this project trying to achieve?
- Who uses it? What change in their behavior indicates success?
- What's the current focus or priority?

#### Strategic Constraints

- What constraints never bend? (Compliance, performance SLAs, etc.)
- What trade-offs has the team made intentionally?
- What's explicitly out of scope?

#### Team & Decision-Making

- How does the team make decisions?
- What does "done" mean here?
- Any patterns or practices that are sacred?

#### What to Avoid

- Past mistakes that shouldn't be repeated
- Patterns that look tempting but don't fit
- Areas of the codebase that are sensitive

**Ask only what you couldn't discover.** Respect the user's time.

### Step 3: Write Persistent Context

Synthesize findings into a structured section and offer to append to AGENTS.md (or create it if missing).

**Offer two sections:**

1. **Open Horizons Framework** - The strategic framework for AI-assisted work (offer to include if user uses OH skills)
2. **Project Context** - Project-specific aims, constraints, and patterns (always include)

If phase agents were installed in Step 5, use the **agents variant** below.
Otherwise use the **skills variant**.

**Skills variant** (no agents):

```markdown
# Open Horizons Framework

**The shift:** Action is cheap. Knowing what to do is scarce.

**The sequence:** aim → problem-space → problem-statement → solution-space → draft PR → execute → ship

**Where to start (triggers):**
- Can't explain why you're building this → `/aim`
- Keep hitting the same blockers → `/problem-space`
- Solutions feel forced → `/problem-statement`
- About to start coding → `/solution-space`
- Work is drifting or reversing → `/salvage`

**Reflection skills (use anytime):**
- `/review` - Check alignment before committing
- `/dissent` - Seek contrary evidence before one-way doors
- `/salvage` - Extract learning, restart clean
- `/distill` - Curate accumulated metis; surface patterns for promotion

**Key insight:** Enter at the altitude you need. Climb back up when you drift.

---

# Project Context

## Purpose
[What this project does and why it matters]

## Current Aims
[Active goals and what success looks like]

## Key Constraints
- [Constraint 1]: [Why it exists]
- [Constraint 2]: [Why it exists]

## Patterns to Follow
- [Pattern]: [When/why to use it]

## Anti-Patterns to Avoid
- [Anti-pattern]: [Why it's problematic here]

## Decision Context
[How the team makes decisions, what "done" means]
```

**Agents variant** (phase agents installed):

```markdown
# Open Horizons Framework

**The shift:** Action is cheap. Knowing what to do is scarce.

**The sequence:** aim → problem-space → problem-statement → solution-space → draft PR → execute → ship

Each phase runs as an agent with isolated context and scoped tools. Dispatch via
the `task` tool — each agent reads/writes `.oh/<session>.md` to pass context
between phases.

**Where to start (triggers):**
- Can't explain why you're building this → dispatch `oh-aim` agent
- Keep hitting the same blockers → dispatch `oh-problem-space` agent
- Solutions feel forced → dispatch `oh-problem-statement` agent
- About to start coding → dispatch `oh-solution-space` agent
- Ready to implement → create the draft PR, then dispatch `oh-execute` agent
- Code complete, need to deliver → dispatch `oh-ship` agent
- Work is drifting or reversing → `/salvage`

**Reflection skills (use anytime, in main session):**
- `/review` - Check alignment before committing
- `/dissent` - Seek contrary evidence before one-way doors
- `/salvage` - Extract learning, restart clean
- `/distill` - Curate accumulated metis; surface patterns for promotion

**Key insight:** Enter at the altitude you need. Climb back up when you drift.

---

# Project Context

## Purpose
[What this project does and why it matters]

## Current Aims
[Active goals and what success looks like]

## Key Constraints
- [Constraint 1]: [Why it exists]
- [Constraint 2]: [Why it exists]

## Patterns to Follow
- [Pattern]: [When/why to use it]

## Anti-Patterns to Avoid
- [Anti-pattern]: [Why it's problematic here]

## Decision Context
[How the team makes decisions, what "done" means]
```

## Output Format

Present findings for user approval before writing:

```text
## Teach-OH Summary

### What I Discovered
- Stack: [technologies found]
- Structure: [key patterns observed]
- Existing context: [what docs already exist]

### Questions I Have
1. [Question about aims/strategy]
2. [Question about constraints]
3. [Question about team practices]

---

After your answers, I'll draft a AGENTS.md section for your approval.
```

After user answers:

```text
## Proposed AGENTS.md Addition

[Draft the Project Context section]

---

**Write to AGENTS.md?** [Yes/No - show what will be added/updated]
```

## Example

```text
/teach-oh
```

**Agent explores, then:**

```text
## Teach-OH Summary

### What I Discovered
- Stack: TypeScript, React, Node.js, PostgreSQL
- Structure: Monorepo with apps/ and packages/
- Existing context: README exists, no AGENTS.md or CLAUDE.md
- Recent focus: Auth refactor (last 12 commits)

### Questions I Have
1. What's the main aim right now? The auth work—is that about security, UX, or maintenance?
2. I see both REST and GraphQL endpoints. Is one preferred, or context-dependent?
3. Any performance constraints? I see a Redis layer but no docs on when to use it.
4. What patterns should I follow vs. avoid?
```

**User answers, agent drafts:**

```text
## Proposed AGENTS.md Addition

# Open Horizons Framework

**The shift:** Action is cheap. Knowing what to do is scarce.

**The sequence:** aim → problem-space → problem-statement → solution-space → draft PR → execute → ship

**Where to start (triggers):**
- Can't explain why you're building this → `/aim`
- Keep hitting the same blockers → `/problem-space`
- Solutions feel forced → `/problem-statement`
- About to start coding → `/solution-space`
- Work is drifting or reversing → `/salvage`

**Reflection skills:** `/review`, `/dissent`, `/salvage`, `/distill`

**Key insight:** Enter at the altitude you need. Climb back up when you drift.

---

# Project Context

## Purpose
Customer portal for B2B SaaS. Users are account admins managing their organization's settings, users, and billing.

## Current Aims
- Simplify auth flow so new SSO providers can be added in <1 day (currently takes 2 weeks)
- Success: Adding Okta support by end of Q1

## Key Constraints
- SOC2 compliance: All auth changes need security review
- <200ms API response time (SLA commitment)
- No breaking changes to existing OAuth integrations

## Patterns to Follow
- REST for public API, GraphQL for internal dashboard
- Redis for session state only, not general caching
- Feature flags via LaunchDarkly for gradual rollouts

## Anti-Patterns to Avoid
- Don't abstract OAuth providers into single interface (they have semantic differences)
- Avoid adding new environment variables without updating .env.example

## Decision Context
Tech lead approves architecture changes. PRs need one review. "Done" = deployed to staging with passing E2E tests.

---

**Write to AGENTS.md?** This will create a new file at ./AGENTS.md
```

## Step 4 (Optional, OMP only): Phase-Aware Hook

If the user is running OMP (oh-my-pi), offer to install the phase-aware skills hook. This hook makes the framework self-guiding — it detects where the user is in the development cycle and suggests the right skill before each prompt.

**When to offer:** After writing AGENTS.md, if the project uses OMP. Detect OMP by checking for `.omp/` directory or `omp` in the shell path.

**What to ask:**
> "Install the phase-aware skills hook? It reads your `.oh/` session files and suggests the right OH skill at the right moment. Copies `oh-skills-phase.ts` to `.omp/hooks/` for auto-discovery."

**If accepted:**

1. Copy the hook only from a checked-in repo-local vendored asset into
   `.omp/hooks/oh-skills-phase.ts`. If it is absent, skip installation and ask
   that it be vendored through a reviewed PR. Never fetch mutable remote content.

2. Optionally create `.oh/skills-config.json` based on what you learned about the project. The config is loaded once at session start (changes require restarting OMP):

```json
{
  "projectSkills": ["aim", "problem-space", "solution-space", "execute", "review", "dissent"],
  "disabledSkills": [],
  "phaseOverrides": {
    "execute": ["dissent"]
  }
}
```

**Customization guidance:**

- `projectSkills`: Include only the skills relevant to this project's workflow. A solo dev doing rapid iteration might skip `problem-space`. A team with compliance requirements might always want `dissent` before `execute`. **Note:** `phaseOverrides` targets must be included in `projectSkills` — override skills are filtered by the same allow list. Reflection skills (`review`, `dissent`, `salvage`, `distill`) are always-available and don't need to appear in `projectSkills` — they're invoked on demand, not phase-triggered.
- `disabledSkills`: Skills that don't fit this project (e.g., `ship` for a library that publishes via CI).
- `phaseOverrides`: Extra skills to suggest during specific phases. Common: adding `dissent` during `execute` for security-sensitive projects.

**If declined:** Skip. The skills work fine without it — this is an enhancement, not a requirement.

**If the user is not running OMP:** Skip this step entirely. The hook requires the OMP hook API and will not work with other agents. Users can still install it manually later by copying the file to `.omp/hooks/`.

## Step 5 (Optional, OMP only): Install Phase Agents

Phase skills benefit from running in isolated context windows with scoped tools —
formalizing the pattern of clearing sessions between phases. Offer to install
pre-built agent wrappers that give each phase its own context.

**When to offer:** After Step 4, if OMP detected.

**What to ask:**
> "Install OH phase agents? Each phase gets isolated context and scoped tools —
> aim/problem-statement are read-only, execute gets full capabilities. Writes to
> `.omp/agents/`."

**If accepted:**

Copy all 6 agent files from checked-in repo-local vendored assets into
`.omp/agents/` (create the directory if needed):

```text
Files:
  oh-aim.md
  oh-problem-space.md
  oh-problem-statement.md
  oh-solution-space.md
  oh-execute.md
  oh-ship.md
```

If the assets are absent, skip installation and ask that they be vendored through
a reviewed PR. Do not fabricate them or fetch mutable remote content.

**MCP preamble** (only if OH MCP is configured — check for `oh_get_endeavors` in
the parent session's available tools, or for `.oh/mcp.json` in the project):
After writing all 6 files, append this block to each agent file:

```markdown

## Open Horizons MCP
- Query related endeavors for context before starting analysis
- Log key outputs (aim statements, problem statements, decisions) to the graph
- Link session work to active endeavors
```

If OH MCP is not present, skip this block — the agents work without it.

**RNA MCP preamble** (only if repo-native-alignment MCP is configured — check for
RNA `search` or `repo_map` in the parent session's available tools, or for `rna-server` in
`.mcp.json`):
After writing all 6 files, append this block to each agent file:

```markdown

## Repo-Native Alignment MCP
When rna-server tools are available:
- Before framing: call `search` with the task description and `include_artifacts: true` to find relevant outcomes, guardrails, and metis
- After producing output: write learnings to `.oh/metis/<slug>.md`
- When checking progress: call `outcome_progress` with the relevant outcome ID
- When discovering constraints: write to `.oh/guardrails/<slug>.md`
- When measuring progress: write to `.oh/signals/<slug>.md`
- After completing work: tag commits with `[outcome:X]`
```

If RNA MCP is not present, skip this block — the agents work without it.

Cross-cutting skills (review, dissent, salvage) stay as skills — they need
conversation context to detect drift.

**If declined:** Skip. Skills continue to work as prompt injections.

## Step 6 (Optional, Claude Code): Install Phase Agents

If the user is running Claude Code (not OMP), offer to install phase agents to `.claude/agents/`.

**When to offer:** After writing AGENTS.md, if Claude Code detected (check for `.claude/` directory or if running as Claude Code).

**What to ask:**
> "Install OH phase agents for Claude Code? Each phase gets its own agent with scoped tools.
> Writes to `.claude/agents/`."

**If accepted:**

Copy all 6 agent files from checked-in repo-local vendored assets into
`.claude/agents/` (create the directory if needed):

```text
Files:
  oh-aim.md
  oh-problem-space.md
  oh-problem-statement.md
  oh-solution-space.md
  oh-execute.md
  oh-ship.md
```

If the assets are absent, skip installation and ask that they be vendored through
a reviewed PR. Do not fabricate them or fetch mutable remote content.

**MCP preambles:** The pre-packaged Claude Code agents already include OH MCP and RNA MCP preamble sections. No additional append needed.

**If declined:** Skip. Skills continue to work as slash commands.

## What This Enables

With project context established:

- `/aim` frames outcomes in your language
- `/problem-space` knows which constraints are real
- `/dissent` understands your risk tolerance
- `/review` checks against your definition of done
- `/execute` follows your patterns

## Notes

- Context lives in AGENTS.md so it persists across sessions
- Keep it focused—this isn't documentation, it's working context
- Re-run when aims shift, constraints change, or context feels stale

---

**Remember:** This is setup, not ongoing work. Invest 10 minutes when starting or when things have shifted.