feat: add obs tool and bug diagnostic skill

.gitignore

@@ -1,2 +1,3 @@
 /bin/
 .playwright-mcp/
+.obs/

AGENTS.md

@@ -0,0 +1,37 @@
+# AI Agent Guide
+
+This is a monorepo harness for the Observability UI team. See [ARCHITECTURE.md](ARCHITECTURE.md) for the project catalog, dependency graph, and
+feature delivery stages.
+
+## Setup
+
+Run `make setup` after cloning to install tools and initialize submodules.
+
+## Tools
+
+- **obs** (`./bin/obs`) — CLI for running development and deployment recipes. Build with `make tools`. Run `./bin/obs list` to see available recipes.
+  Always use `--non-interactive` or `--output-json` when invoking from an agent. See [tools/obs/AGENTS.md](tools/obs/AGENTS.md) for the full command
+  reference.
+
+## Task workflow
+
+Tasks live under `tasks/<name>/` with a structured pipeline:
+
+1. `spec.md` — problem statement, acceptance criteria, related projects
+2. `plan.md` — phased implementation plan with file tables and verification
+3. `execution.md` — checklist tracking progress through the plan
+
+Use the obsui plugin skills to drive this workflow:
+
+- `/obsui:planner` — create a plan from a spec
+- `/obsui:executor` — execute a plan
+- `/obsui:bug-diagnostic` — diagnose a bug from a spec
+- `/obsui:dev-env` — manage project dev environments
+- `/obsui:code-reviewer` — review a PR
+
+## Projects
+
+Projects are git submodules under `projects/`. Each has its own `CLAUDE.md` or `AGENTS.md` with project-specific guidance. Always use relative paths
+from the repo root when referencing project files (`projects/<project>/path/to/file`).
+
+Git commands in submodules: `git -C ./projects/<project> <command>`

Makefile

@@ -1,6 +1,7 @@
+# ── Variables ────────────────────────────────────────────────────────
+
 BIN_DIR    := $(CURDIR)/bin
 
-# Platform detection
 UNAME_S    := $(shell uname -s | tr '[:upper:]' '[:lower:]')
 UNAME_M    := $(shell uname -m)
 
@@ -18,21 +19,29 @@ else ifeq ($(UNAME_S),linux)
   DPRINT_TARGET := $(ARCH)-unknown-linux-gnu
 endif
 
-# Tool versions
-DPRINT_VERSION := 0.54.0
+DPRINT_VERSION     := 0.54.0
+DPRINT             := $(BIN_DIR)/dprint
+DPRINT_RELEASE_URL := https://github.com/dprint/dprint/releases/download/$(DPRINT_VERSION)/dprint-$(DPRINT_TARGET).zip
 
-# Tool paths
-DPRINT := $(BIN_DIR)/dprint
+OBS := $(BIN_DIR)/obs
 
-TOOLS := $(DPRINT)
+# ── Setup ────────────────────────────────────────────────────────────
 
-.PHONY: tools setup fmt-md check-md clean reset-projects
+.PHONY: setup clean reset-projects
 
 setup: tools reset-projects
 
-tools: $(TOOLS)
+clean:
+	rm -rf $(BIN_DIR)
 
-DPRINT_RELEASE_URL := https://github.com/dprint/dprint/releases/download/$(DPRINT_VERSION)/dprint-$(DPRINT_TARGET).zip
+reset-projects:
+	@./scripts/reset-projects.sh
+
+# ── Tools ────────────────────────────────────────────────────────────
+
+.PHONY: tools obs
+
+tools: $(DPRINT) obs
 
 $(DPRINT):
 	@mkdir -p $(BIN_DIR)
@@ -43,14 +52,16 @@ $(DPRINT):
 	@chmod +x $(DPRINT)
 	@echo "Installed dprint -> $(DPRINT)"
 
