oh-my-customcode 0.7.0 → 0.9.0

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

@@ -0,0 +1,145 @@
+# [SHOULD] Ecomode Rules
+
+> **Priority**: SHOULD - Recommended for token efficiency
+> **ID**: R013
+
+## Purpose
+
+Reduce token usage and improve efficiency during batch operations and parallel execution.
+
+## Activation Conditions
+
+Ecomode is automatically activated when:
+
+```yaml
+conditions:
+  - 4+ parallel tasks spawned
+  - Batch operations requested
+  - Near compaction threshold (80%+ context usage)
+  - Explicit user request: "ecomode on"
+```
+
+## Behaviors
+
+### 1. Compact Output Format
+
+When ecomode is active, parallel agents return:
+
+```yaml
+format:
+  - status: success | failed | partial
+  - summary: 1-2 sentences max
+  - key_data: essential results only
+
+skip:
+  - Intermediate steps
+  - Verbose explanations
+  - Repeated context
+  - Full file contents (use paths instead)
+```
+
+### 2. Aggregation Format
+
+Secretary aggregates results in compact format:
+
+```
+[Batch Complete] {n}/{total}
+├── {agent}: {icon} {summary}
+├── {agent}: {icon} {summary}
+└── {agent}: {icon} {summary}
+```
+
+Icons:
+- ✓ success
+- ✗ failed
+- ⚠ partial/warning
+
+### 3. Result Compression
+
+```yaml
+compress:
+  - File lists → count only unless < 5 files
+  - Error traces → first and last 3 lines
+  - Code snippets → path:line reference only
+  - Long outputs → truncate with "[truncated]"
+```
+
+## Secretary Ecomode Config
+
+```yaml
+ecomode:
+  enabled: true
+  threshold: 4           # Activate when >= 4 parallel tasks
+  result_format: summary # summary | full
+  max_result_length: 200 # characters per result
+```
+
+## Examples
+
+### Normal Mode Output
+
+```
+┌─ Agent: lang-golang-expert (sw-engineer)
+├─ Skill: go-best-practices
+└─ Task: Reviewing src/main.go
+
+Reading file...
+[lang-golang-expert → Read] src/main.go
+
+Analyzing code structure...
+Found 3 functions, 2 structs, 1 interface.
+
+Checking naming conventions...
+Function 'GetUser' follows Go naming conventions.
+Function 'processData' follows Go naming conventions.
+Function 'handle_error' VIOLATION: uses snake_case instead of camelCase.
+
+[...]
+
+Review Complete:
+- 1 naming violation found
+- 2 potential improvements suggested
+- Overall code quality: Good
+```
+
+### Ecomode Output
+
+```
+[lang-golang-expert] ✓ src/main.go reviewed: 1 naming issue (handle_error → handleError)
+```
+
+## Implementation Notes
+
+### For Orchestrator (Secretary)
+
+```yaml
+responsibilities:
+  - Detect ecomode activation conditions
+  - Instruct spawned agents to use compact format
+  - Aggregate results in batch format
+  - Track token savings
+```
+
+### For Worker Agents
+
+```yaml
+when_ecomode_active:
+  - Return status + summary only
+  - Skip intermediate progress updates
+  - Use references instead of full content
+  - Compress error messages
+```
+
+## Override
+
+User can disable ecomode:
+- "ecomode off"
+- "verbose mode"
+- "show full details"
+
+## Benefits
+
+1. **Token Efficiency**: 60-80% reduction in batch operations
+2. **Faster Response**: Less output processing
+3. **Better Overview**: Aggregated results at a glance
+4. **Context Preservation**: More room for actual work

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

@@ -0,0 +1,102 @@
+# [SHOULD] Error Handling Rules
+
+> **Priority**: SHOULD - Strongly recommended
+> **Goal**: Safe failure, fast recovery
+
+## Error Classification
+
+### Level 1: Warning
+```
+Symptom: Task completes but needs attention
+Response: Output warning, continue
+Example:
+  - Non-recommended pattern found
+  - Potential performance issue
+  - Better alternative exists
+```
+
+### Level 2: Error
+```
+Symptom: Current task fails, others possible
+Response: Stop task, report cause, suggest alternative
+Example:
+  - File not found
+  - Insufficient permission
+  - Format error
+```
+
+### Level 3: Critical
+```
+Symptom: Cannot proceed at all
+Response: Stop all, preserve state, report immediately
+Example:
+  - System resource exhausted
+  - Missing required dependency
+  - Security violation detected
+```
+
+## Error Report Format
+
+```
+[Error] {error type}
+
+Location: {file:line or task name}
+Cause: {specific cause}
+Impact: {effect of this error}
+
+Attempted:
+1. {attempt 1} → Failed
+2. {attempt 2} → Failed
+
+Recommended:
+- {action 1}
+- {action 2}
+```
+
+## Recovery Strategy
+
+### Retryable Errors
+```
+1. Retry up to 3 times
+2. Wait between retries (1s, 2s, 4s)
+3. Report to user after 3 failures
+```
+
+### Non-recoverable Errors
+```
+1. Save current state
+2. Rollback changes (if possible)
+3. Detailed error report
+4. Wait for user instruction
+```
+
+## Preventive Validation
+
+### Before Action
+```
+□ Target file/path exists
+□ Required permissions available
+□ Dependencies met
+□ Sufficient resources
+```
+
+### After Action
+```
+□ Expected result matches actual
+□ File integrity verified
+□ No side effects
+```
+
+## Error Logging
+
+```yaml
+error_log:
+  timestamp: "2025-01-22T10:30:00Z"
+  level: error
+  code: FILE_NOT_FOUND
+  message: "Config file not found"
+  context:
+    file: "/path/to/config.yaml"
+    action: "read"
+  resolution: "Using default config"
+```

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

