@damian87/omp 0.1.0

package/.github/skills/ralph/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: ralph
+description: Single-owner execute-fix-verify loop for one clear task. Use with /ralph when one agent should keep going until evidence or blocker.
+---
+
+# Ralph
+
+Use `/ralph` when one owner should complete one clear task.
+
+Do:
+- Start from a plan or concrete task.
+- Implement in small steps.
+- Verify after each meaningful change.
+- Fix failures before claiming done.
+- Stop only with evidence or a blocker.
+
+Output:
+- `Done`
+- `Evidence`
+- `Known gaps`

package/.github/skills/ralplan/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: ralplan
+description: Produce an implementation-ready plan with risks, acceptance criteria, and test shape. Use with /ralplan when edits need planning first.
+---
+
+# Ralplan
+
+Use `/ralplan` when the task needs planning before edits.
+
+Do:
+- Summarize target result and constraints.
+- List implementation slices in order.
+- Define acceptance criteria and tests.
+- Call out risks and tradeoffs.
+- Stop at a plan unless user asked to implement.
+
+Output:
+- `Plan`
+- `Tests`
+- `Risks`
+- `Ready for` — `/team`, `/ralph`, `/ultrawork`, or direct edit.

package/.github/skills/self-evolve/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: self-evolve
+description: Capture user-correction patterns from this session and, when a pattern recurs, draft a new project skill. Use at end of session, when the user signals wrap-up, or when invoked directly.
+---
+
+# Self-Evolve
+
+Use `/self-evolve` to turn this session's mistakes into reusable project skills.
+
+## When to run
+
+- User signals end-of-session ("done", "bye", "thanks", "/exit", "wrapping up", "ship it").
+- You finish the user's last task with no pending todos and they have not requested follow-up.
+- The user invokes `/self-evolve` directly.
+
+**Skip if:** the session was fewer than 3 turns, or the session contained no user corrections.
+
+## What counts as a "correction"
+
+A user message right after one of your responses that pushes back on what you did. Signal phrases (case-insensitive):
+
+- explicit rejection: "no", "wrong", "that's wrong", "not what i asked", "undo", "revert"
+- redirection: "wait", "stop", "actually", "instead", "rather"
+- prohibition: "don't", "do not"
+
+Ignore false positives ("no problem", "stop the server", "don't worry") by checking that the phrase rebukes your prior action.
+
+## The loop
+
+### 0. Once-per-session guard
+
+Two checks. If **either** trips, stop immediately, say "self-evolve already ran this session", and do nothing else.
+
+**Exception (both checks):** if the user explicitly retyped `/self-evolve` to force a re-run, skip both checks.
+
+**Check A — conversation memory.** If you have already invoked `/self-evolve` in this conversation, stop.
+
+**Check B — durable marker.** Read `.oh-my-copilot/self-evolve/.last-run-session` (single-line UUID, may not exist). Determine the current Copilot CLI session UUID via shell:
+
+```
+ls -td ~/.copilot/session-state/*/ 2>/dev/null | head -1 | xargs -n1 basename
+```
+
+If the marker file exists and its contents match the current session UUID, stop. (If `~/.copilot/session-state/` is empty or unreadable, skip Check B and rely on Check A alone.)
+
+Check B survives session resume (`copilot --resume`) and conversation compaction, where Check A could miss the earlier invocation.
+
+### 1. Inspect this session
+
+Walk back through the conversation and list every correction event. For each, record:
+
+- **topic** — short kebab-case label (e.g. `trailing-newline-shell-output`, `python-string-quotes`, `unwanted-readme-edits`)
+- **area** — file path or subsystem the correction touched, or `-` if none
+- **summary** — one sentence: what you did wrong and what the user wanted instead
+
+### 2. Append to the ledger
+
+The ledger lives at `.oh-my-copilot/self-evolve/log.md`. Create the directory and file if missing. Append one entry per correction in this exact shape:
+
+```
+- YYYY-MM-DD | <topic> | <area> | <summary>
+```
+
+Keep entries chronological. Never rewrite past entries.
+
+### 3. Count repeats
+
+For each new topic from this session, grep the ledger for the same topic label. The count includes today's entries.
+
+**Threshold: 3 occurrences.** Fewer → stop here.
+
+### 4. Check existing coverage
+
+Before drafting, list:
+
+- `.github/skills/*/SKILL.md` (project skills, including any previously promoted `learned-*`)
+- `.oh-my-copilot/self-evolve/drafts/*/SKILL.md` (in-flight drafts not yet promoted)
+- `~/.copilot/skills/*/SKILL.md` (user skills, if present)
+
+**Match bar (high, not vague).** A skill counts as covering this topic only if:
+
+- its frontmatter `description` explicitly names the exact behavior the user kept correcting, **OR**
+- it contains a `Do` or `Don't` bullet that, applied literally, would have prevented every correction in the cluster.
+
+Generic adjacency does **not** count. A "code quality" skill does not cover "respect Python quote style"; a "respect-quotes" skill does. When in doubt, treat as not covered.
+
+**If clearly covered**, do not draft. Append one note to the ledger and stop:
+
+```
+# covered-by: <existing-skill-name> | <topic>
+```
+
+**If covered ambiguously** (some bullets are adjacent but none are a direct match), still draft — but add a line to the new draft's `Source` section noting the overlap, so a human reviewer can decide on merge or supersede:
+
+```
+possible-duplicate-of: <existing-skill-name>
+```
+
+Bias: when unsure, draft. Drafts live in `.oh-my-copilot/self-evolve/drafts/` and are inert until a human promotes them, so a stray draft costs nothing while a missed pattern wastes signal.
+
+### 5. Draft the new skill
+
+**Path:** `.oh-my-copilot/self-evolve/drafts/<slug>/SKILL.md`
+
+**This is outside `.github/skills/` on purpose.** Drafts must NOT live in the plugin's active skill root: anything under `.github/skills/` is loaded as an active skill on the next Copilot session, so a draft there would silently auto-arm before a human reviewed it. The `.oh-my-copilot/self-evolve/drafts/` location is never read by Copilot CLI; a human promotes a draft by moving its directory to `.github/skills/learned-<slug>/` (see `docs/self-evolve.md`).
+
+- Slug rule: kebab-case of the topic, max 40 chars.
+- The draft's frontmatter `name` should be `learned-<slug>` (matches the target dir name a human will promote it into).
+
+Write the file with this exact frontmatter and body:
+
+```
+---
+name: learned-<slug>
+description: <one sentence — when this skill should fire>
+status: draft
+---
+
+# Learned: <human title>
+
+Invoke `/learned-<slug>` when the trigger below applies.
+
+## Trigger
+<one-line condition derived from the recurring corrections>
+
+## Do
+<concrete instruction(s) that would have prevented the corrections>
+
+## Don't
+<the wrong behaviour you kept doing>
+
+## Source
+Drafted by /self-evolve from 3+ corrections in .oh-my-copilot/self-evolve/log.md.
+Promote to active by moving this directory to .github/skills/learned-<slug>/.
+```
+
+### 6. Report to the user
+
+State:
+
+- how many corrections this session contributed to the ledger,
+- whether any topic crossed the threshold,
+- the path of any draft skill written,
+- the path of the ledger.
+
+### 7. Persist the session marker
+
+Before exiting, write the current Copilot CLI session UUID to `.oh-my-copilot/self-evolve/.last-run-session` (overwrite, no newline needed). Use the same shell line as Step 0 to determine it. Subsequent invocations within the same session will short-circuit via Check B in Step 0.
+
+If `~/.copilot/session-state/` was empty or unreadable in Step 0, write the literal string `unknown-session` so the marker exists but cannot accidentally match a real UUID later.
+
+## Output discipline
+
+- One ledger line per correction. Never batch into a paragraph.
+- One draft skill per recurring topic. Never combine unrelated topics.
+- Drafts always carry `status: draft`. A human promotes them by moving the draft directory from `.oh-my-copilot/self-evolve/drafts/<slug>/` into `.github/skills/learned-<slug>/` (and optionally deleting the `status: draft` line). Until that move, the draft is inert — Copilot CLI does not load it.
+- If unsure whether something is a correction, skip it. False negatives are cheap; false positives pollute the loop.

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

