@damian87/omp 0.1.0 → 0.2.0

package/.github/skills/research-codebase/reference/template.md

@@ -0,0 +1,75 @@
+# Research Document Template
+
+Use this template for all research documents written to `docs/research/`.
+
+## Filename convention
+
+- With ticket: `YYYY-MM-DD-PROJ-1234-description.md`
+- Without ticket: `YYYY-MM-DD-description.md`
+
+## Frontmatter
+
+```yaml
+---
+date: [ISO datetime with timezone from git/system]
+researcher: [git user.name]
+git_commit: [commit hash]
+branch: [branch name]
+repository: [repo name]
+topic: "[User's question/topic]"
+tags: [research, codebase, relevant-component-names]
+status: complete
+last_updated: [YYYY-MM-DD]
+last_updated_by: [git user.name]
+---
+```
+
+## Gather metadata
+
+Run these commands — never write placeholder values:
+
+```bash
+echo "date: $(date -u +%Y-%m-%dT%H:%M:%S%z)"
+echo "user: $(git config user.name)"
+echo "commit: $(git rev-parse HEAD)"
+echo "branch: $(git branch --show-current)"
+echo "repo: $(basename $(git rev-parse --show-toplevel))"
+```
+
+## Document structure
+
+```markdown
+# Research: [User's Question/Topic]
+
+**Date**: [datetime]
+**Researcher**: [name]
+**Git Commit**: [hash]
+**Branch**: [branch]
+**Repository**: [repo]
+
+## Research Question
+[Original user query]
+
+## Summary
+[High-level documentation of what was found — describe what exists]
+
+## Detailed Findings
+
+### [Component/Area 1]
+- Description of what exists (`file.ext:line`)
+- How it connects to other components
+- Current implementation details (without evaluation)
+
+### [Component/Area 2]
+...
+
+## Code References
+- `path/to/file.py:123` — Description of what's there
+- `another/file.ts:45-67` — Description of the code block
+
+## Architecture Documentation
+[Current patterns, conventions, and design implementations]
+
+## Open Questions
+[Areas that need further investigation]
+```

package/.github/skills/tdd/SKILL.md

@@ -7,13 +7,30 @@ description: Red-green-refactor loop for behavior changes where tests are practi
 
 Use `/tdd` when a change can be specified by tests.
 
-Loop:
-1. Write or identify a failing behavior test.
-2. Make it pass with minimal code.
-3. Refactor safely.
-4. Run related checks.
-
-Rules:
-- Test behavior through public surfaces.
-- Avoid brittle implementation tests.
-- If TDD is impractical, explain why and use `/verify`.
+## When to use
+
+- You're implementing a feature or fixing a bug that has clear expected behaviour
+- The codebase has an existing test framework
+- You want to prove correctness incrementally
+
+## Loop (repeat until done)
+
+1. **Red** — write or identify a failing test that describes the desired behaviour
+2. **Green** — write the minimal code to make the test pass
+3. **Refactor** — clean up the code while keeping tests green
+4. **Run** — run the full related test suite to check for regressions
+
+## Rules
+
+- Test **behaviour** through public surfaces, not implementation details
+- Each test should describe one behaviour — name it clearly (e.g. "returns 404 when user not found")
+- Avoid brittle tests that break when implementation changes but behaviour doesn't
+- If TDD is impractical for the change (e.g. UI layout, infra config), explain why and use `/verify` instead
+- Don't write tests for trivial getters/setters — focus on logic
+
+## Output
+
+- `Tests written` — list of test names and what they cover
+- `Implementation` — what was changed to make tests pass
+- `Refactoring` — what was cleaned up
+- `Final test run` — all tests passing (output or summary)

package/.github/skills/team/SKILL.md

@@ -1,20 +1,102 @@
 ---
 name: team
-description: Split an approved plan into parallel lanes for agents or humans. Use with /team when work has independent lanes.
+description: Split an approved plan into parallel tmux panes, each running an independent Copilot CLI agent. Use when work has independent lanes and you want visual parallel execution in split terminals. Use when user says /team, team, or wants parallel agent execution.
+argument-hint: "<number of lanes or plan reference>"
 ---
 
-# Team
+# Team — tmux-based parallel agent execution
 
