oh-my-githubcopilot 1.5.7 → 1.8.0-alpha.021bf87

package/skills/omp-doctor/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: omp-doctor
+description: Diagnose and fix oh-my-githubcopilot installation issues
+trigger: /omp:omp-doctor
+level: 3
+---
+
+# OMP Doctor Skill
+
+## Task: Run Installation Diagnostics
+
+You are the OMP Doctor — diagnose and fix installation issues for the oh-my-githubcopilot plugin.
+
+### Step 1: Check Plugin Version
+
+```bash
+# Check installed plugin version
+node -e "const p=require('path'),f=require('fs'),h=require('os').homedir(),b=p.join(h,'.config','github-copilot','plugins','oh-my-githubcopilot');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));console.log('Installed:',v.length?v[v.length-1]:'(none)')}catch{console.log('Installed: (none)')}"
+npm view oh-my-githubcopilot version 2>/dev/null || echo "Latest: (unavailable)"
+```
+
+**Diagnosis**:
+- If no version installed: CRITICAL - plugin not installed
+- If INSTALLED != LATEST: WARN - outdated plugin
+- If multiple versions exist: WARN - stale cache
+
+### Step 2: Check plugin.json
+
+Read `~/.config/github-copilot/plugin.json` and verify:
+- `oh-my-githubcopilot` is listed as an active plugin
+- The version entry matches the installed version
+
+**Diagnosis**:
+- If plugin.json missing: CRITICAL - plugin not registered
+- If `oh-my-githubcopilot` not listed: CRITICAL - plugin not activated
+- If version mismatch: WARN - version drift
+
+### Step 3: Check Skills Directory
+
+```bash
+ls -la ~/.config/github-copilot/plugins/oh-my-githubcopilot/skills/ 2>/dev/null
+```
+
+**Diagnosis**:
+- If skills/ missing or empty: CRITICAL - skills not installed
+- If known skills are missing entries: WARN - incomplete skill set
+
+**Known skill names** (check skills/ for these):
+`autopilot`, `configure-notifications`, `deep-interview`, `ecomode`, `graphify`, `graphwiki`, `hud`, `learner`, `mcp-setup`, `note`, `omp-doctor`, `omp-plan`, `omp-reference`, `omp-setup`, `pipeline`, `ralph`, `release`, `research`, `setup`, `spending`, `swarm`, `team`, `trace`, `ultrawork`, `wiki`
+
+### Step 4: Check Agents Directory
+
+```bash
+ls -la ~/.config/github-copilot/plugins/oh-my-githubcopilot/agents/ 2>/dev/null
+```
+
+**Diagnosis**:
+- If agents/ missing: CRITICAL - agents not installed
+- If known agents are missing: WARN - incomplete agent set
+
+**Known agent names** (check agents/ for these):
+`orchestrator`, `explorer`, `planner`, `executor`, `verifier`, `writer`, `reviewer`, `designer`, `researcher`, `tester`, `debugger`, `architect`, `security-reviewer`, `simplifier`, `test-engineer`, `critic`, `tracer`, `scientist`, `code-reviewer`, `document-specialist`, `qa-tester`, `git-master`, `analyst`
+
+### Step 5: Check AGENTS.md
+
+```bash
+ls -la ~/.config/github-copilot/plugins/oh-my-githubcopilot/AGENTS.md 2>/dev/null
+```
+
+**Diagnosis**:
+- If AGENTS.md missing: WARN - orchestration brain not found
+
+### Step 6: Check for Stale Plugin Cache
+
+```bash
+node -e "const p=require('path'),f=require('fs'),h=require('os').homedir(),b=p.join(h,'.config','github-copilot','plugins','oh-my-githubcopilot');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x));console.log(v.length+' version(s):',v.join(', '))}catch{console.log('0 versions')}"
+```
+
+**Diagnosis**:
+- If > 1 version: WARN - multiple cached versions (cleanup recommended)
+
+---
+
+## Report Format
+
+After running all checks, output a report:
+
+```
+## OMP Doctor Report
+
+### Summary
+[HEALTHY / ISSUES FOUND]
+
+### Checks
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Plugin Version | OK/WARN/CRITICAL | ... |
+| plugin.json Registration | OK/CRITICAL | ... |
+| Skills Directory | OK/WARN/CRITICAL | ... |
+| Agents Directory | OK/WARN/CRITICAL | ... |
+| AGENTS.md | OK/WARN | ... |
+| Plugin Cache | OK/WARN | ... |
+
+### Issues Found
+1. [Issue description]
+2. [Issue description]
+
+### Recommended Fixes
+[List fixes based on issues]
+```
+
+---
+
+## Auto-Fix (if user confirms)
+
+If issues found, ask user: "Would you like me to fix these issues automatically?"
+
+If yes, apply fixes:
+
+### Fix: Outdated Plugin
+
+```bash
+npm install -g oh-my-githubcopilot@latest
+```
+
+### Fix: Stale Cache (multiple versions)
+
+```bash
+node -e "const p=require('path'),f=require('fs'),h=require('os').homedir(),b=p.join(h,'.config','github-copilot','plugins','oh-my-githubcopilot');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));v.slice(0,-1).forEach(x=>f.rmSync(p.join(b,x),{recursive:true,force:true}));console.log('Removed',v.length-1,'old version(s)')}catch(e){console.log('No cache to clean')}"
+```
+
+### Fix: Missing/Corrupt Installation
+
+Re-run the setup skill:
+
+```
+/omp:omp-setup
+```
+
+---
+
+## Post-Fix
+
+After applying fixes, inform user:
+> Fixes applied. **Restart GitHub Copilot CLI** for changes to take effect.

