claudecode-omc 4.3.5 → 4.4.0

package/skills/ai-commenting/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: ai-commenting
+description: AI-native code annotation protocol that encodes intent, risk, dependencies, constraints, and test expectations in machine-parseable comments.
+---
+
+# AI Commenting Skill
+
+Create and maintain AI-native annotations so coding agents can understand intent, risk, and constraints quickly and safely.
+
+## When to Use
+
+Use this skill when:
+- introducing a new module with high coupling
+- touching auth/payment/state consistency paths
+- preparing codebase context for multi-agent implementation
+- reducing repeated prompt context for long tasks
+
+## Annotation Format
+
+Canonical format:
+
+```text
+/*@ai:key=value|key=value|key=value*/
+```
+
+Rules:
+- ASCII keys/values only
+- `|` as field separator
+- no spaces around `=`
+- one annotation per scope (file or risky block)
+
+## Field Schema
+
+Core file-level fields:
+- `risk=1-5`
+- `core=<domain>`
+- `deps=<A,B,C>`
+- `intent=<why>`
+- `test=<unit|integration|e2e|contract>`
+
+Extended fields:
+- `chain=<A->B->C>`
+- `auth=<none|required|strict>`
+- `security=<none|pii|payment|secret>`
+- `invariant=<must_hold>`
+- `sidefx=<db,cache,queue,event>`
+- `perf=<budget>`
+- `rollback=<strategy>`
+
+## Risk Rubric
+
+- `risk=1`: isolated local logic
+- `risk=2`: low coupling, easy rollback
+- `risk=3`: moderate coupling or external dependency
+- `risk=4`: critical cross-module path
+- `risk=5`: security/payment/core-state high blast radius
+
+Escalate by +1 if auth/session/payment/PII/secrets are touched.
+
+## Placement Strategy
+
+1. File header annotation for critical modules
+2. Block-level annotation only for risky functions
+
+Keep annotations high-signal. Avoid tagging trivial code.
+
+## Example
+
+```typescript
+/*@ai:risk=5|core=UserCRUD|intent=protect_user_consistency|deps=UserModel,AuthService,AuditService*/
+/*@ai:chain=Auth->User->Permission->Audit|auth=strict|sidefx=db,event|test=integration|rollback=feature_flag*/
+class UserManager {
+  /*@ai:risk=4|invariant=user_id_unique|security=pii|perf=p95<200ms*/
+  async deleteUser(userId: string) {
+    // ...
+  }
+}
+```
+
+## Workflow
+
+1. Discover high-risk boundaries
+2. Add file-level core tags
+3. Add targeted block-level tags
+4. Validate syntax and consistency
+5. Ensure `risk>=4` has explicit `test` and `rollback`
+
+## Quality Gates
+
+- all `risk>=4` files include file-level annotation
+- `security!=none` implies `auth!=none`
+- no contradictory tags per scope
+- prefer 1 annotation per 60-120 LOC
+
+## Parsing Helpers
+
+```javascript
+const aiTagPattern = /\/\*@ai:([^*]+)\*\//g;
+const fieldPattern = /(\w+)=([^|*]+)/g;
+```
+
+## Output
+
+Return a concise markdown report:
+- Result summary
+- Files changed
+- Validation evidence
+- Risks / next actions

