oh-my-githubcopilot 1.5.7 → 1.8.0-alpha.afa30a7

package/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: improve-codebase-architecture
+description: Deep exploration and architectural improvement via organic friction detection
+triggers:
+  - /omp:improve-codebase-architecture
+---
+
+# improve-codebase-architecture
+
+Deep architectural analysis of a codebase with the goal of making the system easier to change. This skill works by following friction, not by applying rigid rules.
+
+Route to **omp architect** for deep analysis and **omp planner** for sequencing implementation. Scope-bound all proposals to the files and modules with confirmed friction — do not propose changes to areas the investigation did not touch.
+
+---
+
+## <Do_Not_Use_When>
+
+- **You need a specific bug fixed** -- Use a targeted debugging skill instead. This skill is about structure and long-term maintainability, not fixing individual bugs.
+- **The codebase is new or small (< 5 files)** -- A codebase this young has not accumulated enough friction to reveal its real problems. Wait until the system has been modified several times.
+- **You need an immediate hotfix deployed** -- Architectural changes require testing and verification. If the fix is urgent, do the hotfix first and schedule the architecture work.
+- **The team is in crisis mode** -- Crisis mode prioritizes shipping over quality. Do architectural work between crises, not during them.
+- **You are asked to "just add a feature"** -- If the task is narrowly scoped, it should be handled directly without this skill. Only engage when there is a sense that the system is fighting back or that something is fundamentally hard.
+
+---
+
+## <Scope_Bounding_Constraints>
+
+These constraints are mandatory. Violating them turns architectural analysis into architecture astronautics.
+
+- **Start from evidence, not intuition** — Only propose changes for modules where friction was directly observed or measured.
+- **Bound proposals to touched modules** — Do not expand scope to modules not investigated. If friction in module A implies a problem in module B, investigate B before proposing changes to it.
+- **RFC before code** — No implementation changes without a filed RFC. The RFC is the deliverable; implementation is a follow-up task.
+- **One RFC per friction point** — Do not bundle unrelated architectural changes into a single proposal.
+- **Stop at 30% threshold** — If the friction points to a problem requiring changes across more than 30% of the codebase, escalate to a dedicated architecture review before making any changes.
+- **Respect ownership boundaries** — Do not propose changes to modules owned by other teams without their involvement.
+
+---
+
+## <Tool_Usage>
+
+### Entry Points
+
+| Trigger | When to Use |
+|---|---|
+| `/omp:improve-codebase-architecture` | General request to analyze and improve a codebase's structure |
+
+### Agent Routing
+
+- **omp architect** — Route for deep analysis of module interfaces, dependency graphs, and coupling patterns. Use for parallel interface design.
+- **omp planner** — Route for sequencing the implementation of approved RFCs into a safe, incremental plan.
+- **omp explore** — Map the file structure and module boundaries before analysis begins.
+
+### Sub-Agent Orchestration (Parallel Interface Design)
+
+Spawn multiple sub-agents simultaneously, each with a different constraint perspective. This is the core technique for designing better module interfaces.
+
+```
+Agent A: Minimize the interface surface
+  - Goal: Reduce parameters, simplify signatures
+  - Ask: "What is the smallest interface that still fulfills the contract?"
+
+Agent B: Maximize flexibility / ease of change
+  - Goal: Identify where changes cascade, minimize blast radius
+  - Ask: "What would I need to change to swap this dependency?"
+
+Agent C: Optimize for the common case
+  - Goal: Make the happy path effortless
+  - Ask: "What does this code do most of the time, and how do we make that the default?"
+```
+
+**Workflow:**
+1. Run all agents in parallel.
+2. Collect proposals from each.
+3. Compare interface shapes, tradeoffs, and constraints.
+4. Synthesize the best aspects of each design.
+5. Document the chosen approach with rationale.
+
+### Codebase Investigation Tools
+
+- **omp explore agent** -- Map the file structure and module boundaries.
+- **ast_grep_search** -- Find structural patterns (e.g., functions with many parameters, large classes).
+- **Grep** -- Track import/export chains to understand coupling.
+- **Read** -- Deep-dive into specific modules identified as friction points.
+- **lsp_workspace_symbols** -- Understand public API surfaces of modules.
+
+### Output Format
+
+After analysis, produce a GitHub Issue RFC using this template:
+
+```markdown
+## Problem: [what's wrong]
+## Proposal: [what to change]
+## Alternatives Considered: [other options]
+## Consequences: [what happens if we do this]
+```
+
+---
+
+## <Why_This_Exists>
+
+Most codebases degrade silently. Features are added, conditions accumulate, abstractions pile on top of abstractions. Eventually, every team reaches a point where changing one thing breaks three others -- and nobody knows why.
+
+This skill exists because **friction is a signal, not a noise**. When a developer hits resistance while trying to make a change, that resistance reveals the architecture's true shape. The goal is to listen to that friction, trace it to its root cause, and propose changes that make the system easier to work with -- not by applying external rules, but by following what the code is already telling you.
+
+The core ideas come from John Ousterhout's *A Philosophy of Software Design*:
+- **Deep modules** hide complexity behind small, focused interfaces.
+- **Shallow modules** expose as much complexity as they contain -- making them cognitive burdens.
+- **Organic exploration** means trusting the difficulty you encounter, rather than applying a checklist.
+
+This skill is also a direct response to the failure mode of "architecture astronauts" -- people who design grand systems upfront without reacting to what the code actually needs. The approach here is the opposite: start from real friction and let the architecture emerge from the evidence.
+
+---
+
+## <Examples>
+
+### Example 1: Detecting a Shallow Module
+
+A team has a `UserManager` class with 47 methods. It is imported everywhere. The LSP shows it in 200+ files.
+
+**What the friction tells you:**
+- Changing any behavior in `UserManager` risks breaking many unrelated callers.
+- The class has become a "god class" -- it knows too much and is depended on by too much.
+
+**Organic response:**
+- Identify cohesive subgroups of functionality within `UserManager`.
+- Extract those subgroups into focused modules with narrow interfaces.
+- Keep `UserManager` as a facade with a small, stable interface.
+
+**Proposal (RFC snippet):**
+```markdown
+## Problem: UserManager is a shallow module with 47 methods imported by 200+ files.
+  Any change to it risks cascading failures across the codebase.
+
+## Proposal: Extract three cohesive sub-modules (AuthManager, ProfileManager, PreferencesManager)
+  and replace UserManager's responsibilities with delegation to these new modules.
+  Keep UserManager as a thin facade with no more than 5 public methods.
+
+## Alternatives Considered:
+  - Keep UserManager and add deprecation warnings (does not reduce coupling)
+  - Create a single new class replacing UserManager (too large a change, hard to review)
+```
+
+### Example 2: Following Friction to Find a Design Problem
+
+A developer tries to add a new log level and discovers that the logging system has 6 different configuration locations, each with different precedence rules.
+
+**What the friction tells you:**
+- Configuration is not centralized -- it has spread across layers.
+- The "easy" thing (add a log level) is hard because the concern is not owned in one place.
+
+**Organic response:**
+- Map all 6 configuration sites.
+- Identify which are dead, which are active, and which should be canonical.
+- Propose a single configuration boundary and migrate consumers to it.
+
+### Example 3: Parallel Interface Design
+
+A team needs to redesign the `CacheManager` interface. Instead of one agent designing it in isolation, three agents work simultaneously:
+
+- **Agent A (minimize surface):** Proposes a single `get(key)` / `set(key, value)` interface, with TTL as a property set once at initialization.
+- **Agent B (maximize flexibility):** Proposes a strategy pattern with swappable `CacheStrategy` objects and a `CacheBackend` interface for swapping implementations.
+- **Agent C (optimize common case):** Proposes an annotation-based approach where developers mark methods with `@Cacheable` and the system handles everything transparently.
+
+**Synthesis:** Agent A's surface is too small (loses TTL control at runtime). Agent C is too magical (hard to debug). Agent B's strategy pattern is the best foundation, but the interface is tightened to 4 methods instead of 8.
+
+### Example 4: Four Dependency Categories in Practice
+
+When evaluating how to test a module, classify its dependencies:
+
+| Module | Dependency | Category | Testing Strategy |
+|---|---|---|---|
+| `UserService` | `UserRepository` (local SQLite) | Local-substitutable | Inject a mock repository |
+| `UserService` | `EmailClient` (external SendGrid) | True external | Use a test SMTP server or mock |
+| `AuthService` | `SessionStore` (in-process Map) | In-process | Test directly with real instance |
+| `PaymentService` | `PaymentGateway` (remote, owned adapter) | Remote-but-owned | Use a test payment gateway adapter |
+
+---
+
+## <Escalation_And_Stop_Conditions>
+
+### Escalate when:
+
+- **Architectural problem is systemic** -- If the friction you found points to a problem that would require changes across more than 30% of the codebase, escalate to a dedicated architecture review before making changes.
+- **Cross-team ownership** -- If the modules involved are owned by different teams, the RFC must involve those teams. Do not propose changes that affect code you do not own.
+- **Performance is a concern** -- Architectural improvements sometimes introduce indirection that affects latency. If performance constraints exist, document them in the RFC and involve a performance-conscious reviewer.
+- **Database schema changes** -- Schema changes have high migration costs. Escalate schema changes to a senior architect or DBA review.
+
+### Stop conditions (do not proceed):
+
+- **The codebase does not have tests** -- Architectural changes without test coverage are uncontrolled experiments. Stop and escalate to establishing test infrastructure first.
+- **The team disagrees on the direction** -- If stakeholders have conflicting priorities or views on the proposed changes, stop and reach consensus through structured discussion before proceeding.
+- **Cost of change exceeds benefit** -- If the estimated cost of the refactor is greater than the estimated benefit (measured in future developer-hours saved), stop and document the tradeoff.
+- **A better design cannot be agreed upon** -- If three parallel agents produce incompatible designs and no synthesis is possible, stop and escalate with all three proposals documented.
+
+### Normal completion:
+
+- A GitHub Issue RFC is filed with the problem analysis, proposal, alternatives, and consequences.
+- If implementation is in scope, omp planner creates a follow-up task for the actual refactor.
+- The notepad is updated with key learnings from the exploration.
+
+---
+
+## <Final_Checklist>
+
+- [ ] **Friction-first**: Did you start from a real friction point (hard-to-change code, cascading breakage, unexpected coupling) rather than from a heuristic checklist?
+- [ ] **Shallow module detection**: Did you identify modules whose interface complexity approaches their implementation complexity?
+- [ ] **Sub-agent parallel design**: If proposing a new module interface, did you run parallel agents with different constraints? Are all three constraint perspectives represented in the proposal?
+- [ ] **Deep module validation**: Does the proposed design for each new module have a small, focused interface hiding a rich implementation?
+- [ ] **Dependency categorization**: Did you classify each dependency into one of the four categories (in-process, local-substitutable, remote-but-owned, true external)? Is the testing strategy appropriate for each category?
+- [ ] **RFC completeness**: Does the GitHub Issue RFC include all four sections (Problem, Proposal, Alternatives Considered, Consequences)?
+- [ ] **No over-engineering**: Did you avoid introducing abstractions for single-use logic? Is the change proportional to the friction it resolves?
+- [ ] **Scope bounded**: Are all proposals limited to modules where friction was directly observed?
+- [ ] **Consensus tracked**: If the changes affect multiple teams, is there evidence of review or agreement from each team?
+- [ ] **Notepad updated**: Are key learnings and architectural decisions appended to the notepad for future reference?

