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

package/skills/ralplan/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: ralplan
+description: Consensus planning entrypoint that auto-gates vague ralph/autopilot/team requests before execution
+trigger: "/omp:ralplan"
+autoinvoke: false
+---
+
+# Ralplan (Consensus Planning Alias)
+
+Ralplan is a shorthand alias for `/omp:plan --consensus`. It triggers iterative planning with Planner, Architect, and Critic agents until consensus is reached, with **RALPLAN-DR structured deliberation** (short mode by default, deliberate mode for high-risk work).
+
+## Usage
+
+```
+/omp:ralplan "task description"
+```
+
+## Flags
+
+- `--interactive`: Enables user prompts at key decision points (draft review in step 2 and final approval in step 6). Without this flag the workflow runs fully automated — Planner → Architect → Critic loop — and outputs the final plan without asking for confirmation.
+- `--deliberate`: Forces deliberate mode for high-risk work. Adds pre-mortem (3 scenarios) and expanded test planning (unit/integration/e2e/observability). Without this flag, deliberate mode can still auto-enable when the request explicitly signals high risk (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage).
+
+## Usage with interactive mode
+
+```
+/omp:ralplan --interactive "task description"
+```
+
+## Behavior
+
+This skill invokes the Plan skill in consensus mode:
+
+```
+/omp:plan --consensus <arguments>
+```
+
+The consensus workflow:
+1. **Planner** creates initial plan and a compact **RALPLAN-DR summary** before review:
+   - Principles (3-5)
+   - Decision Drivers (top 3)
+   - Viable Options (>=2) with bounded pros/cons
+   - If only one viable option remains, explicit invalidation rationale for alternatives
+   - Deliberate mode only: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability)
+2. **User feedback** *(--interactive only)*: If `--interactive` is set, use `AskUserQuestion` to present the draft plan **plus the Principles / Drivers / Options summary** before review (Proceed to review / Request changes / Skip review). Otherwise, automatically proceed to review.
+3. **Architect** reviews for architectural soundness and must provide the strongest steelman antithesis, at least one real tradeoff tension, and (when possible) synthesis — **await completion before step 4**. In deliberate mode, Architect should explicitly flag principle violations.
+
+   > Adopt the Architect role: "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 completes. Critic must enforce principle-option consistency, fair alternatives, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. In deliberate mode, Critic must reject missing/weak pre-mortem or expanded test plan.
+
+   > Adopt the Critic role: "Evaluate this plan. Verify principle-option consistency, fair alternative exploration, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. Explicitly reject shallow alternatives, driver contradictions, vague risks, or weak verification."
+
+5. **Re-review loop** (max 5 iterations): Any non-`APPROVE` Critic verdict (`ITERATE` or `REJECT`) MUST run the same full closed loop:
+   a. Collect Architect + Critic feedback
+   b. Revise the plan with Planner
+   c. Return to Architect review
+   d. Return to Critic evaluation
+   e. Repeat this loop until Critic returns `APPROVE` or 5 iterations are reached
+   f. If 5 iterations are reached without `APPROVE`, present the best version to the user
+6. On Critic approval *(--interactive only)*: If `--interactive` is set, use `AskUserQuestion` to present the plan with approval options:
+   - **Approve and implement via team** (Recommended) — proceed via `omp:team`
+   - **Approve and execute via ralph** — proceed via `omp:ralph`
+   - **Clear context and implement** — compact context first, then `omp:ralph` with the saved plan file
+   - **Request changes** — return to step 1
+   - **Reject** — discard the plan entirely
+   Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups).
+   Otherwise (non-interactive), output the final plan and stop.
+7. *(--interactive only)* User chooses: Approve (team or ralph), Request changes, or Reject
+8. *(--interactive only)* On approval: invoke `omp:team` for parallel team execution (recommended) or `omp:ralph` for sequential execution — never implement directly
+
+> **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both agent reviews in the same parallel batch. Always await the Architect result before issuing the Critic evaluation.
+
+Follow the omp-plan skill's full documentation for consensus mode details.
+
+---
+
+## Pre-Execution Gate
+
+### Why the Gate Exists
+
+Execution modes (omp:ralph, omp:autopilot, omp:team, omp:ultrawork) spin up heavy multi-agent orchestration. When launched on a vague request like "ralph improve the app", agents have no clear target — they waste cycles on scope discovery that should happen during planning, often delivering partial or misaligned work that requires rework.
+
+The ralplan-first gate intercepts underspecified execution requests and redirects them through the ralplan consensus planning workflow. This ensures:
+- **Explicit scope**: A PRD defines exactly what will be built
+- **Test specification**: Acceptance criteria are testable before code is written
+- **Consensus**: Planner, Architect, and Critic agree on the approach
+- **No wasted execution**: Agents start with a clear, bounded task
+
+### Good vs Bad Prompts
+
+**Passes the gate** (specific enough for direct execution):
+- `ralph fix the null check in src/hooks/bridge.ts:326`
+- `autopilot implement issue #42`
+- `team add validation to function processKeywordDetector`
+- `ralph do:\n1. Add input validation\n2. Write tests\n3. Update README`
+- `ultrawork add the user model in src/models/user.ts`
+
+**Gated — redirected to ralplan** (needs scoping first):
+- `ralph fix this`
+- `autopilot build the app`
+- `team improve performance`
+- `ralph add authentication`
+- `ultrawork make it better`
+
+**Bypass the gate** (when you know what you want):
+- `force: ralph refactor the auth module`
+- `! autopilot optimize everything`
+
+### When the Gate Does NOT Trigger
+
+The gate auto-passes when it detects **any** concrete signal. You do not need all of them — one is enough:
+
+| Signal Type | Example prompt | Why it passes |
+|---|---|---|
+| File path | `ralph fix src/hooks/bridge.ts` | References a specific file |
+| Issue/PR number | `ralph implement #42` | Has a concrete work item |
+| camelCase symbol | `ralph fix processKeywordDetector` | Names a specific function |
+| PascalCase symbol | `ralph update UserModel` | Names a specific class |
+| snake_case symbol | `team fix user_model` | Names a specific identifier |
+| Test runner | `ralph npm test && fix failures` | Has an explicit test target |
+| Numbered steps | `ralph do:\n1. Add X\n2. Test Y` | Structured deliverables |
+| Acceptance criteria | `ralph add login - acceptance criteria: ...` | Explicit success definition |
+| Error reference | `ralph fix TypeError in auth` | Specific error to address |
+| Code block | `ralph add: \`\`\`ts ... \`\`\`` | Concrete code provided |
+| Escape prefix | `force: ralph do it` or `! ralph do it` | Explicit user override |
+
+### End-to-End Flow Example
+
+1. User types: `ralph add user authentication`
+2. Gate detects: execution keyword (`ralph`) + underspecified prompt (no files, functions, or test spec)
+3. Gate redirects to **ralplan** with message explaining the redirect
+4. Ralplan consensus runs:
+   - **Planner** creates initial plan (which files, what auth method, what tests)
+   - **Architect** reviews for soundness
+   - **Critic** validates quality and testability
+5. On consensus approval, user chooses execution path:
+   - **omp:team**: parallel coordinated agents (recommended)
+   - **omp:ralph**: sequential execution with verification
+6. Execution begins with a clear, bounded plan
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Gate fires on a well-specified prompt | Add a file reference, function name, or issue number to anchor the request |
+| Want to bypass the gate | Prefix with `force:` or `!` (e.g., `force: ralph fix it`) |
+| Gate does not fire on a vague prompt | The gate only catches prompts with <=15 effective words and no concrete anchors; add more detail or use `/omp:ralplan` explicitly |
+| Redirected to ralplan but want to skip planning | In the ralplan workflow, say "just do it" or "skip planning" to transition directly to execution |

