@damian87/omp 0.1.0 → 0.3.0

package/.github/copilot-instructions.md

@@ -18,3 +18,18 @@ Slash commands under `.github/skills/<name>/SKILL.md` are auto-discovered by Cop
 
 ## Hooks
 Lifecycle hooks declared in `hooks/hooks.json` invoke scripts in `scripts/`. Run `omp doctor` to verify discovery.
+
+## Session lifecycle: self-evolve
+
+Before ending a session, invoke `/self-evolve` to capture mistake patterns.
+
+Trigger when any of these apply:
+
+- The user says "done", "bye", "thanks", "wrapping up", "ship it", or types `/exit`.
+- You finish the user's last task with no pending todos and they have not requested follow-up.
+
+Skip when the session was fewer than 3 turns or contained no user corrections.
+
+Invoke `/self-evolve` **at most once per session.** After it reports back, do not invoke it again — even if the user replies "thanks" or "done" to the report itself. Just acknowledge and end the session.
+
+The skill lives at `.github/skills/self-evolve/SKILL.md`. It is self-contained: it tells you which signals count as corrections, where to log them, and when a recurring pattern should become a draft skill.

package/.github/skills/caveman/SKILL.md

@@ -7,14 +7,25 @@ description: Ultra-compact response mode with no filler. Use with /caveman when
 
 Use `/caveman` when user wants fewer tokens.
 
-Rules:
-- Short words.
-- No fluff.
-- Keep facts exact.
-- Use bullets.
-- Do not drop warnings, errors, paths, commands, or test evidence.
-
-Output:
-- Minimal.
-- Clear.
-- Correct.
+## Mode
+
+Once activated, all responses until deactivated follow caveman rules.
+
+## Rules
+
+- Short words. No filler. No pleasantries.
+- Bullets over paragraphs.
+- Keep facts exact — paths, commands, numbers, error messages.
+- Do not drop warnings, errors, or test evidence.
+- Code blocks over prose when showing changes.
+- One-word answers when one word is enough.
+
+## Examples
+
+**Normal**: "I've reviewed the file and found that the authentication middleware is missing a check for expired tokens. I'll add a validation step."
+
+**Caveman**: "Auth middleware missing token expiry check. Adding validation."
+
+## Deactivate
+
+Say "normal mode" or "/caveman off" to return to standard responses.

package/.github/skills/code-review/SKILL.md

@@ -7,16 +7,30 @@ description: Review completed changes for blockers, regressions, security, and s
 
 Use `/code-review` before merge or final handoff.
 
-Check:
-- Correctness
-- Regressions
-- Security/privacy
-- Maintainability
-- Scope creep
-- Test adequacy
-
-Output:
-- `Blocking`
-- `Non-blocking`
-- `Evidence reviewed`
-- `Verdict` — approve or request changes.
+## When to use
+
+- Changes are complete and ready for review
+- You need a second opinion before shipping
+- You want to catch regressions, security issues, or scope drift
+
+## Steps
+
+1. **Read the diff** — `git diff` for unstaged, `git diff --staged` for staged, or `git diff main...HEAD` for branch diff
+2. **Check for blockers** — bugs, logic errors, missing error handling, broken contracts
+3. **Check for security** — secrets in code, injection risks, auth gaps, unsafe defaults
+4. **Check for regressions** — does the change break existing tests or documented behaviour?
+5. **Check for scope drift** — does the change do more or less than requested?
+6. **Run tests** if they exist and haven't been run
+
+## Rules
+
+- Only flag issues that genuinely matter — no style nits, no formatting opinions
+- If the code works, tests pass, and scope is right, say so clearly
+- Flag anything you'd reject in a PR review
+
+## Output
+
+- `Verdict` — PASS / NEEDS_CHANGES / BLOCKER
+- `Blocking` — issues that must be fixed before merge
+- `Non-blocking` — suggestions or observations
+- `Evidence reviewed` — what was checked (diff, tests, build)

package/.github/skills/debug/SKILL.md

@@ -1,22 +1,38 @@
 ---
 name: debug
 description: Reproduce, minimize, diagnose, fix, and regression-test a bug. Use with /debug for broken, failing, slow, or confusing behavior.
+argument-hint: "<symptom or error message>"
 ---
 
 # Debug
 
 Use `/debug` for broken, failing, slow, or confusing behavior.
 
