workspace-doctor

Diagnoses common BotMinter workspace issues — stale submodules, broken symlinks, missing files, outdated context, and sync problems. Use when the operator asks to "check my workspace", "diagnose issues", "why isn't X working", "fix my setup", "workspace health", or "something seems wrong".

8 stars

bybotminter

View on GitHub Installation ↓

Best use case

workspace-doctor is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using workspace-doctor should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/workspace-doctor/SKILL.md --create-dirs "https://raw.githubusercontent.com/botminter/botminter/main/minty/.claude/skills/workspace-doctor/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/workspace-doctor/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How workspace-doctor Compares

Feature / Agent	workspace-doctor	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# Workspace Doctor

Diagnoses common BotMinter workspace issues. Runs checks against team workspaces and reports findings with suggested fixes.

## Data Sources

| Source | Path | Contains |
|--------|------|----------|
| Team registry | `~/.botminter/config.yml` | Team paths |
| Workspace marker | `<workspace>/.botminter.workspace` | Workspace identity |
| Team submodule | `<workspace>/team/` | Team repo as submodule |
| Ralph config | `<workspace>/ralph.yml` | Member's Ralph Orchestrator config |
| Context file | `<workspace>/CLAUDE.md` | Member's coding agent context |
| Prompt file | `<workspace>/PROMPT.md` | Member's work objective |

## Running Diagnostics

When the operator asks for a workspace check, run these checks in order. Report each finding with a status indicator:
- `OK` — check passed
- `WARN` — non-critical issue found
- `FAIL` — critical issue that needs fixing

### Check 1: Workspace Marker

```bash
test -f <workspace>/.botminter.workspace
```

- `OK` if marker exists
- `FAIL` if missing — workspace not provisioned. Fix: `bm teams sync -t <team>`

### Check 2: Team Submodule

```bash
cd <workspace>/team && git status
```

- `OK` if submodule is clean and on a branch
- `WARN` if submodule has uncommitted changes
- `WARN` if submodule is in detached HEAD state
- `FAIL` if `team/` directory is missing. Fix: `bm teams sync -t <team>`

Check for stale submodule (behind remote):

```bash
cd <workspace>/team && git fetch --dry-run 2>&1
```

If fetch reports new commits, the submodule may be outdated:

> Team submodule is behind remote. Run `cd <workspace>/team && git pull` or `bm teams sync -t <team>`.

### Check 3: Required Files

Verify these files exist at the workspace root:

```bash
test -f <workspace>/ralph.yml
test -f <workspace>/CLAUDE.md
test -f <workspace>/PROMPT.md
```

- `OK` if all present
- `FAIL` for each missing file. Fix: `bm teams sync -t <team>` (re-surfaces files from team repo)

### Check 4: Symlinks

Check that `.claude/agents/` symlinks point to valid targets:

```bash
find <workspace>/.claude/agents/ -type l 2>/dev/null | while read link; do
  if [ ! -e "$link" ]; then
    echo "BROKEN: $link -> $(readlink "$link")"
  fi
done
```

- `OK` if no broken symlinks
- `WARN` for each broken symlink. Fix: `bm teams sync -t <team>` (recreates symlinks)

### Check 5: Ralph Lock State

```bash
cat <workspace>/.ralph/loop.lock 2>/dev/null
```

If a lock file exists but the process is not running:

```bash
PID=$(cat <workspace>/.ralph/loop.lock 2>/dev/null | grep -o '"pid":[0-9]*' | grep -o '[0-9]*')
if [ -n "$PID" ] && ! kill -0 "$PID" 2>/dev/null; then
  echo "WARN: Stale lock file — process $PID is not running"
fi
```

- `OK` if no lock or process is alive
- `WARN` if stale lock. Fix: `rm <workspace>/.ralph/loop.lock`

### Check 6: Git Status

```bash
cd <workspace> && git status --short
```

- `OK` if clean
- `WARN` if there are uncommitted changes (may indicate interrupted work)

## Scope Selection

### Single Member

If the operator specifies a member:

```bash
# Derive workspace path
WORKSPACE="<team-path>/<member-name>"
```

### All Members in a Team

If the operator asks to check the whole team:

```bash
# List all members
ls <team-path>/team/members/
```

Run checks for each member's workspace.

### No Teams Configured

If `~/.botminter/config.yml` does not exist:

> No teams registered. There are no workspaces to diagnose. To get started, run `bm init`.

## Output Format

```
## Workspace Health: <member> (<team>)

| Check | Status | Details |
|-------|--------|---------|
| Workspace marker | OK | .botminter.workspace present |
| Team submodule | WARN | Submodule is 3 commits behind remote |
| Required files | OK | ralph.yml, CLAUDE.md, PROMPT.md present |
| Symlinks | FAIL | 2 broken symlinks in .claude/agents/ |
| Ralph lock | OK | No stale locks |
| Git status | WARN | 4 uncommitted files |

### Suggested Fixes

1. **Team submodule behind:** Run `cd <workspace>/team && git pull`
2. **Broken symlinks:** Run `bm teams sync -t <team>`
```