@@ -0,0 +1,112 @@
+# [SHOULD] HUD Statusline Rules
+
+> **Priority**: SHOULD - Recommended for visibility
+> **ID**: R012
+
+## Purpose
+
+Display real-time status information during agent operations for improved visibility and progress tracking.
+
+## Format
+
+```
+─── [Agent] {name} | [Progress] {n}/{total} | [Parallel] {count} ───
+```
+
+## Update Triggers
+
+| Trigger | Description |
+|---------|-------------|
+| Agent activation | When an agent starts handling a task |
+| Task start | When a specific task begins execution |
+| Task complete | When a task finishes (success or failure) |
+| Parallel spawn | When parallel instances are created |
+| Parallel complete | When parallel instances finish |
+
+## Components
+
+| Component | Description | Example |
+|-----------|-------------|---------|
+| Agent | Active agent name | `lang-golang-expert` |
+| Model | Model used (for parallel) | `sonnet` |
+| Progress | Task progress (current/total) | `2/5` |
+| Parallel | Parallel instance count | `3` |
+
+## Display Rules
+
+### Single Agent
+
+```
+─── [Agent] mgr-creator | [Progress] 1/3 ───
+```
+
+### With Parallel Execution (Model Display REQUIRED)
+
+```
+─── [Agent] secretary | [Progress] 0/4 | [Parallel] 4 ───
+
+Instances:
+  [1] Task(general-purpose):sonnet → README update
+  [2] Task(lang-golang-expert):haiku → Code review
+  [3] Task(Explore):opus → Architecture analysis
+  [4] Task(general-purpose):haiku → Validation
+```
+
+### Completion
+
+```
+─── [Agent] mgr-supplier | [Progress] 5/5 | [Done] ───
+```
+
+## Implementation
+
+Status updates via stderr to avoid output pollution:
+
+```bash
+echo "─── [Agent] $AGENT | [Progress] $PROGRESS ───" >&2
+```
+
+## Integration with Other Rules
+
+| Rule | Integration |
+|------|-------------|
+| R007 (Agent ID) | HUD complements agent identification |
+| R008 (Tool ID) | HUD shows overall progress, tool ID shows specific operations |
+| R009 (Parallel) | HUD displays parallel instance count |
+
+## When to Display
+
+| Situation | Display HUD |
+|-----------|-------------|
+| Single file operation | No (too brief) |
+| Multi-step task | Yes |
+| Parallel execution | Yes |
+| Long-running operations | Yes |
+
+## Hook Usage
+
+The HUD statusline is implemented as an inline hook in `.codex/hooks/hooks.json` (PreToolUse → Task matcher).
+
+The hook automatically displays subagent details when the Task tool is used:
+
+```
+─── [Spawn] {subagent_type}:{model} | {description} ───
+─── [Resume] {subagent_type}:{model} | {description} ───
+```
+
+### Examples
+
+```
+─── [Spawn] mgr-gitnerd:sonnet | Commit and push ───
+─── [Spawn] lang-golang-expert:sonnet | Review Go code ───
+─── [Spawn] mgr-creator:sonnet | Create new agent ───
+─── [Resume] mgr-gitnerd:sonnet | Continue push ───
+```
+
+### Fields Displayed
+
+| Field | Source | Purpose |
+|-------|--------|---------|
+| `subagent_type` | Task tool parameter | Which agent is running |
+| `model` | Task tool parameter | Which model (opus/sonnet/haiku) |
+| `description` | Task tool parameter | What the agent is doing (max 40 chars) |

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