package/skills/skill-development/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: skill-development
+description: This skill should be used when the user wants to "create a skill", "write a new skill", "add a skill", or "improve an existing skill". Covers structure, description quality, progressive disclosure, and the quality pipeline.
+---
+
+# Writing Skills for Claude Code (OMC)
+
+Guide for creating effective skills in the oh-my-claudecode (OMC) environment. Skills are modular `.claude/skills/<name>/SKILL.md` files that teach Claude specialized workflows, domain knowledge, and tool integrations.
+
+## Agent Workflow
+
+Follow this **Hybrid Workflow** for every skill creation or improvement task:
+
+1. **Requirement Gathering (Soft)**: Before writing anything, ask for **concrete trigger examples**.
+   - *Agent Question*: "Give me 3 exact phrases a user would say to trigger this skill."
+   - These become the quoted trigger phrases in the description.
+2. **Structural Planning (Hard)**: Decide the file structure based on complexity.
+   - Simple knowledge or utility → just `SKILL.md`
+   - Workflow with detailed reference content → `SKILL.md` + `references/`
+   - Script-heavy → add `scripts/`
+3. **Implementation**: Write with correct YAML frontmatter and consistent body format.
+
+## Integration with the OMC Skill Pipeline
+
+This skill is the **entry point**. After creating or editing a skill, run:
+
+1. `skill-development` — create/author the skill (this skill)
+2. `skill-quality-analyzer` — score it across 6 dimensions (target ≥80)
+3. `skill-debugger` — check if description triggers correctly
+4. `skill-tester` — verify behavioral correctness
+
+## Anatomy of an OMC Skill
+
+```
+skill-name/               ← folder name = YAML name (kebab-case)
+├── SKILL.md              ← required; ≤200 lines ideally
+└── references/           ← optional; detailed content loaded on demand
+    ├── patterns.md
+    └── examples.md
+```
+
+### SKILL.md (required)
+
+**Frontmatter**: The `description` field is what Claude sees in the system-reminder when deciding whether to invoke the skill. Make it specific.
+
+Two formats for the description:
+
+```yaml
+# For skills intended for auto-discovery (user/project skills):
+description: "This skill should be used when the user asks to 'trigger phrase 1', 'trigger phrase 2', 'trigger phrase 3'."
+
+# For OMC core workflow skills (already triggered by CLAUDE.md keywords):
+description: "Concise capability summary. Triggered by: 'keyword1', 'keyword2'."
+```
+
+**Body formats** — choose one and be consistent:
+
+- **XML tags** (for workflow/process skills): `<Purpose>`, `<Use_When>`, `<Do_Not_Use_When>`, `<Steps>`, `<Examples>`, `<Final_Checklist>`, `<Advanced>`
+- **Markdown headers** (for utility/reference skills): `## When to Use`, `## Workflow`, `## Examples`
+
+See `references/format-guide.md` for complete tag-by-tag reference.
+
+### references/ (optional)
+
+Load only when Claude determines it's needed during execution.
+
+- **When to use**: SKILL.md body would exceed ~200 lines without it
+- **Move here**: detailed patterns, API references, advanced techniques, long examples
+- **Keep in SKILL.md**: core workflow, quick reference tables, pointers to references/
+
+### Progressive Disclosure
+
+Skills use a three-level loading system:
+
+| Level | What loads | When |
+|-------|-----------|------|
+| Metadata | `name` + `description` | Always |
+| Body | SKILL.md content | When skill triggers |
+| References | `references/*.md` | When Claude reads them |
+
+## Skill Creation Process
+
+### Step 1: Understand the Use Case
+
+Skip only when usage patterns are completely clear.
+
+Ask for concrete examples:
+- "What would a user say to trigger this skill?"
+- "What's the main output or artifact it produces?"
+- "What should it NOT do?" (defines `<Do_Not_Use_When>`)
+
+Aim for 3 trigger phrases before writing any content.
+
+### Step 2: Plan the Structure
+
+Analyze each concrete example:
+1. What would Claude need to execute this from scratch?
+2. What reference material would help if repeated?
+3. Any scripts or assets needed?
+
+### Step 3: Write the Description
+
+**Hard rule**: The description must contain quoted trigger phrases.
+
+```yaml
+# ✅ Good — specific trigger phrases, third person, summary at end
+description: "This skill should be used when the user asks to 'create a validation rule', 'define trigger conditions', or 'validate tool instructions'. Provides comprehensive guidance with clear trigger phases and quality gates."
+
+# ❌ Bad — vague, no trigger phrases, wrong person
+description: Use this skill when working with hooks.
+description: Provides hook guidance.
+```
+
+### Step 4: Write the Body
+
+**Style**: Imperative/infinitive form, not second person.
+
+```
+✅ "Start by reading the configuration file."
+✅ "Validate the input before processing."
+❌ "You should start by reading the configuration file."
+❌ "You need to validate the input."
+```
+
+**Size target**: ≤200 lines for SKILL.md body. Move detail to `references/` if exceeded.
+
+### Step 5: Validate
+
+Run `skill-quality-analyzer` on the new skill. Target score ≥80.
+
+Check the description manually:
+```bash
+grep "^description:" skills/<name>/SKILL.md
+# Verify it contains quoted trigger phrases
+```
+
+Check line count:
+```bash
+wc -l skills/<name>/SKILL.md
+# Target: ≤200
+```
+
+### Step 6: Iterate
+
+After using the skill on real tasks:
+- Notice struggles or missed triggers
+- Strengthen description with additional trigger phrases
+- Move long sections to `references/` if context bloat is observed
+- Add missing edge cases to `<Do_Not_Use_When>`
+
+## Validation Checklist
+
+**Frontmatter:**
+- [ ] `name` matches folder name exactly (kebab-case)
+- [ ] `description` contains at least 2 quoted trigger phrases
+- [ ] Description is ≤200 characters
+
+**Content:**
+- [ ] Body uses imperative form (not "you should")
+- [ ] SKILL.md ≤200 lines (move detail to references/ if not)
+- [ ] Referenced files in `references/` actually exist
+- [ ] No platform-specific branding (e.g., "Codex CLI")
+
+**Quality:**
+- [ ] `skill-quality-analyzer` score ≥80
+- [ ] `<Do_Not_Use_When>` or equivalent section present (prevents misuse)
+- [ ] At least 3 usage examples (Good + Bad preferred)
+
+## Common Mistakes
+
+### Mistake 1: Weak trigger description
+
+```yaml
+# ❌ Bad
+description: Provides guidance for working with hooks.
+
+# ✅ Good
+description: "This skill should be used when the user asks to 'create a hook', 'add a pre-tool hook', or 'set up hook validation'. Full hook development guide with examples and scripts."
+```
+
+### Mistake 2: Everything in SKILL.md
+
+```
+# ❌ Bad
+skill-name/
+└── SKILL.md  (900 lines — everything in one file)
+
+# ✅ Good
+skill-name/
+├── SKILL.md         (180 lines — core workflow)
+└── references/
+    ├── patterns.md  (250 lines)
+    └── advanced.md  (300 lines)
+```
+
+### Mistake 3: Second-person writing
+
+```
+# ❌ Bad
+You should start by reading the config file.
+You need to validate the input.
+
+# ✅ Good
+Start by reading the config file.
+Validate the input before processing.
+```
+
+## Additional Resources
+
+- `references/format-guide.md` — complete XML tag reference, style rules, size targets
+- `references/description-patterns.md` — Good/Bad description catalog for all OMC skill categories
+
+## Related Skills
+
+- `skill-quality-analyzer` — score a skill across 6 quality dimensions
+- `skill-debugger` — debug why a skill isn't triggering
+- `skill-tester` — verify a skill triggers and behaves correctly
+- `skill` — manage installed skills (list, add, remove, sync)