package/skills/research/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: research
+description: Research and investigation skills. Use for "research this", "investigate", "find out", "autoresearch:", and "deep dive".
+trigger: /omp:research
+autoinvoke: false
+---
+
+## Skill: research
+
+Conduct thorough research and investigation on topics.
+
+## When to Use
+
+- Unknown or unfamiliar topics
+- Need comprehensive understanding
+- Fact-finding missions
+- Competitive analysis
+- Technology evaluation
+
+## Research Process
+
+### 1. Define Scope
+- What do we need to know?
+- How deep to go?
+- What sources to check?
+- Timeline constraints
+
+### 2. Gather Sources
+- Official documentation
+- Expert opinions
+- Community discussions
+- Real-world usage
+
+### 3. Synthesize
+- Extract key information
+- Identify patterns
+- Note contradictions
+- Build understanding
+
+### 4. Analyze
+- Compare options
+- Evaluate trade-offs
+- Assess quality
+- Rate confidence
+
+### 5. Present
+- Clear findings
+- Source attribution
+- Confidence levels
+- Recommendations
+
+## Source Types
+
+### Primary Sources
+- Official documentation
+- Source code
+- API specifications
+- Original research
+
+### Secondary Sources
+- Expert blogs
+- Technical articles
+- Tutorial content
+- Community posts
+
+### Social Proof
+- Usage statistics
+- Adoption rates
+- Community size
+- Support availability
+
+## Research Methods
+
+### Code Archaeology
+- Read source code
+- Trace execution
+- Find patterns
+- Understand internals
+
+### Documentation Mining
+- API docs
+- README files
+- Change logs
+- Migration guides
+
+### Web Research
+- Search engines
+- Specialized forums
+- Stack Overflow
+- GitHub issues
+
+### Expert Consultation
+- Ask practitioners
+- Find case studies
+- Get benchmarks
+- Collect opinions
+
+## Agent Routing
+
+Delegate research tasks to the `researcher` agent (standard tier). For deep code archaeology, use the `explorer` agent. For architecture trade-offs, escalate to the `architect` agent.
+
+State for in-progress research is stored under `.omp/research/`.
+
+## Output Format
+
+```
+## Research: {topic}
+
+### Scope
+**Questions:** {what we need to know}
+**Depth:** {surface/deep/comprehensive}
+**Timeline:** {constraints}
+
+### Sources Consulted
+| Source | Type | Relevance | Confidence |
+|--------|------|-----------|------------|
+| {source} | {type} | High | High |
+
+### Findings
+
+#### Topic 1: {title}
+**Summary:** {what we learned}
+**Source:** {source}
+**Confidence:** {level}
+
+#### Topic 2: {title}
+...
+
+### Analysis
+{comparisons and synthesis}
+
+### Recommendations
+1. **{rec}** — {rationale}
+
+### Confidence
+- **Overall:** {level}
+- **Gaps:** {what we don't know}
+
+### Further Research
+{what would improve confidence}
+```
+
+## Constraints
+
+- Verify information independently
+- Note source quality
+- Be clear about confidence
+- Avoid bias in selection
+- Cite your sources