@@ -0,0 +1,103 @@
+# [SHOULD] Interaction Rules
+
+> **Priority**: SHOULD - Strongly recommended
+> **Exception**: Emergency or explicit user request
+
+## Response Principles
+
+### 1. Brevity
+```
+✓ Key information first
+✓ Skip unnecessary preamble
+✓ Answer only what's asked
+✗ Over-explanation
+✗ Repetitive confirmation
+```
+
+### 2. Clarity
+```
+✓ Specific expressions
+✓ Unambiguous instructions
+✓ Executable code format
+✗ Abstract descriptions only
+✗ Overuse of "maybe", "probably"
+```
+
+### 3. Transparency
+```
+✓ State actions performed
+✓ Report changes
+✓ Acknowledge uncertainty
+✗ Hide actions
+✗ Present guesses as facts
+```
+
+## Status Report Format
+
+### Start
+```
+[Start] {task name}
+```
+
+### In Progress
+```
+[Progress] {current step} ({n}/{total})
+```
+
+### Complete
+```
+[Done] {task name}
+Result: {summary}
+```
+
+### Failed
+```
+[Failed] {task name}
+Cause: {reason}
+Alternative: {possible solutions}
+```
+
+## Handling Requests
+
+### Clear Request
+→ Execute immediately
+
+### Ambiguous Request
+```
+[Confirm]
+Understood "{request}" as {interpretation}.
+
+Proceed?
+```
+
+### Risky Request
+```
+[Warning]
+This action has {risk factor}.
+
+Continue?
+- Yes: {action to perform}
+- No: Cancel
+```
+
+## Multiple Tasks
+
+### Order
+1. Dependent tasks: Sequential
+2. Independent tasks: Parallel allowed
+
+### Report
+```
+[Task 1/3] Done - {result}
+[Task 2/3] In progress...
+[Task 3/3] Pending
+```
+
+## Long-running Tasks
+
+```
+[In Progress] {task name}
+Elapsed: {time}
+Current: {step}
+Remaining: {work left}
+```

package/templates/.codex/rules/SHOULD-memory-integration.md

@@ -0,0 +1,132 @@
+# [SHOULD] Memory Integration Rules
+
+> **Priority**: SHOULD - Recommended for context persistence
+> **ID**: R011
+
+## Purpose
+
+Provide persistent memory for agents using Claude Code's native auto memory system.
+
+## Architecture: Native First
+
+```
+Primary: Native Auto Memory (memory field in agent frontmatter)
+  - Agent-specific persistent knowledge
+  - Automatic system prompt injection (MEMORY.md)
+  - No external dependencies
+
+Supplementary: claude-mem MCP (optional)
+  - Session-level temporal observations
+  - Cross-agent semantic search
+  - Only if installed and configured
+
+RULE: If native auto memory can handle the task,
+      DO NOT use claude-mem.
+```
+
+## Native Auto Memory
+
+### How It Works
+
+1. Agent frontmatter includes `memory` field:
+   ```yaml
+   memory: project  # or user, local
+   ```
+
+2. System automatically:
+   - Creates memory directory for the agent
+   - Loads first 200 lines of MEMORY.md into system prompt
+   - Enables Read/Write/Edit tools for memory directory
+   - Agent learns and records patterns across conversations
+
+### Memory Scopes
+
+| Scope | Location | Use Case | Git Tracked |
+|-------|----------|----------|-------------|
+| `user` | `~/.codex/agent-memory/<name>/` | Cross-project patterns | No |
+| `project` | `.codex/agent-memory/<name>/` | Project-specific patterns | Yes |
+| `local` | `.codex/agent-memory-local/<name>/` | Local-only knowledge | No |
+
+### Current Agent Memory Map
+
+| Scope | Agents | Count |
+|-------|--------|-------|
+| `project` | lang-*, be-*, fe-*, arch-*, tool-*, qa-*, mgr-creator, mgr-updater, mgr-gitnerd, mgr-sauron, mgr-claude-code-bible, sys-memory-keeper | 28 |
+| `user` | infra-docker-expert, infra-aws-expert, db-supabase-expert | 3 |
+| `local` | mgr-supplier, mgr-sync-checker, sys-naggy | 3 |
+
+### Memory Best Practices
+
+```yaml
+do:
+  - Let agents consult memory before starting work
+  - Update memory after discovering patterns or conventions
+  - Keep MEMORY.md under 200 lines (auto-curate if exceeded)
+  - Use separate topic files for detailed notes
+
+dont:
+  - Store sensitive data (API keys, credentials)
+  - Duplicate information already in AGENTS.md
+  - Use memory for temporary session state
+```
+
+## Claude-mem (Optional Supplement)
+
+claude-mem MCP provides session-level observations and semantic search.
+It is NOT required for basic memory functionality.
+
+### When to Use claude-mem
+
+| Scenario | Use Native Memory | Use claude-mem |
+|----------|------------------|---------------|
+| Agent learns project patterns | Yes | |
+| Record debugging insights | Yes | |
+| Search across multiple sessions | | Yes |
+| Temporal queries (date-based) | | Yes |
+| Cross-agent knowledge sharing | | Yes |
+| Basic context persistence | Yes | |
+
+### claude-mem Integration (if installed)
+
+```yaml
+provider: claude-mem
+collection: claude_memories
+project_tag: my-project
+status: optional
+```
+
+## Context Compaction
+
+### Compaction Controls
+
+```yaml
+# Targeted compaction - preserve specific context
+/compact focus on {topic}
+
+# Examples
+/compact focus on agent routing decisions
+/compact focus on authentication implementation
+/compact focus on test failures and fixes
+```
+
+### Best Practices
+
+```
+do:
+  - Use /compact focus when nearing context limits
+  - Focus on the most relevant topic for current work
+  - Let auto-compaction handle routine cleanup
+
+dont:
+  - Manually compact when not near limits
+  - Lose important decision context by unfocused compaction
+```
+
+## Error Handling
+
+```yaml
+on_memory_write_failure:
+  - Log error
+  - Continue without blocking main task
+  - Memory is enhancement, not requirement
+```