package/skills/omp-plan/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: omp-plan
-description: OMP-aware strategic planning
-trigger: "plan:, /plan, /omp:plan, /omp-plan"
+description: OMP-aware strategic planning with interview, direct, consensus, and review modes
+trigger: "plan:, /plan, /omp:plan, /omp-plan, --consensus"
 autoinvoke: false
 ---
+
 # Skill: OMP-Plan
 
 ## Metadata
@@ -11,13 +12,13 @@ autoinvoke: false
 | Field | Value |
 |-------|-------|
 | **ID** | `omp-plan` |
-| **Keywords** | `plan:`, `/plan` |
+| **Keywords** | `plan:`, `/plan`, `/omp:plan`, `/omp-plan`, `--consensus` |
 | **Tier** | Execution Mode |
 | **Source** | `src/skills/omp-plan.mts` |
 
 ## Description
 
-Strategic planning mode with optional interview workflow. Delays implementation until plan is approved.
+Strategic planning mode with optional interview workflow. Supports four modes: Interview (broad requests), Direct (detailed requests), Consensus (iterative Planner/Architect/Critic loop with RALPLAN-DR structured deliberation), and Review (Critic evaluation of an existing plan). Delays implementation until the plan is approved.
 
 ## Interface
 
@@ -39,3 +40,213 @@ export function deactivate(): void
 ## Implementation
 
 Activates the `plan` strategic planning mode by spawning `bin/omp.mjs plan [args]`. No persistent resources are maintained.