-Use `/team` when work has independent lanes.
+`/team` splits work into parallel tmux panes in the **current window**, each running an independent interactive agent session. You see all agents working side-by-side immediately.
 
-Do:
-- Require a plan or clear task.
-- Split into lanes with owners, files, and tests.
-- Identify dependencies and conflict risks.
-- Keep it as a coordination brief, not a runtime.
+## When to use
 
-Output:
-- `Lanes`
-- `Shared files`
-- `Order/dependencies`
-- `Verification`
+- Work has **independent lanes** (no shared files, no ordering constraints)
+- You want visual, demo-friendly parallel execution in split terminals
+
+## Agent execution steps (FOLLOW EXACTLY)
+
+When `/team` is invoked, you MUST execute these steps in order:
+
+### Step 1 — Identify lanes
+
+Collect independent work lanes from the conversation context. Each lane needs:
+- `id`: short kebab-case identifier (e.g. `lane-a`, `fix-auth`)
+- `name`: human-readable name (e.g. `Upgrade dependencies`)
+- `prompt`: complete task prompt — must be self-contained with all context the agent needs (files to change, what to do, commit message)
+
+If no plan or lanes exist yet, ask the user what work to split.
+
+### Step 2 — Write lanes JSON
+
+Write a temporary lanes file at `/tmp/team-lanes-<timestamp>.json`:
+
+```json
+[
+  {
+    "id": "lane-a",
+    "name": "Short descriptive name",
+    "prompt": "Complete self-contained task prompt for the agent..."
+  },
+  {
+    "id": "lane-b",
+    "name": "Another lane name",
+    "prompt": "Another complete task prompt..."
+  }
+]
+```
+
+### Step 3 — Launch the team
+
+Run the launch script, passing the session name and lanes file path:
+
+```
+.github/skills/team/scripts/team-launch.sh --session "team-<name>" --lanes <lanes-file>
+```
+
+This will:
+- Split the **current tmux window** into panes (leader keeps its pane)
+- Launch `omp --madmax` interactively in each pane, then send the prompt
+- Arrange panes in a tiled grid layout
+- Print pane IDs and navigation commands
+
+### Step 4 — Report to user
+
+Show the user:
+- Which panes were created and what each is working on
+- Navigation: `Ctrl-b + arrow keys` to move between panes
+- How to check output: `tmux capture-pane -t <pane-id> -p -S -50`
+- How to kill panes when done
+
+## Prerequisites
+
+- `tmux` installed and running inside a tmux session
+- `omp` (oh-my-copilot) on PATH — preferred, launches with `omp --madmax`
+- Falls back to `copilot` if `omp` is not available
+- `jq` for JSON parsing
+
+## Prompt guidelines
+
+Each lane prompt must be **self-contained**. The agent in that pane has no context from this session. Include:
+- Exact files or directories to work in
+- What to do (fix, upgrade, accept, etc.)
+- How to verify (run tests, npm audit, etc.)
+- Commit message to use
+
+### Good prompt example
+
+> You are working in /Users/me/project. In src/auth/login.ts, replace the bcrypt password check with argon2. Update the import, change the verify call, and run `npm test -- --grep auth` to confirm. Commit with message "refactor: switch password hashing to argon2".
+
+### Bad prompt example
+
+> Fix the auth module. (Too vague — which file? What fix? How to verify?)
+
+## Composition
+
+Use `/ralplan` before `/team` to produce the plan that defines lanes. Use `/verify` after all panes complete to confirm combined results don't conflict.
+
+## Limitations
+
+- Each pane is an independent agent session — no shared state or messaging
+- Agents cannot communicate with each other — if tasks depend on each other, use `/ralph` instead
+- Leader (you) must manually verify results after all panes complete
+- Best for independent, non-conflicting work streams