-Do:
-- Reproduce first.
-- Minimize the case.
-- Form ranked hypotheses.
-- Inspect evidence.
-- Fix root cause, not symptoms.
-- Add or run regression checks.
-
-Output:
-- `Repro`
-- `Cause`
-- `Fix`
-- `Regression test`
+## When to use
+
+- Tests are failing
+- Something is broken or throwing errors
+- Performance is unexpectedly slow
+- Behaviour is confusing or inconsistent
+
+## Steps (follow in order)
+
+1. **Reproduce** — get the failure to happen reliably. If you can't reproduce, that's important information.
+2. **Minimise** — find the smallest case that still fails. Strip away unrelated code/config.
+3. **Hypothesise** — form 2–3 ranked theories about the cause. Start with the most likely.
+4. **Inspect** — gather evidence for/against each hypothesis. Read code, add logging, check state.
+5. **Fix** — address the root cause, not just the symptom. If the fix is in the wrong layer, note it.
+6. **Regression test** — add or run a test that would have caught this bug. Verify it passes now.
+
+## Rules
+
+- Never guess-and-check without a hypothesis
+- If the first fix doesn't work, don't keep patching — re-examine the hypothesis
+- Document what you tried and why it did/didn't work
+
+## Output
+
+- `Repro` — steps to reproduce the issue
+- `Cause` — root cause with file:line evidence
+- `Fix` — what was changed and why
+- `Regression test` — test that proves the fix and prevents recurrence

package/.github/skills/grill-me/SKILL.md

@@ -5,12 +5,24 @@ description: Ask one sharp clarification question after codebase research when a
 
 # Grill Me
 
-Use `/grill-me` after `/codebase-research` when one decision blocks safe progress.
+Use `/grill-me` after `/research-codebase` when one decision blocks safe progress.
 
-Do:
-- State current understanding in 1-2 bullets.
-- Ask exactly one question.
-- Include a recommended answer.
-- Explain what the answer unlocks.
+## When to use
 
-Stop when enough is known for `/ralplan` or direct implementation.
+- Research is done but ambiguity remains
+- A design decision could go either way
+- You need the user's input before committing to an approach
+
+## Steps
+
+1. **State** current understanding in 1–2 bullets — show you've done the homework
+2. **Ask exactly one question** — the most important one that blocks progress
+3. **Include a recommended answer** — your best guess based on evidence
+4. **Explain what the answer unlocks** — what you can do once you know
+
+## Rules
+
+- One question at a time. Never batch questions.
+- Always include a recommended answer — make it easy to say "yes"
+- Stop grilling when enough is known for `/ralplan` or direct implementation
+- If the codebase can answer the question, answer it yourself instead of asking

package/.github/skills/jira-ticket/SKILL.md

@@ -7,15 +7,37 @@ description: Prepare Jira create, comment, and safe-update payloads with safe dr
 
 Use `/jira-ticket` when work tracking is requested.
 
-Do:
-- Create from an approved plan or slice.
-- Comment with implementation or verification evidence.
-- Safely update known simple fields.
-- Do not guess transitions, issue links, project keys, or secrets.
-- If config is missing, output a dry-run payload.
-
-Output:
-- `Operation`
-- `Target`
-- `Payload`
-- `Human action`
+## When to use
+
+- A plan or completed work needs a Jira ticket
+- You need to comment on or update an existing ticket
+- The user wants a ticket draft without actually creating it
+
+## Operations
+
+### Create
+- Build from an approved plan or implementation slice
+- Include: Summary, Description, Acceptance Criteria
+- If Jira config is available, create via API; otherwise output a dry-run payload
+
+### Comment
+- Add implementation evidence, verification results, or status updates
+- Format for readability (use Jira wiki markup, not Markdown)
+
+### Safe update
+- Only update known simple fields (summary, description, labels)
+- Do not guess transitions, issue links, project keys, or secrets
+
+## Rules
+
+- If Jira config is missing, always output a **dry-run payload** — never fail silently
+- Do not guess project keys, transitions, or credentials
+- Keep acceptance criteria testable and specific
+- Include file paths and evidence when commenting with implementation details
+
+## Output
+
+- `Operation` — create / comment / update
+- `Target` — ticket key or "new"
+- `Payload` — the Jira-formatted content
+- `Human action` — what the user needs to do (e.g. "paste into Jira" if dry-run)

package/.github/skills/omp-autopilot/SKILL.md