## CLI Quick Reference

| Task | Command |
|------|---------|
| Sync workspaces | `bm teams sync -t <team>` |
| Check team status | `bm status -t <team>` |
| Show member details | `bm members show <member> -t <team>` |
| Start member | `bm start -t <team>` |
| Stop member | `bm stop -t <team>` |

Related Skills

workspace-sync

from botminter/botminter

Sync and diagnose BotMinter workspaces. Use when the operator says "sync workspaces", "apply profile changes", "propagate changes", "update all workspaces", "check workspace health", "diff against profile", "full sync", "my workspace has old files", or "why is the workspace out of date". Do NOT use for member behavior/config tuning (use member-tuning) or structured process changes (use process-evolution).

team-design

from botminter/botminter

Entry point for all day-2 team design operations. Routes operator intent to the appropriate sub-skill — retrospective, role-management, member-tuning, or process-evolution — and provides a unified dashboard of team design state. Use when asked to "design the team", "show me the team", "team overview", "what's our team setup", "let's evolve the team", "team health check", or when the operator's intent spans multiple team design areas.

role-management

from botminter/botminter

Manages team role composition — list, add, remove, and inspect roles defined in botminter.yml. Includes impact analysis of statuses, hats, and knowledge before changes, and records every change as a team agreement decision. Use when asked to "add a role", "remove a role", "list roles", "inspect a role", "change team composition", "what roles do we have", "team structure", or when an cos:exec:todo issue requests a role change.

retrospective

from botminter/botminter

Guides a structured team retrospective examining what went well, what didn't, and produces typed action items. Outputs a retro summary to agreements/retros/. Use when asked to "run a retro", "do a retrospective", "reflect on the sprint", "what went well", "review team performance", or when an cos:exec:todo issue requests a retrospective.

process-evolution

from botminter/botminter

Guides deliberate, team-wide process changes — adding or removing statuses, modifying transitions, updating review gates, and evolving the workflow lifecycle. Validates changes against the status graph before applying and records every decision as a team agreement. Use when asked to "change the process", "add a status", "remove a status", "modify the workflow", "update transitions", "add a review gate", "evolve the process", "change auto-advance rules", or when an cos:exec:todo issue requests a process change.

member-tuning

from botminter/botminter

Diagnoses and tunes individual member configurations by mapping symptoms to the responsible artifact — PROMPT.md, CLAUDE.md, ralph.yml (hats), skills, or PROCESS.md. Provides a diagnostic decision tree, inspection commands, example edits, and propagation steps for each artifact type. Use when asked to "tune a member", "fix a member", "troubleshoot a member", "member isn't working", "adjust member behavior", "member diagnostic", "why is the member doing X", or when an cos:exec:todo issue requests member tuning.

cos-session

from botminter/botminter

Chief of Staff working session with the operator. Use when the operator says "chief of staff session", "cos session", "I have things to file", "let's work through some items", "I found some problems", "what's <member> doing", "let's go over the board", or brings any mix of observations, bugs, ideas, or operational concerns.

github-project

from botminter/botminter

Manages GitHub Projects v2 workflows for issue tracking and project management. Use when user asks to "show the board", "view issues", "what's in [status]", "create an epic", "add a story", "create a bug", "move issue

team-overview

from botminter/botminter

Shows registered BotMinter teams, their members, roles, workspaces, and running state. Use when the operator asks to "show teams", "list teams", "who is on the team", "team status", "show members", or "what teams do I have". Reads ~/.botminter/config.yml and workspace directories.

profile-design

from botminter/botminter

Designs and troubleshoots BotMinter profiles — team methodology templates that define roles, statuses, hats, skills, and process conventions. Use when the operator asks to "design a profile", "create a new role", "fork a profile", "fix my profile", "troubleshoot profile issues", "design a process workflow", "add a hat", "customize a profile", or "validate my profile". Operates on profile templates, not live team repos.

profile-browser

from botminter/botminter

Browses and describes BotMinter profiles — team methodology templates that define roles, statuses, coding agents, and process conventions. Use when the operator asks to "list profiles", "show profiles", "what profiles are available", "describe a profile", "what roles does X have", or "compare profiles". Reads ~/.config/botminter/profiles/.

hire-guide

from botminter/botminter

Interactive guide for hiring team members with `bm hire`. Helps operators choose roles, pick names, and understand hiring implications. Use when the operator asks to "hire someone", "add a member", "what roles can I hire", "help me hire", "who should I hire next", or "explain the roles".