@@ -0,0 +1,19 @@
+---
+name: tdd
+description: Red-green-refactor loop for behavior changes where tests are practical. Use with /tdd when a change can be specified by tests.
+---
+
+# TDD
+
+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`.

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

@@ -0,0 +1,20 @@
+---
+name: team
+description: Split an approved plan into parallel lanes for agents or humans. Use with /team when work has independent lanes.
+---
+
+# Team
+
+Use `/team` when work has independent lanes.
+
+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.
+
+Output:
+- `Lanes`
+- `Shared files`
+- `Order/dependencies`
+- `Verification`

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

@@ -0,0 +1,20 @@
+---
+name: ultraqa
+description: Adversarial QA pass that tests behavior, failures, and regressions. Use with /ultraqa after implementation when shallow checks are not enough.
+---
+
+# UltraQA
+
+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`

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

@@ -0,0 +1,20 @@
+---
+name: ultrawork
+description: High-throughput execution for many independent small tasks. Use with /ultrawork when work can be batched safely.
+---
+
+# 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`

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

@@ -0,0 +1,20 @@
+---
+name: verify
+description: Prove completion claims with fresh evidence. Use with /verify before saying done.
+---
+
+# Verify
+
+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`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damian Borek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# oh-my-copilot
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+**Multi-agent orchestration for GitHub Copilot CLI. Zero learning curve.**
+
+_Don't relearn Copilot. Just use omp._
+
+[Quick Start](#quick-start) • [Features](#features) • [In-session shortcuts](#in-session-shortcuts) • [Roadmap](#roadmap) • [Documentation](#documentation)
+
+---
+
+## Quick Start
+
+**Step 1: Install**
+
+Two commands install all 17 omp skills as a Copilot CLI plugin:
+
+```bash
+copilot plugin marketplace add damian87x/oh-my-copilot
+copilot plugin install oh-my-copilot@oh-my-copilot
+```
+
+Requires Copilot CLI v1.0.48+. After install, `/omp-autopilot`, `/ralplan`, `/code-review`, `/create-skill`, `/self-evolve`, and the rest are available inside any Copilot session.
+
+If you prefer the npm path for the local runtime:
+
+```bash
+npm i -g @damian87/omp
+```
+
+**Step 2: Build something**
+
+```bash
+# Bare-flag launch with permissions bypass (alias of copilot --yolo)
+omp --madmax -p "build a REST API for managing tasks"
+
+# Or via in-session skill
+/omp-autopilot "build a REST API for managing tasks"
+```
+
+That's it.
+
+---
+
+## Why oh-my-copilot?
+
+- **Zero configuration** — works out of the box with sane defaults
+- **Team-first orchestration** — staged pipelines on a shared task list
+- **Bare-flag bypass** — `omp --madmax` injects `--yolo` so non-interactive runs never block on a permission prompt
+- **Persistent execution** — Ralph, UltraQA, and Ultrawork keep going until the goal is verified
+- **MCP-powered shared state** — workers swap typed messages over an outbox/inbox cursor instead of summarising each other's summaries
+- **Lifecycle hooks** — `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `SessionEnd`, `Error`
+- **Doctor included** — `omp doctor` verifies plugin manifest, skills discovery, hooks, and the underlying `copilot` CLI in one shot
+
+---
+
+## Features
+
+### Orchestration Modes
+
+| Mode                 | What it is                                                       | Best for                                       |
+| -------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
+| **Team**             | tmux CLI workers on a shared task list with file-state outbox    | Coordinated parallel work on one objective     |
+| **Autopilot**        | Single-lead autonomous loop (`/omp-autopilot`)                   | End-to-end feature work with minimal ceremony  |
+| **Ralph**            | Persistent verify/fix loop with explicit reviewer                | Tasks that must complete fully (no partials)   |
+| **Ultrawork**        | Maximum parallelism for fan-out tasks                            | Burst parallel fixes / refactors               |
+| **UltraQA**          | QA cycling until tests/build/lint/typecheck all pass             | Quality gates needing repeat diagnose/fix      |
+| **Ralplan**          | Consensus planning step before any loop                          | Vague requests that need decomposition first   |
+| **Madmax (CLI)**     | `omp --madmax …` — bypass permissions for non-interactive runs   | Scripted / automated copilot invocations       |
+
+### Intelligent Orchestration
+
+- **7 specialized agents** — planner, architect, executor, verifier, code-reviewer, designer, researcher (all `--agent <name>` compatible with Copilot CLI)
+- **17 in-session skills** auto-discovered from `.github/skills/`
+- **Smart pipeline routing** — `/codebase-research` → `/ralplan` → `/team` / `/ralph` / `/ultrawork` → `/code-review` → `/ultraqa`
+
+### Developer Experience
+
+- **MCP server** ships with `notepad`, `project-memory`, `shared-memory`, `state`, and `trace` tools out of the box
+- **File-state coordination** — outbox JSONL + byte cursor, atomic `O_EXCL` task locks, optimistic CAS on claim
+- **Idle nudge** — content-based pane idle detection that pokes stuck workers
+- **Mode-state loops** — single source of truth per loop (Ralph/Ultrawork/UltraQA state files)
+
+---
+
+## In-session shortcuts
+
+These run **inside a Copilot CLI session** after the plugin is installed.
+
+| In-session form         | Effect                                                    | Example                                              |
+| ----------------------- | --------------------------------------------------------- | ---------------------------------------------------- |
+| `/omp-autopilot`        | Full autonomous execution                                 | `/omp-autopilot "build a todo app"`                  |
+| `/ralph`                | Persistence mode                                          | `/ralph "refactor auth"`                             |
+| `/ultrawork`            | Maximum parallelism                                       | `/ultrawork "fix all type errors"`                   |
+| `/ultraqa`              | QA cycling until goal met                                 | `/ultraqa "build green, tests pass"`                 |
+| `/ralplan`              | Consensus planning                                        | `/ralplan "plan this feature"`                       |
+| `/team`                 | Coordinated multi-agent task list                         | `/team 3:executor "ship the migration"`              |
+| `/code-review`          | Diff-focused reviewer                                     | `/code-review`                                       |
+| `/codebase-research`    | Map an area of the codebase                               | `/codebase-research "auth middleware"`               |
+| `/debug`                | Disciplined diagnose-reproduce-fix loop                   | `/debug "flaky integration test"`                    |
+| `/tdd`                  | Red-green-refactor cycle                                  | `/tdd "add pagination to /users"`                    |
+| `/verify`               | Exercise a change end-to-end                              | `/verify`                                            |
+| `/create-skill`         | Author a new skill                                        | `/create-skill`                                      |
+| `/self-evolve`          | Extract a learned skill from this session                 | `/self-evolve`                                       |
+| `/jira-ticket`          | Render or apply a Jira ticket payload                     | `/jira-ticket`                                       |
+| `/prototype`            | Throwaway prototype to flesh out a design                 | `/prototype "state shape"`                           |
+| `/grill-me`             | Stress-test a plan with Socratic questions                | `/grill-me`                                          |
+| `/caveman`              | Ultra-compressed communication mode                       | `/caveman`                                           |
+
+---
+
+## Terminal CLI
+
+```bash
+omp --help
+omp version
+omp doctor                                  # verify install + copilot binary
+omp list                                    # show discovered skills and agents
+omp setup [--dry-run] [--scope project|user]
+omp launch -- [copilot flags…]              # forward arbitrary args to copilot
+omp --madmax -p "edit src/foo.ts"           # bare-flag, maps to copilot --yolo
+omp team 3:executor "fix all type errors"   # spawn tmux workers
+omp team status <name>
+omp team shutdown <name>
+omp ralph start "<task>" [--max-iterations N]
+omp ultrawork start "<objective>" [--task-count N]
+omp ultraqa start "<goal>" [--max-cycles N]
+omp mcp                                     # MCP server over stdio
+omp catalog list | validate | capability <id>
+omp jira render <plan-file>
+omp jira apply <key-or-plan> --comment|--update|--transition|--link
+```
+
+Environment overrides:
+
+- `OMP_PLUGIN_ROOT` — path to the plugin checkout (with `OMC_PLUGIN_ROOT` accepted for back-compat)
+- `OMP_COPILOT_BIN` — alternate `copilot` binary
+
+---
+
+## Roadmap
+
+omp is intentionally small today and growing in vertical slices.
+
+### v0.2 — Notification gateways
+
+Telegram, Discord, Slack, and generic webhook integration so long-running modes can ping you when they finish, fail, or stall. Tag with `--telegram` / `--discord` / `--slack` per invocation; configure once with `omp notify add`.
+
+### v0.3 — Checkpoints + rollback
+
+Auto-snapshot the working tree before any tool-driven file edit. `omp rollback [id]` to revert a checkpoint. A safety net for autonomous loops that go wide before they go right.
+
+### v0.4 — Provider advisor (`omp ask`)
+
+One command to consult an alternate provider CLI (`claude`, `codex`, `gemini`) and save the response as a markdown artifact under `.omp/artifacts/ask/`. Same surface in-session via `/ask`.
+
+### v0.5 — Scheduled tasks
+
+Natural-language cron: `omp schedule "every weekday 9am run /code-review on main"`. Jobs can attach skills, deliver results to a notification gateway, and support pause/resume/edit. Built on the same mode-state primitives Ralph and UltraQA use.
+
+### v0.6 — Browser tool (MCP)
+
+A first-class browser MCP tool: web search, page extraction, full automation (navigate, click, type, screenshot). For research skills that need fresh data instead of training-cutoff guesses.
+
+### v0.7 — HUD-lite statusline
+
+Live orchestration metrics in the terminal: active mode, current task, worker count, tokens, cache hit rate, last error.
+
+### v0.8 — Provider routing
+
+Fine-grained per-task provider selection — sorting, whitelists, priority ordering, cost-aware fallback. For mixed pipelines that want Opus for planning and Haiku for grunt work without manual model switching.
+
+### v0.9 — Skill learning
+
+Extract repeating patterns from session transcripts into reusable skill files with strict quality gates. Auto-injects into context when relevant triggers fire.
+
+### v1.0 — Pre-built agent templates
+
+One-shot deployable templates for common workflows: research, security audit, design-system migration, content automation. `omp template add <name>` drops a curated skill + agent pair into your project.
+
+---
+
+## Documentation
+
+- [General skills](docs/general-skills.md) — slash-skill layout, capability IDs, portability rules
+- [Copilot distribution](docs/copilot-distribution.md) — project/user skill installs and the case against GitHub App Extensions
+- [Jira adapter](docs/jira.md) — configuration discovery, safe operations, dry-runs, fallback payloads
+- [Self-evolve](docs/self-evolve.md) — extracting reusable skills from session transcripts
+
+## Layout
+
+```text
+.github/agents/<name>.md          # custom agents discoverable via --agent
+.github/skills/<name>/SKILL.md    # in-session slash skills
+hooks/hooks.json                  # lifecycle hook manifest
+scripts/*.mjs                     # hook implementations
+src/                              # omp CLI, MCP server, team runtime, mode-state loops
+```
+
+Skills follow the [Copilot agent-skills docs](https://docs.github.com/en/copilot) — project skills live in `.github/skills/` and are invoked with `/skill-name`.
+
+---
+
+## Local development
+
+```bash
+npm install
+npm run build
+npm test                                       # 137 tests
+npm run lint:skills
+npm run sync:dry-run
+npx tsx src/cli.ts skill install .github/skills/create-skill --dry-run
+```