oh-my-customcodex 0.1.0

package/templates/.claude/rules/MUST-sync-verification.md

@@ -0,0 +1,145 @@
+# [MUST] Sync Verification Rules
+
+> **Priority**: MUST | **ID**: R017
+
+## Core Rule
+
+After modifying agents, skills, or guides: run full verification before committing AND pushing. Never ask to commit/push before `mgr-sauron:watch` passes.
+
+Every `git push` requires: `mgr-sauron:watch` → all pass → `git push`
+
+## Verification Phases
+
+### Phase 1: Manager Verification (5 rounds)
+
+| Round | Actions |
+|-------|---------|
+| 1-2 | mgr-supplier:audit, mgr-updater:docs (sync check), fix issues |
+| 3-4 | Re-verify mgr-supplier:audit + re-run mgr-updater:docs, fix remaining |
+| 5 | Final: all counts match, frontmatter valid, skill refs exist, memory scopes valid, routing patterns updated |
+
+Also run: mgr-claude-code-bible:verify (official spec compliance)
+
+### Phase 2: Deep Review (3 rounds)
+
+| Round | Focus |
+|-------|-------|
+| 1 | Workflow alignment: routing skills have complete agent mappings |
+| 2 | References: no orphans, no circular refs, valid skill/memory refs |
+| 3 | Philosophy: R006 separation, R009 parallel, R010 delegation, R007/R008 identification |
+
+### Phase 3: Wiki Sync Verification
+
+| Check | Action |
+|-------|--------|
+| Missing pages | Source entities without wiki pages → run `/omcodex:wiki` |
+| Stale pages | Source modification date newer than wiki `updated` field → run `/omcodex:wiki ingest <path>` |
+| Broken cross-refs | Wiki links pointing to non-existent pages → run `/omcodex:wiki lint` |
+| index.md accuracy | Wiki index page count matches actual page count |
+
+Wiki verification is also enforced by CI (`.github/workflows/wiki-sync.yml`).
+
+### Phase 4: Fix all discovered issues
+
+### Phase 5: Commit via mgr-gitnerd
+
+### Phase 6: Push via mgr-gitnerd (only after sauron passes)
+
+## Self-Check — 6-point commit check + 3-point push check. See full checklist via Read tool.
+
+<!-- DETAIL: Self-Check Before Commit and Push
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  BEFORE COMMITTING, ASK YOURSELF:                                ║
+║                                                                   ║
+║  1. Did I complete all 5 rounds of manager verification?         ║
+║  2. Did I complete all 3 rounds of deep review?                  ║
+║  3. Did I fix all discovered issues?                             ║
+║  4. Are all counts matching across all sources?                  ║
+║  5. Am I delegating to mgr-gitnerd for the commit?               ║
+║  6. Are wiki pages in sync with source changes?                  ║
+║                                                                   ║
+║  If NO to any → wait until verification completes                ║
+╚══════════════════════════════════════════════════════════════════╝
+
+╔══════════════════════════════════════════════════════════════════╗
+║  BEFORE PUSHING, ASK YOURSELF:                                   ║
+║                                                                   ║
+║  1. Did mgr-sauron:watch complete successfully?                  ║
+║  2. Were all issues from sauron verification fixed?              ║
+║  3. Am I delegating to mgr-gitnerd for the push?                 ║
+║                                                                   ║
+║  If NO to any → wait until sauron verification passes            ║
+║                                                                   ║
+║  Sauron verification is required for all pushes.                 ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+-->
+
+## When Required
+
+Any change to: agents, agent frontmatter, skills, guides, routing patterns, rules, wiki pages.
+
+## Quick Verification Commands — agent/skill/guide/wiki counts via ls/find/wc. See commands via Read tool.
+
+<!-- DETAIL: Quick Verification Commands
+
+Key checks: agent count (`ls .codex/agents/*.md | wc -l`), skill count (`find .codex/skills -name "SKILL.md" | wc -l`), guide count (`find guides -mindepth 1 -maxdepth 1 -type d | wc -l`), wiki page count (`find wiki -name "*.md" ! -name "index.md" ! -name "log.md" | wc -l`).
+
+Full verification bash scripts:
+```bash
+# Agent count check
+ls .codex/agents/*.md | wc -l
+
+# Skill count check
+find .codex/skills -name "SKILL.md" | wc -l
+
+# Frontmatter validation (check for missing YAML headers)
+for f in .codex/agents/*.md; do head -1 "$f" | grep -q "^---" || echo "MISSING FRONTMATTER: $f"; done
+
+# Check for agents with invalid skill references
+for f in .codex/agents/*.md; do
+  grep "^skills:" -A 10 "$f" | grep "  - " | sed 's/.*- //' | while read skill; do
+    [ -f ".codex/skills/$skill/SKILL.md" ] || echo "INVALID SKILL REF in $f: $skill"
+  done
+done
+
+# Routing skill pattern coverage
+grep -c "agent_patterns:" .codex/skills/secretary-routing/SKILL.md
+grep -c "agent_patterns:" .codex/skills/dev-lead-routing/SKILL.md
+grep -c "agent_patterns:" .codex/skills/qa-lead-routing/SKILL.md
+
+# Memory field validation
+for f in .codex/agents/*.md; do
+  mem=$(grep "^memory:" "$f" | awk '{print $2}')
+  if [ -n "$mem" ] && [ "$mem" != "project" ] && [ "$mem" != "user" ] && [ "$mem" != "local" ]; then
+    echo "INVALID MEMORY SCOPE in $f: $mem"
+  fi
+done
+
+# Hook count check
+ls .codex/hooks/*.json 2>/dev/null | wc -l
+
+# Context count check
+ls .codex/contexts/*.md 2>/dev/null | wc -l
+
+# Guide count check
+find guides -mindepth 1 -maxdepth 1 -type d | wc -l
+
+# Agent name accuracy (compare AGENTS.md table with actual files)
+ls .codex/agents/*.md | xargs -I{} basename {} .md | sort > /tmp/actual-agents.txt
+
+# Slash command skill existence
+for cmd in $(grep "^| \`/" AGENTS.md | sed 's/.*`\///' | sed 's/`.*//' | sed 's/ .*//')
+do
+  [ -d ".codex/skills/$cmd" ] || echo "MISSING SKILL: $cmd"
+done
+
+# Routing skill completeness check
+ls -d .codex/skills/*-routing 2>/dev/null | xargs -I{} basename {} | sort
+
+# Verify routing skill names in AGENTS.md
+grep -oP '(secretary|dev-lead|de-lead|qa-lead)-routing' AGENTS.md | sort -u
+```
+-->

package/templates/.claude/rules/MUST-tool-identification.md

@@ -0,0 +1,97 @@
+# [MUST] Tool Usage Identification Rules
+
+> **Priority**: MUST | **ID**: R008
+
+## Core Rule
+
+Every tool call MUST be prefixed with agent and model identification:
+
+```
+[agent-name][model] → Tool: <tool-name>
+[agent-name][model] → Target: <file/path/url>
+```
+
+For parallel calls: list ALL identifications BEFORE the tool calls.
+
+### Common Violations to Avoid
+
+```
+❌ Missing: tool call with no identification prefix
+✓ Correct: [agent-name][model] → Tool: WebFetch
+           [agent-name][model] → Fetching: url
+           <tool_call>...</tool_call>
+```
+
+<!-- DETAIL: Full violation examples
+Incorrect: Calling tools without identification — no [agent][model] prefix before tool_call
+Incorrect: Missing model — [secretary] → Tool: WebFetch (missing [model])
+Correct: [secretary][opus] → Tool: WebFetch / [secretary][opus] → Fetching: url / then tool_call
+
+Incorrect parallel: tool_call(url1), tool_call(url2), tool_call(cmd) — no identification
+Correct parallel: list ALL [agent][model] → Tool/Fetching/Running lines FIRST, then all tool_calls
+-->
+
+## Models
+
+| Model | Use |
+|-------|-----|
+| `opus` | Complex reasoning, architecture |
+| `sonnet` | General tasks, code generation (default) |
+| `haiku` | Fast simple tasks, file search |
+
+## Tool Categories
+
+| Category | Tools | Verb |
+|----------|-------|------|
+| File Read | Read, Glob, Grep | Reading / Searching |
+| File Write | Write, Edit | Writing / Editing |
+| Network | WebFetch | Fetching |
+| Execution | Bash, Agent | Running / Spawning |
+
+## Agent Tool Format
+
+```
+subagent_type:model → description
+```
+
+`subagent_type` MUST match actual Agent tool parameter. Custom names not allowed.
+
+## Parallel Spawn Prefix Rule
+
+When spawning 2+ agents in parallel, each agent's `description` parameter MUST include a `[N]` prefix (1-indexed) to enable correlation with the Running display:
+
+```
+Agent(description: "[1] Go code review", subagent_type: "lang-golang-expert")
+Agent(description: "[2] Python code review", subagent_type: "lang-python-expert")
+```
+
+Single agent spawns do NOT use the `[N]` prefix.
+
+This ensures the Running display:
+```
+⏺ Running 2 agents… (ctrl+o to expand)
+   ├─ [1] Go code review · ...
+   └─ [2] Python code review · ...
+```
+
+matches the spawn announcement:
+```
+[secretary][opus] → Spawning:
+  [1] lang-golang-expert:sonnet → Go code review
+  [2] lang-python-expert:sonnet → Python code review
+```
+
+## Example
+
+```
+[mgr-creator][sonnet] → Write: .codex/agents/new-agent.md
+[secretary][opus] → Spawning:
+  [1] lang-golang-expert:sonnet → Go code review
+  [2] lang-python-expert:sonnet → Python code review
+```
+
+Parallel spawn description parameter:
+```
+Agent(description: "[1] Go code review", subagent_type: "lang-golang-expert", ...)
+Agent(description: "[2] Python code review", subagent_type: "lang-python-expert", ...)
+```

package/templates/.claude/rules/SHOULD-ecomode.md

@@ -0,0 +1,123 @@
+# [SHOULD] Ecomode Rules
+
+> **Priority**: SHOULD | **ID**: R013
+
+## Activation
+
+Auto-activates when: 4+ parallel tasks, batch operations, 80%+ context usage, or explicit "ecomode on".
+
+## Behaviors
+
+**Compact Output**: Agents return `status + summary (1-2 sentences) + key_data only`. Skip intermediate steps, verbose explanations, repeated context, full file contents.
+
+**Aggregation Format**:
+```
+[Batch Complete] {n}/{total}
+├── {agent}: ✓/✗/⚠ {summary}
+```
+
+**Compression**: File lists -> count only (unless < 5), error traces -> first/last 3 lines, code -> path:line ref only.
+
+## Config
+
+```yaml
+ecomode:
+  threshold: 4
+  result_format: summary
+  max_result_length: 200
+```
+
+## Example
+
+Normal: Full agent header + step-by-step analysis + detailed results.
+Ecomode: `[lang-golang-expert] ✓ src/main.go reviewed: 1 naming issue (handle_error -> handleError)`
+
+## Override
+
+Disable with: "ecomode off", "verbose mode", or "show full details".
+
+## Input Context Pruning — Active removal of irrelevant content. See full spec via Read tool.
+
+<!-- DETAIL: Input Context Pruning
+
+Active removal of irrelevant retrieved content from agent context. Complements output compression by managing the input side of token budget.
+
+> **Terminology**: "Input Context Pruning" (R013) manages retrieved chunks during a task. "Memory Pruning" (R011) manages behavioral memory across sessions. These are distinct concepts.
+
+### Pruning Triggers
+
+| Trigger | Condition | Action |
+|---------|-----------|--------|
+| Search overflow | Retrieved chunks > 10 | Retain top-K by relevance, prune rest |
+| Context pressure | Context usage > 50% | Summarize oldest/lowest-relevance chunks |
+| Multi-hop intermediate | Between retrieval hops | Replace previous hop raw results with summary |
+
+### Pruning Strategy
+
+| Strategy | When | Behavior |
+|----------|------|----------|
+| **Retain** | Directly relevant code/docs | Keep as-is |
+| **Summarize** | Background context, prior hop results | Replace with 1-2 line summary |
+| **Drop** | Search noise, duplicates, already-reflected info | Remove entirely |
+
+### Rules
+
+- Pruning is irreversible — generate summary BEFORE dropping original
+- Prune at document/chunk level, not mid-sentence
+- When in doubt, Summarize rather than Drop
+- Track pruning decisions: `[Pruned] {N} chunks → {M} retained, {K} summarized, {J} dropped`
+-->
+
+## Context Budget Management — Task-type-aware thresholds (research 40%, implementation 50%, review 60%, management 70%, general 80%). See full spec via Read tool.
+
+<!-- DETAIL: Context Budget Management
+
+Task-type-aware context thresholds that trigger ecomode earlier for context-heavy operations.
+
+### Task Type Thresholds
+
+| Task Type | Context Trigger | Rationale |
+|-----------|----------------|-----------|
+| Research (/research, multi-team) | 40% | High context consumption from parallel team results |
+| Implementation (code generation) | 50% | Moderate context for code + test output |
+| Review (code review, audit) | 60% | Moderate context for diff analysis |
+| Management (git, deploy, CI) | 70% | Lower context needs |
+| General (default) | 80% | Standard threshold |
+
+### Detection
+
+Task type is inferred from active context:
+- **Research**: `/research` skill active, 4+ parallel agents
+- **Implementation**: Write/Edit tools dominant, code files targeted
+- **Review**: Read/Grep dominant, review/audit skill active
+- **Management**: git/gh commands, CI/CD operations
+- **General**: No specific pattern detected
+
+### Budget Advisor Hook
+
+The `context-budget-advisor.sh` hook monitors context usage and emits warnings when task-specific thresholds are approached:
+
+```
+[Context Budget] Task: research | Threshold: 40% | Current: 38%
+[Context Budget] ⚠ Approaching budget limit — consider /compact or ecomode
+```
+
+### Integration
+
+- Works with existing ecomode activation (R013)
+- Does NOT override explicit user settings
+- Advisory only — never blocks operations
+- Context percentage from statusline data when available
+-->
+
+## Token Guardian Coexistence — R013 context budget (usage-based) + cc-token-saver Token Guardian (time-based) can run simultaneously.
+
+<!-- DETAIL: Token Guardian Coexistence (cc-token-saver)
+
+| Component | Trigger | Scope |
+|-----------|---------|-------|
+| `context-budget-advisor.sh` (R013) | Context usage % approaching threshold | In-session budget |
+| Token Guardian (cc-token-saver) | 1h cache TTL idle detection | Cross-session cost |
+
+Both can run simultaneously — different triggers, complementary coverage. R013's context budget is usage-based (approaching limit), Token Guardian is time-based (idle cache expiry).
+-->

package/templates/.claude/rules/SHOULD-error-handling.md

@@ -0,0 +1,33 @@
+# [SHOULD] Error Handling Rules
+
+> **Priority**: SHOULD | **ID**: R004
+
+## Error Classification
+
+| Level | Symptom | Response |
+|-------|---------|----------|
+| Warning | Task completes but needs attention | Output warning, continue |
+| Error | Current task fails, others possible | Stop task, report cause, suggest alternative |
+| Critical | Cannot proceed at all | Stop all, preserve state, report immediately |
+
+## Error Report Format
+
+```
+[Error] {type} — Location: {file:line} — Cause: {cause} — Impact: {effect}
+Attempted: 1. {try1} -> Failed  2. {try2} -> Failed
+Recommended: {action1}, {action2}
+```
+
+## Recovery
+
+| Type | Strategy |
+|------|----------|
+| Retryable | Retry up to 3x with backoff (1s, 2s, 4s), then report |
+| Non-recoverable | Save state, rollback if possible, detailed report, wait for user |
+
+## Validation
+
+| When | Checks |
+|------|--------|
+| Before action | Target exists, permissions available, dependencies met |
+| After action | Expected = actual, file integrity, no side effects |

package/templates/.claude/rules/SHOULD-hud-statusline.md

@@ -0,0 +1,51 @@
+# [SHOULD] HUD Statusline Rules
+
+> **Priority**: SHOULD | **ID**: R012
+
+## Two-System Architecture
+
+| Aspect | HUD Events | Statusline API |
+|--------|-----------|----------------|
+| Channel | stderr (hooks) | stdout (dedicated statusline) |
+| Location | Inline in conversation log | Persistent bar at screen bottom |
+| Trigger | PreToolUse (Agent/Task matcher) | Message update cycle (~300ms) |
+| Role | Event notifications | Persistent session status |
+
+## HUD Events (Hook-based)
+
+Format: `─── [Spawn] {subagent_type}:{model} | {description} ───` — implemented in `.codex/hooks/hooks.json` (PreToolUse → Agent/Task matcher). Display for multi-step/parallel/long-running ops only.
+
+<!-- DETAIL: HUD Events full spec
+### When to Display: Multi-step tasks, parallel execution, long-running operations. Skip for single brief operations.
+### Parallel Display:
+─── [Agent] secretary | [Parallel] 4 ───
+  [1] Agent(mgr-creator):sonnet → Create agent
+  [2] Agent(lang-golang-expert):haiku → Code review
+-->
+
+## Statusline API (Command-based)
+
+Format: `{Cost} | {project} | {branch} | RL:{rate_limit}% {countdown} | WL:{weekly_limit}% {countdown} | CTX:{usage}%`
+
+Config in `.codex/settings.local.json`: `statusLine.type: "command"`, `statusLine.command: ".codex/statusline.sh"`. Requires CC v2.1.80+ for RL/WL segments. `refreshInterval` setting (v2.1.97+): Auto-refresh interval in seconds for the status line command. Set in `statusLine.refreshInterval` in settings.json.
+
+<!-- DETAIL: Statusline configuration JSON and color coding
+```json
+{ "statusLine": { "type": "command", "command": ".codex/statusline.sh", "padding": 0 } }
+```
+Color coding: Cost (<$1 green, $1-4.99 yellow, >=5 red), RL/WL (<50% green, 50-79% yellow, >=80% red), CTX (<60% green, 60-79% yellow, >=80% red).
+Countdown format: >=1d → "{d}d{h}h", >=1h → "{h}h{m}m", <1h → "{m}m", unavailable → omitted.
+RL/WL segments omitted on CC older than v2.1.80.
+-->
+
+## Integration
+
+Integrates with R007 (Agent ID), R008 (Tool ID), R009 (Parallel).
+
+## External Plugin Statusline Conflict
+
+| Plugin | Component | Resolution |
+|--------|-----------|------------|
+| cc-token-saver | Live Status Line | R012 `.codex/statusline.sh` has priority. Disable cc-token-saver statusline to avoid duplicate status bars. |
+
+Internal statusline (`.codex/statusline.sh`) is the primary status display. External plugin status lines are supplementary or disabled.

package/templates/.claude/rules/SHOULD-interaction.md

@@ -0,0 +1,77 @@
+# [SHOULD] Interaction Rules
+
+> **Priority**: SHOULD | **ID**: R003
+
+## Response Principles
+
+| Principle | Do | Don't |
+|-----------|-----|-------|
+| Brevity | Key info first, answer only what's asked | Over-explanation, repetitive confirmation |
+| Clarity | Specific expressions, executable code | Abstract descriptions, "maybe"/"probably" |
+| Transparency | State actions, report changes, acknowledge uncertainty | Hide actions, present guesses as facts |
+
+## Status Format
+
+```
+[Start] {task name}
+[Progress] {current step} ({n}/{total})
+[Done] {task name} — Result: {summary}
+[Failed] {task name} — Cause: {reason} — Alternative: {solutions}
+```
+
+## Request Handling
+
+| Type | Action |
+|------|--------|
+| Clear | Execute immediately |
+| Ambiguous | `[Confirm] Understood "{request}" as {interpretation}. Proceed?` |
+| Risky | `[Warning] This action has {risk}. Continue? Yes: {action} / No: Cancel` |
+
+## Multiple Tasks
+
+- Dependent: Sequential
+- Independent: Parallel allowed
+- Report: `[Task 1/3] Done` / `[Task 2/3] In progress...` / `[Task 3/3] Pending`
+
+## Output Styles
+
+| Style | Trigger | Behavior |
+|-------|---------|----------|
+| `concise` | effort: low, batch operations | Key result only, no preamble, no elaboration |
+| `balanced` | effort: medium, general tasks | Summary + key details, minimal explanation |
+| `explanatory` | effort: high, complex/learning tasks | Full reasoning, examples, trade-off analysis |
+
+### Style Selection Priority
+
+1. User explicit request ("be concise", "explain in detail") → Override
+2. Ecomode active → Force `concise`
+3. Agent effort level → Map to corresponding style
+4. Default → `balanced`
+
+### Style Examples — See concise/balanced/explanatory examples via Read tool.
+
+<!-- DETAIL: Style Examples
+**Concise** (effort: low):
+```
+✓ 3 files updated, 0 errors
+```
+
+**Balanced** (effort: medium):
+```
+[Done] Updated authentication module
+- Modified: auth.ts, middleware.ts, config.ts
+- Added JWT validation with 24h expiry
+```
+
+**Explanatory** (effort: high):
+```
+[Done] Updated authentication module — Result: JWT-based auth with refresh tokens
+
+Changes:
+1. auth.ts:45 — Added JWT signing with RS256 algorithm (chosen over HS256 for key rotation support)
+2. middleware.ts:12 — New auth middleware validates token and attaches user context
+3. config.ts:8 — Added TOKEN_EXPIRY (24h) and REFRESH_EXPIRY (7d) constants
+
+Trade-offs: RS256 is ~10x slower than HS256 but enables asymmetric key management.
+```
+-->