package/skills/interactive-menu/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: interactive-menu
+description: Pattern for presenting numbered choices to the user in OMP's conversational TUI
+invocation: none (referenced by commands that need selection)
+autoinvoke: false
+---
+# Skill: Interactive Menu
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **ID** | `interactive-menu` |
+| **Keywords** | `interactive-menu:`, `/interactive-menu` |
+| **Tier** | UI Pattern |
+| **Source** | `src/skills/interactive-menu.mts` |
+
+## Description
+
+OMP does not have a native menu widget. Use this conversational pattern when a command needs user selection.
+
+## 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 interactive-menu [args]`. No persistent resources are maintained.
+
+## Format
+
+```
+{Title}
+
+{Optional context line}
+
+  1. {Option A}  -- {description}
+  2. {Option B}  -- {description}
+  3. {Option C}  -- {description}
+  4. Type something else
+
+Your choice:
+```
+
+## Rules
+
+1. Present options as a numbered list. Keep descriptions to one line each.
+2. Always include a "Type something else" option as the last item.
+3. Wait for user input. Do not assume a choice.
+4. Accept the number ("1") or the option name ("graphwiki") as valid input.
+5. If the user types something not in the list (via the last option), validate it against allowed values. If invalid, re-present the menu with an error message.
+6. After selection, confirm what was set: "Set graph.provider to graphwiki (local)."
+7. Maximum 6 options. If more choices exist, group them or paginate.
+8. Do not use emoji, decorative borders, or ASCII art. Clean text only.
+
+## Example: Graph Provider
+
+```
+Graph Provider
+
+Current: graphwiki (from local config)
+
+  1. graphwiki   -- TypeScript knowledge graph with wiki compilation
+  2. graphify    -- Python knowledge graph with community detection
+  3. none        -- Disable graph context
+  4. Type something else
+
+Your choice:
+```
+
+User types: 2
+
+Agent responds: "Set graph.provider to graphify (local). Install graphify if not already: pip install graphify"
+
+## Example: Orchestration Mode
+
+```
+Orchestration Mode
+
+Current: ralph
+
+  1. ralph       -- Persistence loop with architect verification
+  2. autopilot   -- Full autonomous pipeline
+  3. ultrawork   -- Parallel execution
+  4. ultraqa     -- QA cycling
+  5. Type something else
+
+Your choice:
+```