+
+---
+
+## Flags
+
+```
+omp-plan [--direct|--consensus|--review] [--interactive] [--deliberate] <task description>
+```
+
+| Flag | Description |
+|------|-------------|
+| `--direct` | Skip interview, generate plan immediately |
+| `--consensus` | Run Planner → Architect → Critic loop (RALPLAN-DR) |
+| `--review` | Critic evaluation of an existing plan |
+| `--interactive` | Enable user prompts at draft review and final approval steps (consensus mode) |
+| `--deliberate` | Force deliberate RALPLAN-DR mode: adds pre-mortem + expanded test plan |
+
+---
+
+## Mode Selection
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Interview | Default for broad requests | Interactive requirements gathering |
+| Direct | `--direct`, or detailed request | Skip interview, generate plan directly |
+| Consensus | `--consensus`, "ralplan" | Planner → Architect → Critic loop until agreement with RALPLAN-DR structured deliberation (short by default, `--deliberate` for high-risk); add `--interactive` for user prompts at draft and approval steps |
+| Review | `--review`, "review this plan" | Critic evaluation of existing plan |
+
+---
+
+## Interview Mode (broad/vague requests)
+
+1. **Classify the request**: Broad (vague verbs, no specific files, touches 3+ areas) triggers interview mode
+2. **Ask one focused question** using `AskUserQuestion` for preferences, scope, and constraints
+3. **Gather codebase facts first**: Before asking "what patterns does your code use?", explore the codebase to find out, then ask informed follow-up questions
+4. **Build on answers**: Each question builds on the previous answer
+5. **Consult Analyst** for hidden requirements, edge cases, and risks
+6. **Create plan** when the user signals readiness: "create the plan", "I'm ready", "make it a work plan"
+
+**Question Classification**:
+
+| Type | Examples | Action |
+|------|----------|--------|
+| Codebase Fact | "What patterns exist?", "Where is X?" | Explore first, do not ask user |
+| User Preference | "Priority?", "Timeline?" | Ask user via AskUserQuestion |
+| Scope Decision | "Include feature Y?" | Ask user |
+| Requirement | "Performance constraints?" | Ask user |
+
+---
+
+## Direct Mode (detailed requests)
+
+1. **Quick Analysis**: Optional brief Analyst consultation
+2. **Create plan**: Generate comprehensive work plan immediately
+3. **Review** (optional): Critic review if requested
+
+---
+
+## Consensus Mode (`--consensus` / "ralplan")
+
+**RALPLAN-DR modes**: **Short** (default, bounded structure) and **Deliberate** (for `--deliberate` or explicit high-risk requests: auth/security, data migration, destructive/irreversible changes, production incident, compliance/PII, public API breakage). Both modes keep the same Planner → Architect → Critic sequence and the same `AskUserQuestion` gates.
+
+**Consensus mode runs fully automated by default**; add `--interactive` to enable user prompts at draft review (step 2) and final approval (step 6).
+
+### Steps
+
+1. **Planner** creates initial plan and a compact **RALPLAN-DR summary** before any Architect review. The summary **MUST** include:
+   - **Principles** (3-5)
+   - **Decision Drivers** (top 3)
+   - **Viable Options** (>=2) with bounded pros/cons for each option
+   - If only one viable option remains, an explicit **invalidation rationale** for alternatives that were rejected
+   - In **deliberate mode**: a **pre-mortem** (3 failure scenarios) and an **expanded test plan** covering unit / integration / e2e / observability
+
+2. **User feedback** *(--interactive only)*: If running with `--interactive`, **MUST** use `AskUserQuestion` to present the draft plan **plus the RALPLAN-DR Principles / Decision Drivers / Options summary** with these options:
+   - **Proceed to review** — send to Architect and Critic for evaluation
+   - **Request changes** — return to step 1 with user feedback incorporated
+   - **Skip review** — go directly to final approval (step 6)
+   If NOT running with `--interactive`, automatically proceed to review (step 3).
+
+3. **Architect** reviews for architectural soundness. Adopt the Architect role and review the plan for:
+   - Strongest steelman counterargument (antithesis) against the favored option
+   - At least one meaningful tradeoff tension
+   - A synthesis path when possible
+   - In deliberate mode: explicitly flag principle violations
+   
+   **Wait for this step to complete before proceeding to step 4. Do NOT run steps 3 and 4 in parallel.**
+
+   > Invoke the architect agent to review the plan. If using a sub-agent: "Adopt the Architect role and review this plan for architectural soundness. Provide the strongest steelman antithesis against the favored option, at least one real tradeoff tension, and a synthesis path where possible."
+
+4. **Critic** evaluates against quality criteria. Run only after step 3 is complete.
+   - Verify principle-option consistency
+   - Fair alternative exploration
+   - Risk mitigation clarity
+   - Testable acceptance criteria
+   - Concrete verification steps
+   - In deliberate mode: **MUST** reject missing/weak pre-mortem or missing/weak expanded test plan
+
+   > Invoke the critic agent to evaluate the plan. If using a sub-agent: "Adopt the Critic role and evaluate this plan. Verify principle-option consistency, fair alternative exploration, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. Reject shallow alternatives, driver contradictions, vague risks, or weak verification."
+
+5. **Re-review loop** (max 5 iterations): If Critic rejects, execute this closed loop:
+   a. Collect all rejection feedback from Architect + Critic
+   b. Pass feedback to Planner to produce a revised plan
+   c. **Return to Step 3** — Architect reviews the revised plan
+   d. **Return to Step 4** — Critic evaluates the revised plan
+   e. Repeat until Critic approves OR max 5 iterations reached
+   f. If max iterations reached without approval, present the best version to user via `AskUserQuestion` with note that expert consensus was not reached
+
+6. **Apply improvements**: When reviewers approve with improvement suggestions, merge all accepted improvements into the plan file before proceeding. Final consensus output **MUST** include an **ADR** section with: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups.
+   a. Collect all improvement suggestions from Architect and Critic responses
+   b. Deduplicate and categorize the suggestions
+   c. Update the plan file in `.omp/plans/` with the accepted improvements
+   d. Note which improvements were applied in a brief changelog section at the end of the plan
+
+7. On Critic approval *(--interactive only)*: If running with `--interactive`, use `AskUserQuestion` to present the plan with these options:
+   - **Approve and implement via team** (Recommended) — proceed to implementation via `omp:team`
+   - **Approve and execute via ralph** — proceed to implementation via `omp:ralph`
+   - **Clear context and implement** — compact the context window first, then start fresh implementation via `omp:ralph` with the saved plan file
+   - **Request changes** — return to step 1 with user feedback
+   - **Reject** — discard the plan entirely
+   If NOT running with `--interactive`, output the final approved plan and stop. Do NOT auto-execute.
+
+8. *(--interactive only)* User chooses via the structured `AskUserQuestion` UI (never ask for approval in plain text).
+
+9. *(--interactive only)* On user approval:
+   - **Approve and implement via team**: Invoke `omp:team` with the approved plan path from `.omp/plans/` as context. Do NOT implement directly.
+   - **Approve and execute via ralph**: Invoke `omp:ralph` with the approved plan path from `.omp/plans/` as context. Do NOT implement directly.
+   - **Clear context and implement**: Compact the context window first, then invoke `omp:ralph` with the approved plan path.
+
+---
+
+## RALPLAN-DR Short Mode Workflow
+
+Used by default in consensus mode. Bounded structure with four mandatory sections:
+
+1. **Principles** (3-5 guiding constraints for this decision)
+2. **Decision Drivers** (top 3 criteria that will determine the best option)
+3. **Viable Options** (>=2) — for each option:
+   - One-sentence description
+   - Pros (2-3 bullets)
+   - Cons (2-3 bullets)
+4. **Invalidation rationale** (if only one viable option remains after analysis)
+
+---
+
+## RALPLAN-DR Deliberate Mode Workflow
+
+Enabled with `--deliberate` or when the request explicitly signals high risk. Adds to the short mode:
+
+- **Pre-mortem**: 3 specific failure scenarios (what could go wrong, how to detect it)
+- **Expanded Test Plan**: unit / integration / e2e / observability layers
+
+---
+
+## Review Mode (`--review`)
+
+1. Read plan file from `.omp/plans/`
+2. Adopt the Critic role to evaluate the plan (or invoke critic agent)
+3. Return verdict: APPROVED, REVISE (with specific feedback), or REJECT (replanning required)
+
+---
+
+## Plan Output Format
+
+Every plan includes:
+- Requirements Summary
+- Acceptance Criteria (testable, 90%+ concrete)
+- Implementation Steps (with file references, 80%+ claims cite file/line)
+- Risks and Mitigations
+- Verification Steps
+- For consensus/ralplan: **RALPLAN-DR summary** (Principles, Decision Drivers, Options)
+- For consensus/ralplan final output: **ADR** (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups)
+- For deliberate consensus mode: **Pre-mortem (3 scenarios)** and **Expanded Test Plan** (unit/integration/e2e/observability)
+
+Plans are saved to `.omp/plans/`. Drafts go to `.omp/drafts/`.
+
+---
+
+## Execution Policy
+
+- Auto-detect interview vs direct mode based on request specificity
+- Ask one question at a time during interviews — never batch multiple questions
+- Gather codebase facts via exploration before asking the user about them
+- Plans must meet quality standards: 80%+ claims cite file/line, 90%+ criteria are testable
+- Consensus mode runs fully automated by default; add `--interactive` to enable user prompts
+- Consensus mode uses RALPLAN-DR short mode by default; switch to deliberate mode with `--deliberate` or when the request signals high risk
+
+---
+
+## Final Checklist
+
+- [ ] Plan has testable acceptance criteria (90%+ concrete)
+- [ ] Plan references specific files/lines where applicable (80%+ claims)
+- [ ] All risks have mitigations identified
+- [ ] No vague terms without metrics ("fast" → "p99 < 200ms")
+- [ ] Plan saved to `.omp/plans/`
+- [ ] In consensus mode: RALPLAN-DR summary includes 3-5 principles, top 3 drivers, and >=2 viable options (or explicit invalidation rationale)
+- [ ] In consensus mode final output: ADR section included (Decision / Drivers / Alternatives considered / Why chosen / Consequences / Follow-ups)
+- [ ] In deliberate consensus mode: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability) included
+- [ ] In consensus mode with `--interactive`: user explicitly approved before any execution; without `--interactive`: plan output only, no auto-execution
+- [ ] **CRITICAL — Consensus mode agent calls MUST be sequential, never parallel.** Always await Architect review before issuing the Critic evaluation.
+
+---
+
+## Escalation and Stop Conditions
+
+- Stop interviewing when requirements are clear enough to plan — do not over-interview
+- In consensus mode, stop after 5 Planner/Architect/Critic iterations and present the best version
+- Consensus mode without `--interactive` outputs the final plan and stops; with `--interactive`, requires explicit user approval before any implementation begins
+- If the user says "just do it" or "skip planning", transition directly to `omp:ralph` for execution — do NOT implement directly in the planning agent
+- Escalate to the user when there are irreconcilable trade-offs that require a business decision