+obs:
+	@mkdir -p $(BIN_DIR)
+	cd tools/obs && go build -o $(OBS) ./cmd/obs
+
+# ── Lint ─────────────────────────────────────────────────────────────
+
+.PHONY: lint check
+
 lint: $(DPRINT)
 	$(DPRINT) fmt
 
 check: $(DPRINT)
 	$(DPRINT) check
-
-clean:
-	rm -rf $(BIN_DIR)
-
-reset-projects:
-	@./scripts/reset-projects.sh

README.md

@@ -7,9 +7,9 @@ for using AI coding agents across the team's project portfolio.
 
 Each task follows a three-document workflow:
 
-1. **`spec.md`** - Problem statement, related projects/branches, and acceptance criteria.
-2. **`plan.md`** - Step-by-step breakdown an AI agent can execute against.
-3. **`execution.md`** - Progress tracking with checkboxes and notes captured during execution.
+1. **`spec.md`** — Problem statement, related projects/branches, and acceptance criteria.
+2. **`plan.md`** — Step-by-step breakdown an AI agent can execute against.
+3. **`execution.md`** — Progress tracking with checkboxes and notes captured during execution.
 
 Tasks live in `tasks/`. The `projects/` directory contains git submodules for every repo in scope, giving agents direct access to source code.
 
@@ -20,23 +20,56 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for the full project catalog and system a
 ## Repository layout
 
 ```
-tasks/                  # Active tasks (description + work-plan + execution)
+tasks/                  # Active tasks (spec + plan + execution)
 completed/              # Archived completed tasks
 projects/               # Git submodules for all in-scope repos
-bin/                    # Local tooling (dprint)
-claude/plugins/obsui/   # Claude Code plugin for assisted development and code reviews
+tools/obs/              # obs CLI source (Go)
+bin/                    # Built tools (obs + dprint) — gitignored
+claude/plugins/obsui/   # Claude Code plugin (skills for planning, execution, debugging, dev environments, code review)
 ```
 
 ## Setup
 
 ```sh
 git clone --recurse-submodules https://github.com/observability-ui/harness/
-make setup    # install tools and reset submodules to their configured branches
+make setup    # install tools, build obs CLI, and reset submodules to their configured branches
 ```
 
+## Tools
+
+### obs CLI
+
+The `obs` CLI runs development and deployment recipes for projects in the harness. Built with `make tools`, the binary lands in `bin/obs`.
+
+```sh
+obs list                              # list available recipes
+obs start mp                          # start monitoring plugin (frontend + backend + console)
+obs start mp --force                  # kill processes on busy ports, then start
+obs --dry-run start mp                # show what would run without executing
+obs deploy coo                        # deploy cluster observability operator
+obs status                            # show running processes
+obs cleanup                           # stop all processes
+```
+
+Runs in interactive mode (TUI with tabs per process) by default, falls back to non-interactive (docker-compose style) in CI or with
+`--non-interactive`. See [tools/obs/README.md](tools/obs/README.md) for the full reference.
+
+### AI agent skills
+
+The [obsui plugin](claude/plugins/obsui/) provides skills for AI-assisted development:
+
+| Skill                   | Purpose                                           |
+| ----------------------- | ------------------------------------------------- |
+| `/obsui:planner`        | Create an implementation plan from a spec         |
+| `/obsui:executor`       | Execute a plan with parallel agents               |
+| `/obsui:bug-diagnostic` | Diagnose a bug from a spec                        |
+| `/obsui:dev-env`        | Manage project dev environments via the obsui CLI |
+| `/obsui:code-reviewer`  | Multi-angle PR review                             |
+
 ## Resetting projects
 
-After working on tasks, submodules may have checked-out branches or uncommitted changes. Run `make reset-projects` to reset all submodules back to the branches defined in `.gitmodules` at the latest remote HEAD. This prevents intermediate states from being committed to this meta-repo.
+After working on tasks, submodules may have checked-out branches or uncommitted changes. Run `make reset-projects` to reset all submodules back to the
+branches defined in `.gitmodules` at the latest remote HEAD.
 
 ## Markdown formatting