package/.github/skills/team/scripts/team-launch.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# team-launch.sh — split the CURRENT tmux window into panes, each running
+# an interactive Copilot CLI agent session.
+#
+# Usage:
+#   team-launch.sh --session <name> --lanes <lanes.json>
+#
+# Each pane launches an interactive `omp --madmax` (or `copilot`) session,
+# then sends the lane prompt via tmux send-keys so the agent stays alive
+# for follow-up interaction.
+
+SESSION=""
+LANES_FILE=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --session) SESSION="$2"; shift 2 ;;
+    --lanes)   LANES_FILE="$2"; shift 2 ;;
+    *) echo "Unknown arg: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$SESSION" || -z "$LANES_FILE" ]]; then
+  echo "Usage: team-launch.sh --session <name> --lanes <lanes.json>" >&2
+  exit 1
+fi
+
+if [[ ! -f "$LANES_FILE" ]]; then
+  echo "Lanes file not found: $LANES_FILE" >&2
+  exit 1
+fi
+
+if ! command -v tmux &>/dev/null; then
+  echo "tmux not found" >&2
+  exit 1
+fi
+
+if [[ -z "${TMUX:-}" ]]; then
+  echo "Not inside a tmux session. Run this from within tmux." >&2
+  exit 1
+fi
+
+if command -v omp &>/dev/null; then
+  AGENT_CMD="omp --madmax"
+elif command -v copilot &>/dev/null; then
+  AGENT_CMD="copilot"
+else
+  echo "Neither omp nor copilot CLI found" >&2
+  exit 1
+fi
+
+LANE_COUNT=$(jq length "$LANES_FILE")
+if [[ "$LANE_COUNT" -lt 1 ]]; then
+  echo "No lanes defined in $LANES_FILE" >&2
+  exit 1
+fi
+
+CWD=$(pwd)
+WAIT_SECS="${TEAM_AGENT_WAIT:-5}"
+
+echo "🚀 Splitting current window into $LANE_COUNT panes ($SESSION)"
+echo ""
+
+# Collect pane IDs as we create them
+PANE_IDS=()
+
+for i in $(seq 0 $((LANE_COUNT - 1))); do
+  LANE_NAME=$(jq -r ".[$i].name" "$LANES_FILE")
+  LANE_PROMPT=$(jq -r ".[$i].prompt" "$LANES_FILE")
+  LANE_ID=$(jq -r ".[$i].id" "$LANES_FILE")
+
+  # Split: alternate horizontal/vertical for a grid
+  if (( i == 0 )); then
+    PANE_ID=$(tmux split-window -h -c "$CWD" -P -F '#{pane_id}')
+  elif (( i % 2 == 1 )); then
+    PANE_ID=$(tmux split-window -v -t "${PANE_IDS[$((i-1))]}" -c "$CWD" -P -F '#{pane_id}')
+  else
+    PANE_ID=$(tmux split-window -v -t "${PANE_IDS[$((i-2))]}" -c "$CWD" -P -F '#{pane_id}')
+  fi
+
+  PANE_IDS+=("$PANE_ID")
+
+  # Set pane title
+  tmux select-pane -t "$PANE_ID" -T "$LANE_ID: $LANE_NAME"
+
+  # Launch interactive agent session (NOT with -p)
+  tmux send-keys -t "$PANE_ID" "echo '═══ $LANE_NAME ═══' && $AGENT_CMD" C-m
+
+  echo "  ✅ Pane $PANE_ID → $LANE_NAME (launching agent...)"
+done
+
+# Rebalance layout
+tmux select-layout tiled
+
+# Wait for agents to start up before sending prompts
+echo ""
+echo "⏳ Waiting ${WAIT_SECS}s for agents to initialise..."
+sleep "$WAIT_SECS"
+
+# Now send prompts to each interactive session
+for i in $(seq 0 $((LANE_COUNT - 1))); do
+  LANE_PROMPT=$(jq -r ".[$i].prompt" "$LANES_FILE")
+  LANE_NAME=$(jq -r ".[$i].name" "$LANES_FILE")
+  PANE_ID="${PANE_IDS[$i]}"
+
+  # Write prompt to temp file and use tmux load-buffer + paste for reliable delivery
+  PROMPT_FILE="/tmp/team-prompt-${SESSION}-${i}.txt"
+  printf '%s' "$LANE_PROMPT" > "$PROMPT_FILE"
+
+  # Send via tmux send-keys -l (literal) then Enter
+  tmux send-keys -t "$PANE_ID" -l "$(cat "$PROMPT_FILE")"
+  tmux send-keys -t "$PANE_ID" C-m
+
+  echo "  📨 Sent prompt to $PANE_ID ($LANE_NAME)"
+done
+
+# Switch focus back to the original (leader) pane
+tmux select-pane -t '{left}'
+
+echo ""
+echo "✅ $LANE_COUNT interactive agent sessions running in split panes"
+echo ""
+echo "Pane IDs: ${PANE_IDS[*]}"
+echo ""
+echo "Commands:"
+echo "  tmux select-layout tiled              # rebalance layout"
+echo "  tmux capture-pane -t <pane-id> -p -S -50  # read pane output"
+echo "  Ctrl-b + arrow keys                   # navigate between panes"
+echo ""
+echo "💡 Agents are interactive — you can send follow-up prompts to any pane"