package/skills/interview/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: interview
+description: Socratic interview and ambiguity scoring. Use for "interview", "question", "socratic", and "ambiguity".
+trigger: "interview:, /interview, /omp:interview"
+autoinvoke: false
+---
+# Skill: Interview
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **ID** | `interview` |
+| **Keywords** | `interview:`, `/interview` |
+| **Tier** | Planning Tool |
+| **Source** | `src/skills/interview.mts` |
+
+## Description
+
+Conduct Socratic interviews to expose ambiguity and deepen understanding. Scores ambiguity across categories (Terminology, Scope, Process, Outcome) and surfaces remaining questions and next steps.
+
+## Differentiation from deep-interview
+
+| Aspect | interview | deep-interview |
+|--------|-----------|----------------|
+| **Purpose** | General Socratic inquiry — expose ambiguity in any problem or plan | Pre-execution gating — mathematical ambiguity scoring before autonomous work begins |
+| **Gating** | Does not block execution; produces a report | Gates entry into ralph/autopilot until score falls below threshold |
+| **Trigger style** | On-demand, conversational | Pipeline step, usually auto-invoked before execution modes |
+| **Output** | Structured interview report with ambiguity table | Pass/fail ambiguity gate + resolved requirements doc |
+
+Use `interview` when you want a Socratic exploration of a topic. Use `deep-interview` when you need to gate autonomous execution until ambiguity is resolved.
+
+## 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 interview [args]`. No persistent resources are maintained.
+
+## When to Use
+
+- Unclear requirements
+- Complex problems
+- Before major decisions
+- Identifying blind spots
+- Challenge assumptions
+
+## Interview Process
+
+### 1. Establish Context
+- What is the problem?
+- What do we think we know?
+- What's the goal?
+
+### 2. Probe Assumptions
+- What are we assuming?
+- Why are we assuming this?
+- What if we're wrong?
+
+### 3. Explore Evidence
+- What evidence do we have?
+- How strong is it?
+- What's missing?
+
+### 4. Test Alternatives
+- What else could be true?
+- What other explanations exist?
+- What would disprove this?
+
+### 5. Assess Uncertainty
+- What don't we know?
+- How confident are we?
+- What would change our view?
+
+## Question Types
+
+### Clarifying
+- "What do you mean by X?"
+- "Can you give an example?"
+- "How is this different from Y?"
+
+### Assumption Probing
+- "What are you assuming here?"
+- "Why assume X rather than Y?"
+- "What if that assumption is wrong?"
+
+### Evidence Evaluation
+- "What evidence supports this?"
+- "How would we know if this is wrong?"
+- "What's the strongest evidence?"
+
+### Alternative Exploration
+- "What other approaches exist?"
+- "What would happen if we did X instead?"
+- "What's the best alternative and why?"
+
+### Implications Testing
+- "If this is true, what else must be true?"
+- "What would follow from this?"
+- "What are the consequences?"
+
+## Ambiguity Scoring
+
+Rate ambiguity on scale:
+
+| Score | Level | Description |
+|-------|-------|-------------|
+| 1 | Clear | No ambiguity, single interpretation |
+| 2 | Minor | Slight ambiguity, mostly clear |
+| 3 | Moderate | Notable ambiguity, needs clarification |
+| 4 | Significant | Major ambiguity, multiple interpretations |
+| 5 | Severe | Fundamental ambiguity, needs resolution |
+
+### Ambiguity Categories
+
+**Terminology**
+- Undefined terms
+- Multiple meanings
+- Jargon without explanation
+
+**Scope**
+- Boundary unclear
+- Inclusion/exclusion fuzzy
+- Overlap undefined
+
+**Process**
+- Steps missing
+- Order ambiguous
+- Responsibilities unclear
+
+**Outcome**
+- Success undefined
+- Metrics absent
+- Trade-offs unstated
+
+## Output Format
+
+```
+## Interview: {topic}
+
+### Opening Context
+{what we discussed}
+
+### Key Exchanges
+
+#### Exchange 1: {subject}
+**Q:** {question}
+**A:** {answer}
+**Ambiguity:** {score} - {notes}
+
+#### Exchange 2: {subject}
+...
+
+### Assumptions Exposed
+- **{assumption}** — {questioning}
+- **{assumption}** — {questioning}
+
+### Evidence Gaps
+- **{gap}** — {what's missing}
+- **{gap}** — {what's missing}
+
+### Alternative Views
+- **{alternative}** — {description}
+- **{alternative}** — {description}
+
+### Ambiguity Summary
+| Category | Score | Key Issues |
+|----------|-------|------------|
+| Terminology | {n} | {issues} |
+| Scope | {n} | {issues} |
+| Process | {n} | {issues} |
+| Outcome | {n} | {issues} |
+| **Overall** | **{n}** | **{summary}** |
+
+### Remaining Questions
+1. {question}
+2. {question}
+
+### Next Steps
+{how to resolve remaining ambiguity}
+```
+
+## Constraints
+
+- Ask genuine questions
+- Follow the thread
+- Don't lead the witness
+- Document all ambiguity
+- Don't resolve prematurely