package/skills/skill-development/references/description-patterns.md

@@ -0,0 +1,160 @@
+# Description Patterns — Good/Bad Catalog
+
+Reference for writing the `description` field in SKILL.md frontmatter.
+
+Claude sees this description in the system-reminder when deciding whether to invoke a skill.
+Format: `"This skill should be used when the user asks to '[trigger]', '[trigger]'. [Summary]."`
+
+---
+
+## The Format Standard
+
+```yaml
+# Auto-discovery skills (user/project skills):
+description: "This skill should be used when the user asks to '[trigger 1]', '[trigger 2]', or '[trigger 3]'. [One-sentence summary]."
+
+# OMC core workflow skills (also triggered by CLAUDE.md keywords):
+description: "[Capability summary]. Triggered by: '[kw1]', '[kw2]'."
+```
+
+**Required**: At least 2 quoted trigger phrases using `'single quotes'`.
+
+---
+
+## Anti-Pattern Catalog
+
+### Anti-pattern 1: Tagline instead of trigger
+
+```yaml
+# ❌ Tagline — describes what it IS, not WHEN to use it
+description: Full autonomous execution from idea to working code
+description: Parallel execution engine for high-throughput task completion
+description: Self-referential loop until task completion with architect verification
+
+# ✅ Trigger-forward
+description: "Use when user wants full-auto development ('build me', 'autopilot', 'I want a'). End-to-end pipeline from idea to verified code."
+description: "Use when running multiple independent tasks in parallel ('ulw', 'ultrawork', 'run in parallel'). Tiered agent routing with haiku/sonnet/opus."
+description: "Use when task must complete guaranteed ('ralph', 'don't stop', 'must complete'). Persistence loop with architect sign-off."
+```
+
+### Anti-pattern 2: Wrong platform branding
+
+```yaml
+# ❌ Platform-specific (Codex, not Claude Code)
+description: Analyzes Codex skill quality with 6-dimension scoring system
+description: Tests Codex skill functionality with TDD approach
+
+# ✅ Platform-neutral
+description: "This skill should be used when the user asks to 'analyze skill quality', 'score skill', or 'skill quality report'. 6-dimension scoring for Claude Code skills."
+description: "This skill should be used when the user asks to 'test skill', 'verify skill', or 'skill test'. Trigger tests and behavioral validation for Claude Code skills."
+```
+
+### Anti-pattern 3: Second person in description
+
+```yaml
+# ❌ Second person
+description: Use this skill when you want to plan before coding
+description: Load this skill when user asks for parallel execution
+
+# ✅ Third person or neutral
+description: "This skill should be used when the user asks to 'plan this', 'plan the', or 'let's plan'. Interview, direct, consensus, and review modes."
+```
+
+### Anti-pattern 4: No trigger phrases (vague)
+
+```yaml
+# ❌ Vague — no specific triggers
+description: Helps with various tasks
+description: Provides guidance for working with hooks
+description: Deep analysis and investigation
+
+# ✅ Specific
+description: "This skill should be used when the user asks to 'create a hook', 'add validation hook', or 'configure hook behavior'. Full hook development with examples."
+description: "Use when debugging or investigating failures ('analyze', 'debug', 'investigate', 'why is this failing'). Delegates to debugger agent for root-cause analysis."
+```
+
+---
+
+## Pattern Catalog by Category
+
+### Workflow / Orchestration Skills
+
+These are invoked by keyword — triggers must match CLAUDE.md `<skills>` section keywords.
+
+```yaml
+# autopilot
+description: "Use when user wants full-auto development ('build me', 'autopilot', 'I want a', 'create me'). End-to-end: spec→plan→code→QA→validation with no manual intervention."
+
+# ralph
+description: "Use when task must complete guaranteed ('ralph', 'don't stop', 'must complete', 'finish this'). Persistence loop with ultrawork parallelism and architect sign-off."
+
+# ultrawork
+description: "Use when running multiple independent tasks in parallel ('ulw', 'ultrawork', 'run in parallel'). Tiered agent routing: haiku/sonnet/opus fired simultaneously."
+
+# plan
+description: "Use when planning before coding ('plan this', 'plan the', 'let's plan', 'make a plan'). Interview, direct, consensus (--consensus), and review (--review) modes."
+
+# team
+description: "Use when coordinating multiple agents on a project ('team', 'coordinated team', 'multi-agent', 'swarm'). TeamCreate→tasks→parallel agents→verify→TeamDelete pipeline."
+```
+
+### Quality / Skill Tooling
+
+```yaml
+# writing-skills
+description: "This skill should be used when the user asks to 'create a skill', 'write a new skill', 'add a skill', or 'improve an existing skill'. Covers structure, description quality, progressive disclosure, and the quality pipeline."
+
+# skill-quality-analyzer
+description: "This skill should be used when the user asks to 'analyze skill quality', 'score skill', 'skill quality report', or 'audit skill'. 6-dimension scoring: clarity, structure, examples, triggers, practices, maintainability."
+
+# skill-debugger
+description: "This skill should be used when the user asks to 'debug skill', 'skill not triggering', 'why isn't skill working', or 'skill discovery issue'. Diagnoses description quality, naming, conflicts, and file structure."
+
+# skill-tester
+description: "This skill should be used when the user asks to 'test skill', 'verify skill', 'does this skill trigger', or 'skill test'. Trigger tests, functional tests, and edge case validation."
+```
+
+### Domain / Code Skills
+
+```yaml
+# tdd
+description: "This skill should be used when the user asks to 'tdd', 'test first', 'red green refactor', or 'write tests first'. Enforces Red→Green→Refactor cycle — no implementation before failing test."
+
+# security-review
+description: "This skill should be used when the user asks to 'security review', 'check for vulnerabilities', 'OWASP audit', or 'security scan'. Comprehensive review across OWASP Top 10, authn/authz, and trust boundaries."
+
+# code-review
+description: "This skill should be used when the user asks to 'code review', 'review this PR', 'review code', or 'check my code'. Multi-layer review: style, quality, security, API compatibility, performance."
+
+# ai-commenting
+description: "This skill should be used when the user asks to 'ai comment', 'annotate code', 'add ai tags', or 'mark high-risk code'. Machine-parseable @ai: protocol for risk, intent, deps, auth, invariants."
+```
+
+### Utility / Management Skills
+
+```yaml
+# note
+description: "This skill should be used when the user asks to 'note', 'remember this', 'save note', or 'notepad'. Persists to .omc/notepad.md — survives context compaction."
+
+# cancel
+description: "This skill should be used when the user wants to 'cancel', 'stop', or 'abort' an active OMC mode. Cleanly exits autopilot, ralph, ultrawork, ultraqa, team, pipeline state."
+
+# trace
+description: "This skill should be used when the user asks to 'trace', 'show agent trace', 'what agents ran', or 'session timeline'. Renders timeline of agent calls and results."
+
+# hud
+description: "This skill should be used when the user asks to 'hud', 'configure display', 'hud layout', or 'status bar'. Sets layout, visible elements, and display presets."
+```
+
+---
+
+## Quick Self-Check
+
+Before finalizing a description, ask:
+
+1. **Natural?** Would a user actually say these trigger phrases?
+2. **Specific?** Would it distinguish this skill from similar ones?
+3. **Quoted?** Does it contain at least 2 phrases in `'single quotes'`?
+4. **Summarized?** Does the last sentence say what it produces?
+
+If all 4 are yes → the description is ready.