package/.github/skills/ultraqa/SKILL.md

@@ -7,14 +7,58 @@ description: Adversarial QA pass that tests behavior, failures, and regressions.
 
 Use `/ultraqa` after implementation when shallow checks are not enough.
 
-Do:
-- Test happy paths, hostile cases, and fallbacks.
-- Prefer runnable checks over inspection.
-- Record exact failures.
-- Route fixes back to `/ralph` or `/ultrawork`.
-
-Output:
-- `Scenarios`
-- `Results`
-- `Regressions`
-- `Fix recommendations`
+## When to use
+
+- Changes are complete but you're not confident they're correct
+- The change touches critical paths (auth, payments, data integrity)
+- You need to verify edge cases, error paths, and regressions
+
+## Do not use when
+
+- A simple `npm test` is sufficient — use `/verify`
+- You're still implementing — finish first, then QA
+
+## Steps
+
+### Cycle 1 (and each subsequent cycle)
+
+Number every cycle explicitly: "Cycle 1", "Cycle 2", etc.
+
+1. **Identify test surface** — what changed, what could break
+2. **Run existing tests** — baseline must pass before adversarial testing
+3. **Test happy path** — primary use case works
+4. **Test edge cases** — empty inputs, boundary values, concurrent access
+5. **Test error paths** — timeouts, bad data, missing deps
+6. **Test regressions** — did anything that previously worked now break?
+
+### After each cycle
+
+- If issues found → fix and start next cycle
+- If clean → report PASS and stop
+- Track which issues were found and fixed per cycle
+
+## Early exit conditions
+
+- **5 cycles reached** — stop, report remaining issues as known gaps
+- **Same failure 3 consecutive cycles** — stop, this is a design issue not a bug. Report it for `/ralplan`
+- **Critical regression found** — stop immediately, report before fixing anything else
+
+## Severity routing
+
+- **Critical** (data loss, security, crash) → immediate stop, fix before continuing
+- **Major** (broken feature, wrong output) → fix in current cycle
+- **Minor** (cosmetic, non-blocking) → log and continue, fix at end if time permits
+
+## Rules
+
+- Prefer runnable checks over inspection — run tests, don't just read code
+- If tests don't exist, write minimal ones that cover the change
+- Route fixes back to `/ralph` or `/ultrawork` if they're substantial
+
+## Output
+
+- `Cycles` — how many iterations, what was found/fixed in each
+- `Scenarios` — what was tested (happy, edge, error, regression)
+- `Results` — PASS/FAIL with trend across cycles
+- `Regressions` — anything that used to work but now doesn't
+- `Known gaps` — remaining issues after max cycles

package/.github/skills/ultrawork/SKILL.md

@@ -5,16 +5,69 @@ description: High-throughput execution for many independent small tasks. Use wit
 
 # Ultrawork
 