package/skills/session/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: session
+description: Worktree and tmux session management. Use for "new session", "worktree", "tmux", and "session management".
+trigger: "session:, /session, /omp:session"
+autoinvoke: false
+---
+# Skill: Session
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **ID** | `session` |
+| **Keywords** | `session:`, `/session` |
+| **Tier** | Developer Tool |
+| **Source** | `src/skills/session.mts` |
+
+## Description
+
+Manage development sessions with git worktrees and tmux. Create, attach, detach, list, and end sessions with isolated worktrees for parallel development.
+
+## Differentiation from psm
+
+| Aspect | session | psm |
+|--------|---------|-----|
+| **Scope** | Git worktrees + tmux sessions for development isolation | OMP Plugin State Manager — inspect and update plugin runtime state |
+| **Manages** | Branches, worktrees, tmux windows/panes, session lifecycle | OMP internal state, session metadata, plugin config values |
+| **Use when** | You need to create/switch/end a development context | You need to inspect or modify OMP's running plugin state |
+
+## Interface
+
+```typescript
+interface SkillInput {
+  trigger: string;
+  args: string[];
+}
+
+interface SkillOutput {
+  status: "ok" | "error";
+  message: string;
+}
+
+export async function activate(input: SkillInput): Promise<SkillOutput>
+export function deactivate(): void
+```
+
+## Implementation
+
+Spawns `bin/omp.mjs session [args]`. No persistent resources are maintained.
+
+## When to Use
+
+- Creating new branches
+- Managing multiple tasks
+- Isolating work
+- Session recovery
+- Parallel development
+
+## Session Types
+
+### Development Session
+- Feature work
+- Bug fixes
+- Single focused task
+
+### Exploration Session
+- Research
+- Prototyping
+- Proof of concept
+
+### Review Session
+- Code review
+- Pair programming
+- Pair review
+
+## Worktree Management
+
+### Create Worktree
+```bash
+git worktree add {path} {branch}
+```
+
+### List Worktrees
+```bash
+git worktree list
+```
+
+### Remove Worktree
+```bash
+git worktree remove {path}
+```
+
+### Worktree for Feature
+```
+{project}-feature-{name}
+```
+
+## Tmux Session Management
+
+### Session Structure
+```
+session:{project}
+  └── window:feature-{name}
+      └── pane: editor
+      └── pane: terminal
+      └── pane: tests
+```
+
+### Commands
+```bash
+# Create session
+tmux new-session -s {name} -d
+
+# Attach
+tmux attach -t {name}
+
+# List
+tmux list-sessions
+
+# Kill
+tmux kill-session -t {name}
+```
+
+## Session Workflow
+
+### Start New Feature
+1. Create worktree
+2. Start tmux session
+3. Set up windows/panes
+4. Track session info
+5. Begin work
+
+### Switch Context
+1. Detach current session
+2. Attach target session
+3. Resume work
+
+### End Session
+1. Commit changes
+2. Push if needed
+3. Clean up tmux
+4. Optionally remove worktree
+5. Log session summary
+
+## Commands
+
+### Start Session
+```
+/omp:session start {name}
+```
+
+### Attach Session
+```
+/omp:session attach {name}
+```
+
+### Detach Session
+```
+/omp:session detach
+```
+
+### List Sessions
+```
+/omp:session list
+```
+
+### End Session
+```
+/omp:session end {name}
+```
+
+### Create Worktree
+```
+/omp:session worktree create {branch} {path}
+```
+
+## State
+
+Session state is stored in `.omp/sessions/`. Each session has a JSON record with worktree path, branch, tmux session name, and timestamps.
+
+## Output Format
+
+```
+## Session: {name}
+
+### Type
+{type}
+
+### Worktree
+**Path:** {path}
+**Branch:** {branch}
+**Status:** {clean|dirty}
+
+### Tmux
+**Session:** {tmux-session}
+**Windows:** {n}
+**Created:** {date}
+**Last active:** {date}
+
+### Windows
+| Window | Panes | Current |
+|--------|-------|---------|
+| {name} | {n} | {yes/no} |
+
+### Recent Sessions
+| Name | Type | Last Active | Status |
+|------|------|-------------|--------|
+| {name} | {type} | {date} | {active/ended} |
+
+### Session Notes
+{notes}
+```
+
+## Constraints
+
+- Clean up completed sessions
+- Don't forget worktree paths
+- Keep session names unique
+- Document session purpose
+- Backup before major changes