@@ -1,20 +1,75 @@
 ---
 name: omp-autopilot
 description: Full lightweight flow from research to plan, execution, review, and verification. Use with /omp-autopilot only for clear autonomous work. (Renamed from /autopilot to avoid collision with the Copilot CLI built-in.)
+argument-hint: "<task description>"
 ---
 
-# OMC Autopilot
+# OMP Autopilot
 
-Use `/omp-autopilot` only for clear autonomous work.
+Use `/omp-autopilot` only for clear autonomous work where the goal is unambiguous.
 
-Flow:
-1. `/codebase-research`
-2. `/grill-me` if ambiguity remains
-3. `/ralplan`
-4. `/team`, `/ralph`, or `/ultrawork`
-5. `/code-review`
-6. `/verify` or `/ultraqa`
-7. `/jira-ticket` if tracking is needed
+## When to use
 
-Do not skip verification.
-Ask only for destructive, credentialed, or materially ambiguous choices.
+- The task is well-defined and can be completed without human input
+- You have enough context to proceed end-to-end
+- The work is not destructive or credential-dependent
+
+## Do not use when
+
+- The request is vague or underspecified — use `/grill-me` first
+- The change is a single file fix — use `/ralph` directly
+- You need human decisions at multiple points — use `/ralplan` then manual execution
+
+## Phases
+
+### Phase 0 — Gate check
+
+If the request is vague (no clear deliverable, multiple interpretations), redirect to `/grill-me` and stop. Do not guess intent.
+
+### Phase 1 — Research
+
+Run `/research-codebase` to understand current state. Skip if you already have full context from the conversation.
+
+### Phase 2 — Plan
+
+Run `/ralplan` to produce an implementation plan with acceptance criteria. If a consensus plan already exists from a prior `/ralplan`, skip this phase.
+
+### Phase 3 — Execute
+
+Route based on plan shape:
+- **Independent parallel tasks** → `/team` (tmux panes)
+- **Single linear task** → `/ralph` (persistence loop)
+- **Many mechanical items** → `/ultrawork` (batch execution)
+
+### Phase 4 — Review
+
+Run `/code-review` on the diff. Fix any issues found before proceeding.
+
+### Phase 5 — Verify
+
+Run `/verify` or `/ultraqa` to prove the work is done. This phase is **mandatory** — never skip it.
+
+## Stop conditions
+
+- **Vague input** → redirect to `/grill-me`, do not proceed
+- **Phase fails 3 times** → stop, report the blocker
+- **Scope expands beyond original plan** → pause, report new scope, ask whether to continue
+- **Destructive or credentialed action needed** → stop and ask
+
+## Composition
+
+```
+/omp-autopilot wraps:
+  /research-codebase → /ralplan → /ralph or /team or /ultrawork → /code-review → /verify
+```
+
+Each inner skill can be invoked independently. Autopilot chains them.
+
+## Final checklist
+
+Before claiming done:
+- [ ] Every acceptance criterion from the plan is met
+- [ ] Tests pass (if applicable)
+- [ ] Lint clean (if applicable)
+- [ ] `/verify` or `/ultraqa` produced PASS evidence
+- [ ] No uncommitted work left behind

package/.github/skills/prototype/SKILL.md

@@ -7,15 +7,33 @@ description: Build a disposable experiment to answer one design, UI, state, or d
 
 Use `/prototype` when a cheap experiment beats guessing.
 
-Do:
-- State the question.
-- Build the smallest throwaway version.
-- Prefer isolated routes, fixtures, or tiny terminal demos.
-- Mark prototype code as disposable.
-- Decide keep, revise, or discard.
-
-Output:
-- `Question`
-- `Prototype`
-- `What we learned`
-- `Decision`
+## When to use
+
+- You're unsure about a design choice and need to try it
+- A UI layout, state shape, or API contract is unclear
+- "Let me try it" is faster than "let me think about it"
+
+## Steps
+
+1. **State the question** — what are you trying to learn? (e.g. "Does a tree or flat list work better for this state?")
+2. **Build the smallest throwaway version** — prefer:
+   - Isolated routes or pages
+   - Hardcoded fixtures instead of real data
+   - Terminal demos for backend logic
+   - Standalone scripts for API experiments
+3. **Mark as disposable** — prefix files with `prototype-` or put in a `prototype/` directory
+4. **Run it** — actually test the prototype, don't just write it
+5. **Decide** — keep (graduate to real code), revise (iterate), or discard (delete)
+
+## Rules
+
+- Prototypes are not production code — speed over polish
+- Delete prototypes that aren't kept — don't let them linger
+- One question per prototype — don't scope-creep
+
+## Output
+
+- `Question` — what was being tested
+- `Prototype` — what was built and where
+- `What we learned` — concrete findings
+- `Decision` — keep, revise, or discard

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