-Use `/ultrawork` when there are many independent, low-conflict work items.
-
-Do:
-- Batch independent tasks.
-- Avoid shared-file collisions.
-- Verify each batch.
-- Escalate ambiguous or risky branches to `/ralplan`.
-
-Output:
-- `Batch`
-- `Completed`
-- `Failed/blockers`
-- `Verification`
+Use `/ultrawork` when there are many independent, low-conflict work items that can be batched.
+
+## When to use
+
+- 5+ independent tasks with no shared files
+- Work is mechanical or repetitive (e.g. "fix all type errors", "update all imports")
+- Each task can be verified independently
+
+## Do not use when
+
+- Tasks share files or have ordering constraints — use `/ralph`
+- Tasks need design decisions — use `/ralplan` first
+- Fewer than 5 items — just do them inline
+
+## Composition
+
+Ultrawork is the **parallelism primitive** in the skill stack:
+```
+/omp-autopilot → /ralph (persistence) → /ultrawork (parallelism)
+```
+Ralph wraps ultrawork when a persistent verify loop is needed around batched work.
+
+## Steps
+
+### 1. Inventory
+
+List all tasks. For each, note the files it touches. Flag any collisions.
+
+### 2. Dependency check
+
+If tasks have ordering constraints, group them into **waves**:
+- Wave 1: tasks with no dependencies (fire all at once)
+- Wave 2: tasks that depend on wave 1 results
+- Complete each wave before starting the next
+
+If all tasks are independent, use a single wave.
+
+### 3. Execute
+
+Process each wave. For each task in the wave:
+- Execute the change
+- Verify it individually (test, lint, type-check)
+- Mark as done or failed
+
+### 4. Report
+
+Summarise: completed, failed, blocked.
+
+## Stop conditions
+
+- **Failure rate > 30%** — stop remaining tasks, report what failed and why
+- **Shared file collision discovered** — stop, re-partition, or escalate to `/ralph`
+- **Ambiguous task** — skip it, escalate to `/ralplan`
+
+## Rules
+
+- Verify each batch before moving to the next
+- If a task is ambiguous or risky, escalate — don't guess
+- Commit after each successful wave, not at the end
+
+## Output
+
+- `Waves` — how tasks were grouped
+- `Completed` — items done with evidence
+- `Failed/blockers` — items that couldn't be completed and why
+- `Verification` — test/lint/build results per wave

package/.github/skills/verify/SKILL.md

@@ -7,14 +7,32 @@ description: Prove completion claims with fresh evidence. Use with /verify befor
 
 Use `/verify` before saying done.
 
-Do:
-- State the claim.
-- Run or inspect the smallest checks that prove it.
-- Read outputs.
-- Report gaps honestly.
-
-Output:
-- `PASS/FAIL`
-- `Evidence`
-- `Known gaps`
-- `Stop condition`
+## When to use
+
+- You've completed a task and need to prove it works
+- Someone claims "it's done" and you need to confirm
+- Before creating a PR or handing off work
+
+## Steps
+
+1. **State the claim** — what is being verified (e.g. "auth flow works end-to-end")
+2. **Run checks** — the smallest set of commands/inspections that prove the claim:
+   - Tests: `npm test`, `pytest`, etc.
+   - Build: does it compile/build without errors?
+   - Lint: any new warnings?
+   - Behaviour: does the feature work as described?
+3. **Read outputs** — don't assume green means pass; read the actual results
+4. **Report honestly** — if there are gaps, say so
+
+## Rules
+
+- Fresh evidence only — don't rely on previous test runs
+- If a check fails, report it as a gap, don't hide it
+- Verify what was asked for, not more and not less
+
+## Output
+
+- `PASS` or `FAIL`
+- `Evidence` — command output, screenshots, or behaviour description
+- `Known gaps` — anything not verified and why
+- `Stop condition` — what would need to change for a different verdict

package/.github/skills/worktree/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: worktree
+description: Guides worktree-based workflow for parallel branch work. Use when user wants to start a new ticket, review a PR, or work on a branch without switching. Also use when user mentions worktree, branch switching, or parallel branch work.
+---
+
+# Worktree Workflow
+
+Use `/worktree` to set up a git worktree for a new ticket, PR review, or any branch work.
+
+## Why worktrees?
+
+- Your `main` branch stays untouched
+- Work on multiple tickets or reviews in parallel — no stashing, no context-switching
+- Each worktree is a full working copy — run tests, build, etc. independently
+
+## New ticket
+
+```bash
+cd <repo>
+git fetch origin
+git worktree add ../<repo>-<ticket-id> -b <ticket-id>
+cd ../<repo>-<ticket-id>
+```
+
+## PR review
+
+```bash
+cd <repo>
+git fetch origin
+git worktree add ../<repo>-review-<branch> origin/<branch>
+cd ../<repo>-review-<branch>
+```
+
+## Cleanup
+
+```bash
+cd <repo>
+git worktree remove ../<repo>-<ticket-id>
+# or list all worktrees
+git worktree list
+```
+
+## Agent behaviour
+
+When the user asks to work on a ticket or review a PR:
+
+1. `cd` into the repo's main clone
+2. `git fetch origin`
+3. Create a worktree with a descriptive name (ticket number or PR branch)
+4. Do all work inside the worktree, not the main clone
+5. Remind the user to clean up when the work is done