package/skills/skillify/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: skillify
+description: Turn a repeatable workflow from the current session into a reusable OMP skill draft
+triggers:
+  - /omp:skillify
+---
+
+# Skillify
+
+Use this skill when the current session uncovered a repeatable workflow that should become a reusable OMP skill.
+
+## Goal
+Capture a successful multi-step workflow as a concrete skill draft instead of rediscovering it later.
+
+## Workflow
+1. Identify the repeatable task the session accomplished.
+2. Extract:
+   - inputs
+   - ordered steps
+   - success criteria
+   - constraints / pitfalls
+   - best target location for the skill
+3. Decide whether the workflow belongs as:
+   - a repo built-in skill (in `skills/` directory of oh-my-githubcopilot)
+   - a project learned skill (in `.omp/skills/<skill-name>.md`)
+   - documentation only
+4. When drafting a learned skill file, output a complete skill file that starts with YAML frontmatter.
+   - Never emit plain markdown-only skill files.
+   - Minimum frontmatter:
+     ```yaml
+     ---
+     name: <skill-name>
+     description: <one-line description>
+     triggers:
+       - /omp:<skill-name>
+       - <keyword-trigger>
+     ---
+     ```
+   - Write learned/project skills to:
+     - `.omp/skills/<skill-name>.md`
+   - Write repo built-in skills to:
+     - `skills/<skill-name>/SKILL.md` in the oh-my-githubcopilot repo
+     - `src/skills/<skill-name>.mts` in the oh-my-githubcopilot repo
+5. Draft the rest of the skill file with clear triggers, steps, and success criteria.
+6. Point out anything still too fuzzy to encode safely.
+
+## State Paths
+
+OMP state uses the `.omp/` prefix:
+- `.omp/skills/` — project-local learned skills
+- `.omp/state/` — runtime state
+- `.omp/notepad.md` — working notepad
+
+## Rules
+- Only capture workflows that are actually repeatable.
+- Keep the skill practical and scoped.
+- Prefer explicit success criteria over vague prose.
+- If the workflow still has unresolved branching decisions, note them before drafting.
+- Use `omp:` prefix for all skill references, never `omc:` or `oma:`.
+- Do not output model parameters (haiku/sonnet/opus) in skill files.
+
+## Output
+- Proposed skill name
+- Target location (repo built-in or `.omp/skills/`)
+- Draft workflow structure
+- Open questions, if any