@@ -5,16 +5,65 @@ description: Single-owner execute-fix-verify loop for one clear task. Use with /
 
 # 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`
+Use `/ralph` when one owner should complete one clear task end-to-end.
+
+## When to use
+
+- A plan or concrete task already exists
+- The work is a single logical unit (not parallelisable)
+- You need persistent execution until done or blocked
+
+## Do not use when
+
+- Work has independent parallel lanes — use `/team`
+- 5+ mechanical tasks — use `/ultrawork`
+- No plan exists yet — use `/ralplan` first
+
+## Input
+
+Accept a plan from `/ralplan`, a ticket, or a concrete task description. If a `/ralplan` consensus plan exists, use its acceptance criteria as your definition of done.
+
+## Steps
+
+1. **Start** from the plan or task. State what "done" looks like before writing code.
+2. **Implement** one slice at a time, in plan order.
+3. **Verify after each slice** — run tests, lint, type-check. Do not batch verification to the end.
+4. **Fix** any failures immediately before moving to the next slice.
+5. **Repeat** until all slices complete with evidence, or a blocker is hit.
+6. **Final verification** — run the full test suite one last time after all slices.
+
+## Circuit breaker
+
+If the same issue fails **3 times** after 3 different fix attempts, **stop**. Report:
+- What was tried
+- Why each attempt failed
+- What information is missing
+
+Do not keep trying the same approach. Escalate the blocker.
+
+## Scope freeze
+
+If you discover work outside the original plan:
+- **Note it** in your output under "Known gaps"
+- **Do not chase it** — finish the planned work first
+- If it blocks the plan, stop and report
+
+## Rules
+
+- Never claim "done" without running verification
+- Commit working increments — don't batch everything into one commit
+- Read test output — don't assume green means pass
+
+## Final checklist
+
+Before claiming done:
+- [ ] Every plan slice implemented and verified individually
+- [ ] Full test suite passes after all slices
+- [ ] No lint or type errors introduced
+- [ ] Evidence of completion attached (test output, build log)
+
+## Output
+
+- `Done` — what was completed
+- `Evidence` — test output, build logs, or behaviour proof
+- `Known gaps` — anything intentionally left or discovered but out of scope

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

@@ -7,15 +7,24 @@ description: Produce an implementation-ready plan with risks, acceptance criteri
 
 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.
+## When to use
+
+- The change touches multiple files or components
+- There are unclear trade-offs or risks
+- You need alignment before implementation
+
+## Steps
+
+1. **Summarise** the target result and constraints in 2–3 sentences
+2. **List implementation slices** in execution order — each slice should be independently verifiable
+3. **Define acceptance criteria** — what must be true when done
+4. **Define test shape** — which tests to write or run, what they cover
+5. **Call out risks** — what could go wrong, tradeoffs chosen, alternatives rejected
+6. **Stop at the plan** unless the user explicitly asked to implement
+
+## Output
+
+- `Plan` — ordered implementation slices with file-level specificity
+- `Tests` — acceptance criteria and test shape for each slice
+- `Risks` — tradeoffs, concerns, and what was deliberately not done
+- `Ready for` — recommended next skill: `/team`, `/ralph`, `/ultrawork`, or direct edit