package/skills/skill-development/references/format-guide.md

@@ -0,0 +1,203 @@
+# Format Guide — OMC Skill Body Structure
+
+Reference for the two body formats used in oh-my-claudecode skills.
+
+---
+
+## Format Selection
+
+| Use case | Format |
+|----------|--------|
+| Workflow/process/orchestration skills (autopilot, ralph, plan, ultrawork) | XML tags |
+| Utility/tool/management skills (note, trace, hud, skill) | Markdown headers |
+| Domain skills with a clear protocol (tdd, security-review, ai-commenting) | Either — be consistent |
+
+**Rule**: Pick one format per skill and don't mix them.
+
+---
+
+## XML Tag Format (Workflow Skills)
+
+### Required tags
+
+```xml
+<Purpose>
+What the skill does and what it produces. 2-4 sentences.
+Answers: "What is this?" and "What do I get at the end?"
+</Purpose>
+
+<Use_When>
+- Specific trigger conditions (be concrete, not vague)
+- List exact phrases: User says "autopilot", "build me", "I want a..."
+- List task types that warrant this skill
+</Use_When>
+
+<Do_Not_Use_When>
+- Explicitly redirect to the right skill: "use `ralph` instead"
+- List cases where users commonly misapply this skill
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+1-2 sentences explaining the problem this solves.
+Prevents misuse by setting expectations.
+</Why_This_Exists>
+
+<Steps>
+Ordered procedure. Each step should be a concrete action.
+Include sub-steps where needed.
+Reference agents with: Task(subagent_type="oh-my-claudecode:executor", ...)
+</Steps>
+
+<Examples>
+<Good>
+Concrete correct usage with explanation.
+Why good: [specific reason]
+</Good>
+
+<Bad>
+Common mistake with explanation.
+Why bad: [specific reason]
+</Bad>
+</Examples>
+
+<Final_Checklist>
+- [ ] Checkboxes that verify completion
+- [ ] Each item must be tool-verifiable or judgment-based (label which)
+</Final_Checklist>
+```
+
+### Optional tags
+
+```xml
+<Execution_Policy>
+Hard rules that override default behavior.
+Use for: parallelism rules, model selection, iteration limits.
+</Execution_Policy>
+
+<Tool_Usage>
+Which tools to use and when.
+Required if the skill uses MCP tools (ToolSearch, ask_codex, ask_gemini).
+</Tool_Usage>
+
+<Escalation_And_Stop_Conditions>
+When to stop and report vs. keep going.
+Required for loop/persistence skills (ralph, ultrawork, ultraqa).
+</Escalation_And_Stop_Conditions>
+
+<Advanced>
+Detail that's useful but not needed for basic execution.
+This implements progressive disclosure — moved here from main body to keep it lean.
+</Advanced>
+```
+
+### Anti-patterns in XML format
+
+```xml
+<!-- ❌ Vague Use_When -->
+<Use_When>
+- When the user needs help
+- For complex tasks
+</Use_When>
+
+<!-- ✅ Specific Use_When -->
+<Use_When>
+- User says "autopilot", "build me", "I want a [project]"
+- Task requires multiple phases: spec, code, test, validate
+- User wants hands-off execution to completion
+</Use_When>
+```
+
+---
+
+## Markdown Header Format (Utility Skills)
+
+```markdown
+# Skill Name
+
+One-sentence purpose statement.
+
+## When to Use
+
+Use this skill when:
+- [specific scenario]
+- [specific scenario]
+
+## When NOT to Use
+
+- [redirect]: use `other-skill` instead
+
+## Workflow
+
+1. [Step]
+2. [Step]
+
+## Examples
+
+**Basic**:
+"[example invocation]"
+
+**Advanced**:
+"[example invocation]"
+
+## Notes / Limitations
+
+- [caveat]
+```
+
+---
+
+## Size Targets
+
+| File | Target | Maximum |
+|------|--------|---------|
+| SKILL.md body | ≤150 lines | 200 lines |
+| references/*.md | ≤250 lines | 400 lines |
+
+If SKILL.md body exceeds 200 lines:
+1. Identify the largest "reference-style" section (tables, long examples, advanced techniques)
+2. Move it to `references/<topic>.md`
+3. Add a pointer in SKILL.md: `See references/<topic>.md for detailed patterns.`
+
+---
+
+## Writing Style Rules
+
+### Imperative form (required)
+
+```
+✅ "Start by reading the configuration file."
+✅ "Validate the input before processing."
+✅ "Use the Read tool to examine the skill content."
+
+❌ "You should start by reading the configuration file."
+❌ "You need to validate the input."
+❌ "Claude should use the Read tool."
+```
+
+### Description (frontmatter) — third person
+
+```yaml
+✅ description: "This skill should be used when the user asks to 'create X', 'configure Y'."
+✅ description: "Use when user wants to [scenario] ('[trigger 1]', '[trigger 2]')."
+
+❌ description: Use this skill when you want to create X.
+❌ description: Load when user needs help.
+```
+
+### No platform branding
+
+Never include "Codex CLI", "Codex skill", or similar in body content — this is a Claude Code skill.
+
+---
+
+## Frontmatter Fields
+
+```yaml
+---
+name: skill-name          # required; must match folder name exactly (kebab-case)
+description: "..."        # required; must contain quoted trigger phrases
+argument-hint: "<args>"   # optional; shown in skill listing
+---
+```
+
+Only `name` and `description` are used by Claude for skill discovery and invocation. Additional fields are ignored at runtime.