package/skills/notifications/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: notifications
+description: Send and manage runtime notifications across Telegram, Discord, Slack, and Email channels
+trigger: "notifications:, /notifications, /omp:notifications"
+autoinvoke: false
+---
+# Skill: Notifications
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **ID** | `notifications` |
+| **Keywords** | `notifications:`, `/notifications` |
+| **Tier** | Developer Tool |
+| **Source** | `src/skills/notifications.mts` |
+
+## Description
+
+Send and manage notification delivery across multiple channels (Telegram, Discord, Slack, Email). Handles immediate alerts, digests, and escalation patterns at runtime.
+
+## Differentiation from configure-notifications
+
+| Aspect | notifications | configure-notifications |
+|--------|---------------|-------------------------|
+| **Purpose** | Runtime notification delivery, channel management, testing, escalation | One-time setup of notification credentials and integrations |
+| **Scope** | Send alerts, manage preferences, configure digest schedules, escalate | Configure webhook URLs and tokens |
+| **Use when** | You need to act on notifications or manage delivery rules | You are setting up a new integration for the first time |
+
+## 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 notifications [args]`. No persistent resources are maintained.
+
+## When to Use
+
+- Setting up alerts
+- Configuring notification channels
+- Managing notification preferences
+- Troubleshooting missing alerts
+
+## Notification Channels
+
+### Telegram
+- Fast delivery
+- Supports markdown
+- Group chats
+- Bot integration
+
+### Discord
+- Webhook-based
+- Rich embeds
+- Channels and roles
+- High volume
+
+### Slack
+- Channel-based
+- App integration
+- Threaded
+- Enterprise friendly
+
+### Email
+- Universal
+- SMTP based
+- Digest options
+- Fallback option
+
+## Configuration
+
+### Telegram Setup
+```yaml
+telegram:
+  bot_token: {token}
+  chat_id: {chat_id}
+  parse_mode: markdown
+```
+
+### Discord Setup
+```yaml
+discord:
+  webhook_url: {url}
+  username: {bot_name}
+  embed_color: {hex}
+```
+
+### Slack Setup
+```yaml
+slack:
+  webhook_url: {url}
+  channel: {channel}
+  username: {bot_name}
+```
+
+## Notification Types
+
+### Immediate
+- Errors and failures
+- Critical alerts
+- Completion notifications
+- Mentions and replies
+
+### Digest
+- Summary of activity
+- Batch reports
+- Periodic updates
+- Non-urgent changes
+
+### Escalation
+- Alert escalation
+- No response follow-up
+- Priority boosts
+- Emergency alerts
+
+## Commands
+
+### Configure Channel
+```
+/omp:notifications configure {channel}
+```
+
+### Test Notification
+```
+/omp:notifications test {channel}
+```
+
+### List Channels
+```
+/omp:notifications list
+```
+
+### Set Preferences
+```
+/omp:notifications set {type} {channel}
+```
+
+## Output Format
+
+```
+## Notifications: {project}
+
+### Configured Channels
+| Channel | Status | Last Test |
+|---------|--------|-----------|
+| Telegram | OK | {date} |
+| Discord | OK | {date} |
+
+### Notification Preferences
+
+#### Immediate
+| Event | Channel | Enabled |
+|-------|---------|---------|
+| Error | Telegram | yes |
+| Complete | Discord | yes |
+
+#### Digest
+| Schedule | Channel | Enabled |
+|---------|---------|---------|
+| Daily | Email | yes |
+
+### Recent Notifications
+- **{time}** — {event} -> {channel}
+
+### Configuration Files
+- `.omp/notifications/config.yaml`
+- `.omp/notifications/templates/`
+```
+
+## Constraints
+
+- Test after configuration
+- Don't over-notify
+- Respect quiet hours
+- Secure sensitive tokens
+- Provide unsubscribe