package/.github/skills/research-codebase/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: research-codebase
+description: Comprehensive codebase research that scales effort to task complexity, synthesises findings, and writes a timestamped document to docs/research/. Use when user says /research-codebase, asks to research or document a codebase area, or wants a deep-dive into how something works.
+argument-hint: "<area or question to research>"
+---
+
+# Research Codebase
+
+Read-only codebase research. Documents what EXISTS — no recommendations or critiques unless explicitly asked.
+
+## Contract (stated once)
+
+- ONLY describe what exists, where it exists, how it works, and how components interact
+- Do NOT suggest improvements, critique implementation, or propose changes
+- You are creating a technical map of the existing system
+
+## When invoked without a query
+
+Respond: "I'm ready to research the codebase. What area or question should I investigate?" — then wait.
+
+## Steps
+
+### 1. Read mentioned files
+
+If the user references specific files, read them with `view` in the **main context** before anything else.
+
+### 2. Scope the tech stack
+
+Detect from `package.json`, config files, directory structure, and project conventions. This determines which reference files are relevant — do NOT load unrelated framework guidance.
+
+### 3. Size the task → choose effort tier
+
+| Tier | When | Agent strategy |
+|------|------|----------------|
+| **Small** | Single file/component, narrow question | Main agent reads directly. No subagents. |
+| **Medium** | Cross-file, single area (e.g. "how does auth work") | 1–2 `explore` agents for locate + analyse |
+| **Large** | Cross-cutting, multi-area (e.g. "map the entire API layer") | Parallel locator → analyser → pattern-finder (see `reference/agent-prompts.md`) |
+
+### 4. Research
+
+- Track subtasks via SQL `todos` table
+- For medium/large: read `reference/agent-prompts.md` for subagent prompt templates
+- **MUST GATE**: Before writing findings, show file:line evidence for every claim
+
+### 5. Synthesise & write document
+
+- Read `reference/template.md` for output format and frontmatter
+- Read `reference/permalink.md` if GitHub permalinks are applicable
+- Gather git metadata: `date`, `user`, `commit`, `branch`, `repo`
+- Write to `docs/research/YYYY-MM-DD-description.md`
+
+### 6. Present findings
+
+Show concise summary to user with key file references. Ask if they have follow-up questions.
+
+### 7. Follow-ups
+
+If the user has follow-ups, read `reference/follow-up.md` for the append protocol.

package/.github/skills/research-codebase/reference/agent-prompts.md

@@ -0,0 +1,38 @@
+# Subagent Prompt Templates
+
+Use these templates when spawning `explore` agents via the `task` tool. Only used for **medium** and **large** research tasks.
+
+## Agent roles
+
+### Locator — find WHERE files and components live
+
+```
+Find all files and components related to [topic] in the codebase.
+Return file paths, directory structure, and a brief note on what each file contains.
+Do not evaluate or suggest improvements — only document what exists.
+```
+
+### Analyser — understand HOW specific code works
+
+```
+Read and document how [component] works.
+Describe the data flow, key functions, and how it connects to other components.
+Include file paths and line numbers.
+Do not critique or suggest improvements — only describe what exists.
+```
+
+### Pattern finder — find examples of existing patterns
+
+```
+Find all examples of [pattern] across the codebase.
+List each occurrence with file path, line number, and a brief description of how it's used.
+Do not evaluate consistency or suggest changes — only document occurrences.
+```
+
+## Guidelines
+
+- Each agent is stateless — provide complete context in the prompt
+- Remind every agent: "You are documenting, not evaluating"
+- Run independent explorations in parallel
+- For web research (only if user explicitly asks), use a `research` agent instead of `explore`
+- **Wait for ALL agents to complete before synthesising**

package/.github/skills/research-codebase/reference/follow-up.md

@@ -0,0 +1,21 @@
+# Follow-up Research Protocol
+
+When the user has follow-up questions after initial research:
+
+1. **Append** to the same research document — do not create a new file
+2. **Update frontmatter**:
+   - `last_updated: YYYY-MM-DD`
+   - `last_updated_by: [git user.name]`
+   - Add `last_updated_note: "Added follow-up research for [brief description]"`
+3. **Add a new section** at the end:
+   ```markdown
+   ## Follow-up Research [ISO timestamp]
+   
+   ### Question
+   [User's follow-up question]
+   
+   ### Findings
+   [New findings with file:line evidence]
+   ```
+4. **Spawn new agents** as needed (same tier sizing rules apply)
+5. **Connect** new findings to existing sections where relevant

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

@@ -0,0 +1,26 @@
+# GitHub Permalinks
+
+When the research is on `main`/`master` or the commit is pushed, replace local file references with GitHub permalinks.
+
+## Get repo info
+
+```bash
+gh repo view --json owner,name --jq '"\(.owner.login)/\(.name)"'
+```
+
+## Permalink format
+
+```
+https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}
+```
+
+For line ranges:
+```
+https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{start}-L{end}
+```
+
+## When to use
+
+- Only when on `main`/`master` or the commit is known to be pushed
+- Replace `path/to/file.ts:42` with the full permalink
+- Keep the local path as descriptive text: `[path/to/file.ts:42](permalink)`