package/skills/omp-reference/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: omp-reference
+description: OMP agent catalog, available tools, team pipeline routing, commit protocol, and skills registry. Auto-loads when delegating to agents, using OMP tools, orchestrating teams, making commits, or invoking skills.
+user-invocable: false
+---
+
+# OMP Reference
+
+Use this built-in reference when you need detailed OMP catalog information that does not need to live in every session context.
+
+## Agent Catalog
+
+Prefix: `omp:`. See `agents/*.md` for full prompts.
+
+| # | ID | Tier | Tools | Role |
+|---|-----|------|-------|------|
+| 1 | `orchestrator` | high | TaskList, SendMessage, Glob, Grep | Top-level coordinator; never writes |
+| 2 | `explorer` | standard | Glob, Grep, Read | Fast codebase surveys, pattern finding |
+| 3 | `planner` | high | Read, Write, TaskCreate | Architecture, sequencing, risk assessment |
+| 4 | `executor` | standard | Read, Write, Edit, Bash | Implementation, refactoring, complex changes |
+| 5 | `verifier` | standard | Bash, Read, Glob | Testing, diagnostics, evidence collection |
+| 6 | `writer` | standard | Read, Write, Glob | Documentation, README, API docs |
+| 7 | `reviewer` | high | Read, Glob, Grep, LSP | Code review, quality gates |
+| 8 | `designer` | high | WebFetch, Figma tools | UI/UX, design system, Figma integration |
+| 9 | `researcher` | standard | WebSearch, WebFetch | External docs, benchmarking, options analysis |
+| 10 | `tester` | standard | Bash, Read, Write | Test writing, execution, CI integration |
+| 11 | `debugger` | high | Bash, Read, LSP, Grep | Error diagnosis, crash analysis |
+| 12 | `architect` | high | Read, Write, Glob | System design, cross-cutting concerns |
+| 13 | `security-reviewer` | high | Grep, Glob, Read | Vulnerability scanning, dependency audit |
+| 14 | `simplifier` | high | Read, Edit, Grep | Code reuse, quality, efficiency improvements |
+| 15 | `test-engineer` | standard | Bash, Read, Write | Test authoring, coverage analysis |
+| 16 | `critic` | high | Read, Grep, Write | Plan review, gap analysis, improvement suggestions |
+| 17 | `tracer` | high | Bash, Read, Grep | Causal investigation, root cause analysis |
+| 18 | `scientist` | high | Read, Write, Bash | Experimental design, hypothesis testing |
+| 19 | `code-reviewer` | standard | Read, Glob, LSP | PR reviews, style enforcement |
+| 20 | `document-specialist` | standard | Read, Write, Grep | Technical docs, API docs, guides |
+| 21 | `qa-tester` | standard | Bash, Read, Write | QA testing, regression verification |
+| 22 | `git-master` | standard | Bash, Read, Grep | Atomic commits, history management |
+| 23 | `analyst` | high | Read, Grep | Requirements analysis, gap identification |
+
+## Model Routing
+
+| Tier | When to use |
+|------|-------------|
+| high (opus) | Security, architecture, complex multi-file refactors, PR reviews, plan challenges |
+| standard (sonnet) | Feature implementation, testing, documentation, debugging |
+| fast (haiku) | Quick lookups, simple edits, documentation updates, glob/grep passes |
+
+## Tools Reference
+
+### Team runtime
+- `TaskCreate`, `TaskList`, `TaskGet`, `TaskUpdate`
+- `SendMessage`
+
+### OMP state
+- `state_read`, `state_write`, `state_clear`, `state_list_active`, `state_get_status`
+
+### Notepad
+- `notepad_read`, `notepad_write_priority`, `notepad_write_working`, `notepad_write_manual`
+
+### Project memory
+- `project_memory_read`, `project_memory_write`, `project_memory_add_note`, `project_memory_add_directive`
+
+### Code intelligence
+- LSP: `lsp_hover`, `lsp_goto_definition`, `lsp_find_references`, `lsp_diagnostics`, and related helpers
+- AST: `ast_grep_search`, `ast_grep_replace`
+- Utility: `python_repl`
+
+## Skills Registry
+
+Invoke built-in workflows via `/omp:<name>`.
+
+### Workflow skills
+- `autopilot` — full autonomous execution from idea to working code
+- `ralph` — persistence loop until completion with verification
+- `ultrawork` — high-throughput parallel execution
+- `team` — coordinated team orchestration
+- `ultraqa` — QA cycle: test, verify, fix, repeat
+- `omp-plan` — planning workflow
+- `pipeline` — sequential pipeline mode with strict phase ordering
+- `swarm` — swarm orchestration with multiple agents and shared state
+- `ecomode` — token budget mode; prioritize completion over expansion
+- `trace` — evidence-driven causal tracing lane
+- `deep-interview` — Socratic ambiguity-gated requirements workflow
+- `graphify` — knowledge graph generation from any input
+- `graphwiki` — LLM wiki with graph-backed knowledge base
+
+### Utility skills
+- `research` / `autoresearch:` — research and investigation workflow
+- `omp-doctor` — diagnose and fix omp installation issues
+- `omp-setup` — install or refresh omp plugin
+- `setup` — install routing entrypoint
+- `mcp-setup` — configure MCP servers
+- `hud` — HUD display options
+- `note` — quick note capture
+- `learner` — extract learned skill from session
+- `spending` — token spend tracking
+- `release` — release assistant
+- `configure-notifications` — notification integrations
+- `wiki` — persistent LLM wiki
+- `psm` — Plugin State Manager control
+
+### Keyword triggers
+- `"autopilot"→autopilot`
+- `"ralph"→ralph`
+- `"ulw"→ultrawork`
+- `"ralplan"→omp-plan`
+- `"deep interview"→deep-interview`
+- `"autoresearch:"→research`
+- `"pipeline"→pipeline`
+- `"swarm"→swarm`
+- `"eco"→ecomode`
+- `"plan"→omp-plan`
+- Team orchestration is explicit via `/team`.
+
+## Team Pipeline
+
+Stages: `team-plan` → `team-prd` → `team-exec` → `team-verify` → `team-fix` (loop).
+
+- Use `team-fix` for bounded remediation loops.
+- Prefer team mode when independent parallel lanes justify the coordination overhead.
+
+## Execution Mode Handling
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| `autopilot` | `/autopilot:` | Autonomous end-to-end execution |
+| `ralph` | `/ralph:` | Self-referential loop with verification |
+| `ultrawork` | `/ulw:` | Parallel execution engine |
+| `team` | `/team:` | Coordinated multi-agent session on shared task list |
+| `ecomode` | `/eco:` | Token budget mode |
+| `swarm` | `/swarm:` | Multiple agents with shared state |
+| `pipeline` | `/pipeline:` | Sequential pipeline with strict phase ordering |
+| `plan` | `/plan:` | Strategic planning via planner agent |
+
+## Commit Protocol
+
+Use git trailers to preserve decision context in every commit message.
+
+### Format
+- Intent line first: why the change was made
+- Optional body with context and rationale
+- Structured trailers when applicable
+
+### Common trailers
+- `Constraint:` active constraint shaping the decision
+- `Rejected:` alternative considered | reason for rejection
+- `Directive:` forward-looking warning or instruction
+- `Confidence:` `high` | `medium` | `low`
+- `Scope-risk:` `narrow` | `moderate` | `broad`
+- `Not-tested:` known verification gap
+
+### Example
+```text
+feat(skills): add research skill to omp plugin
+
+Adds autoresearch workflow with structured output format and
+agent routing to researcher/explorer/architect as appropriate.
+
+Constraint: No model routing parameters allowed in omp skills
+Confidence: high
+Scope-risk: narrow
+```
+
+## State Paths
+
+All OMP runtime state uses `.omp/` prefix:
+- `.omp/state/` — active state files
+- `.omp/state/sessions/{sessionId}/` — per-session state
+- `.omp/notepad.md` — shared notepad
+- `.omp/project-memory.json` — persistent project memory
+- `.omp/plans/` — planning artifacts
+- `.omp/research/` — research outputs
+- `.omp/logs/` — execution logs