oh-my-customcodex 0.1.0

package/templates/.claude/rules/MUST-agent-design.md

@@ -0,0 +1,340 @@
+# [MUST] Agent Design Rules
+
+> **Priority**: MUST | **ID**: R006
+
+## Agent File Format
+
+Location: `.codex/agents/{name}.md` (single file, kebab-case)
+
+### Required Frontmatter
+
+```yaml
+name: agent-name           # Unique identifier (kebab-case)
+description: Brief desc    # One-line summary
+model: sonnet              # sonnet | opus | haiku | opusplan (or full ID: claude-sonnet-4-6, claude-opus-4-6[1m])
+tools: [Read, Write, ...]  # Allowed tools
+```
+
+### Model Aliases
+
+| Alias | Full ID | Use Case |
+|-------|---------|----------|
+| `haiku` | claude-haiku-4-5 | Fast, cheap tasks (search, simple edits) |
+| `sonnet` | claude-sonnet-4-6 | General tasks, code generation (default) |
+| `opus` | claude-opus-4-6 | Complex reasoning, architecture |
+| `opusplan` | claude-opus-4-6 + plan mode | Architecture planning with approval gates |
+| `opus47` | claude-opus-4-7 | Latest Opus model, supports xhigh effort |
+
+Extended context suffix: `[1m]` (e.g., `claude-opus-4-6[1m]`) — enables 1M token context window.
+
+### Optional Frontmatter
+
+```yaml
+memory: project            # user | project | local
+effort: high               # low | medium | high | xhigh | default | max
+skills: [skill-1, ...]     # Skill name references
+source:                    # For external agents
+  type: external
+  origin: github | npm
+  url: https://...
+  version: 1.0.0
+escalation:              # Model escalation policy (optional)
+  enabled: true          # Enable auto-escalation advisory
+  path: haiku → sonnet → opus  # Escalation sequence
+  threshold: 2           # Failures before advisory
+soul: true                 # Enable SOUL.md identity injection
+isolation: worktree | sandbox  # worktree = git worktree, sandbox = restricted bash
+sandboxFailIfUnavailable: true  # Exit if sandbox unavailable (v2.1.83+)
+background: true           # Run in background
+maxTurns: 10               # Max conversation turns
+maxTokens: 100000          # Per-turn token ceiling
+mcpServers: [server-1]     # MCP servers available
+hooks:                     # Agent-specific hooks
+  PreToolUse:
+    - matcher: "Edit"
+      if: "Edit(*.md)"      # Conditional filter (permission rule syntax, v2.1.85+)
+      command: "echo hook"
+permissionMode: bypassPermissions  # Permission mode
+disallowedTools: [Bash]    # Tools to disallow
+limitations:               # Negative capability declarations
+  - "cannot execute tests"
+  - "cannot modify code"
+domain: backend              # backend | frontend | data-engineering | devops | universal
+disableSkillShellExecution: true  # Disable inline shell execution in skills (v2.1.91+)
+```
+
+> **Note**: When `disableSkillShellExecution` is enabled (v2.1.91+), skills that rely on inline shell execution (e.g., `codex-exec`, `gemini-exec`, `rtk-exec`) will have their shell blocks disabled. This is a security hardening option.
+
+> **Note**: Optional frontmatter fields supported since CC v2.1.63+. Version-specific features listed in HTML comment below — access via Read tool.
+
+<!-- DETAIL: CC Version Compatibility History
+`isolation`, `background`, `maxTurns`, `maxTokens`, `mcpServers`, `hooks`, `permissionMode`, `disallowedTools`, `limitations` are supported in Claude Code v2.1.63+. Hook types `PostCompact`, `Elicitation`, `ElicitationResult` require v2.1.76+. `CwdChanged`, `FileChanged` hook events and `managed-settings.d/` drop-in directory require v2.1.83+. Conditional `if` field for hooks requires v2.1.85+. `PermissionDenied` hook event requires v2.1.88+. `refreshInterval` setting for status line auto-refresh interval added in v2.1.97+. Monitor tool and subprocess sandboxing (`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`, `CLAUDE_CODE_SCRIPT_CAPS`) added in v2.1.98+. Settings resilience (unrecognized hook event names no longer cause settings.json to be ignored) improved in v2.1.101+. PreCompact hook block support (exit 2 / `{"decision":"block"}`) added in v2.1.105+. Skill description listing cap raised from 250 to 1,536 characters in v2.1.105+. Plugin `monitors` manifest key for background monitors added in v2.1.105+. `ENABLE_PROMPT_CACHING_1H` and `FORCE_PROMPT_CACHING_5M` env vars for prompt cache TTL control added in v2.1.108+. Skill tool can now discover and invoke built-in slash commands (`/init`, `/review`, `/security-review`) in v2.1.108+. `/recap` session context feature and `/undo` alias for `/rewind` added in v2.1.108+. `/tui` command and `tui` setting for fullscreen rendering added in v2.1.110+. PushNotification tool for mobile push notifications (Remote Control + config required) added in v2.1.110+. `autoScrollEnabled` config for fullscreen mode added in v2.1.110+. SDK/headless `TRACEPARENT`/`TRACESTATE` distributed trace linking added in v2.1.110+. Bash tool maximum timeout enforcement added in v2.1.110+. Write tool IDE diff feedback (informs model when user edits proposed content) added in v2.1.110+. `--resume`/`--continue` now resurrects unexpired scheduled tasks in v2.1.110+. `/focus` command (separated from Ctrl+O) added in v2.1.110+. `xhigh` effort level for Opus 4.7 (between `high` and `max`; other models fall back to `high`) added in v2.1.111+. `/effort` interactive slider with arrow-key navigation (when called without arguments) added in v2.1.111+. Auto mode no longer requires `--enable-auto-mode` in v2.1.111+. PowerShell tool progressive rollout (`CLAUDE_CODE_USE_POWERSHELL_TOOL` env var) added in v2.1.111+. Read-only bash commands with glob patterns (`ls *.ts`) and `cd <project-dir> &&` prefix no longer trigger permission prompt in v2.1.111+. `/less-permission-prompts` built-in skill for permission allowlist scanning added in v2.1.111+. `/ultrareview` parallel multi-agent cloud code review added in v2.1.111+. `/skills` menu sorting by estimated token count (press `t`) added in v2.1.111+. `OTEL_LOG_RAW_API_BODIES` env var for full API request/response body logging added in v2.1.111+. Plan files named after prompt content (not random words) in v2.1.111+. Plugin error handling improvements (dependency conflict errors, stale version recovery, install recovery) in v2.1.111+.
+`sandbox.network.deniedDomains` setting for domain blocking within `allowedDomains` wildcards added in v2.1.113+. Subagent mid-stream stall detection with auto-fail after 10 minutes added in v2.1.113+. Bash `find -exec`/`-delete` no longer auto-approved under `Bash(find:*)` allow rules in v2.1.113+. Bash deny rules now match exec wrappers (`env`/`sudo`/`watch`/`ionice`/`setsid`) in v2.1.113+. Native binary spawning (per-platform optional dependency) replaces bundled JavaScript in v2.1.113+. `/loop` Esc now cancels pending wakeups in v2.1.113+.
+-->
+
+## Hook Event Types
+
+27 event types documented: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, PostMessage, SessionEnd. 4 handler types: command, prompt, http, agent. See full reference table via Read tool.
+
+<!-- DETAIL: Hook Event Types Full Reference
+
+| Event | Trigger | Data Available | Handler Types | CC Version |
+|-------|---------|---------------|---------------|------------|
+| `PreToolUse` | Before tool execution | tool, tool_input | command, prompt | v2.1.63+ |
+| `PermissionRequest` | Permission dialog shown | tool_name, tool_input, permission_context | command, prompt | v2.1.113+ |
+| `PermissionDenied` | Auto-mode classifier denies tool use | tool, tool_input, denial_reason | command, prompt | v2.1.88+ |
+| `PostToolUse` | After tool execution | tool, tool_input, tool_output | command, prompt | v2.1.63+ |
+| `PostToolUseFailure` | After tool execution fails | tool, tool_input, error | command, prompt | v2.1.113+ |
+| `PreCompact` | Before context compaction | — | command, prompt | v2.1.76+ |
+| `PostCompact` | After context compaction | — | command, prompt | v2.1.76+ |
+| `Stop` | Session ending | — | command, prompt | v2.1.63+ |
+| `StopFailure` | Turn ends with API error | error, error_details | command, prompt | v2.1.113+ |
+| `SessionStart` | Session begins | — | command | v2.1.63+ |
+| `SessionEnd` | Session fully closes | — | command | v2.1.76+ |
+| `SubagentStart` | Subagent spawned | agent_type, model, description | command | v2.1.63+ |
+| `SubagentStop` | Subagent completed | agent_type, model, result | command, prompt | v2.1.63+ |
+| `UserPromptSubmit` | User submits prompt | user_input | command, prompt | v2.1.76+ |
+| `Notification` | Long-running op completes | message | command | v2.1.76+ |
+| `InstructionsLoaded` | AGENTS/CLAUDE/rules file loaded | path, source | command | v2.1.113+ |
+| `ConfigChange` | Config file changed during session | path, scope | command | v2.1.113+ |
+| `CwdChanged` | Working directory changes | old_cwd, new_cwd | command | v2.1.83+ |
+| `FileChanged` | External file modification | file_path, change_type | command | v2.1.83+ |
+| `WorktreeCreate` | Worktree is being created | worktree_path | command | v2.1.113+ |
+| `WorktreeRemove` | Worktree is being removed | worktree_path | command | v2.1.113+ |
+| `Elicitation` | Agent requests user input | question | command, prompt | v2.1.76+ |
+| `ElicitationResult` | User responds to elicitation | answer | command, prompt | v2.1.76+ |
+| `PostMessage` | After message sent | message_type | command | v2.1.76+ |
+| `TeammateIdle` | Agent Teams member idle | teammate_id | command | v2.1.83+ |
+| `TaskCreated` | Task created | task_id, description | command | v2.1.83+ |
+| `TaskCompleted` | Task completed | task_id, result | command | v2.1.83+ |
+
+### Hook Handler Types
+
+| Type | Behavior | Use Case |
+|------|----------|----------|
+| `command` | Execute shell command, stdin receives JSON context | Scripts, validation, logging |
+| `prompt` | Inject text into model context | Rule reinforcement, advisory guidance |
+| `http` | POST to HTTP endpoint | External integrations, webhooks |
+| `agent` | Spawn agent to handle event | Complex event-driven workflows |
+
+### PreToolUse Hook Return Values
+
+| Return | Behavior | CC Version |
+|--------|----------|------------|
+| `exit 0` | Allow tool execution | All |
+| `exit 1` | Block silently | All |
+| `exit 2` + stderr | Block with message | All |
+| `{"decision": "defer"}` | Pause execution; resume with `-p --resume` | v2.1.89+ |
+
+The `defer` decision allows headless sessions to pause at a tool call for human review.
+
+### PreCompact Hook Return Values
+
+| Return | Behavior | CC Version |
+|--------|----------|------------|
+| `exit 0` | Allow compaction | All |
+| `exit 2` + stderr | Block compaction with message | v2.1.105+ |
+| `{"decision": "block"}` | Block compaction (JSON response) | v2.1.105+ |
+
+PreCompact hooks can now prevent context compaction, useful for preserving critical context during multi-step workflows.
+
+### Hook Matcher Syntax
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: "tool == \"Edit\""       # Match specific tool
+      if: "Edit(*.md)"                  # Conditional filter (v2.1.85+)
+      command: "echo hook"
+    - matcher: "*"                       # Match all
+      command: "echo hook"
+```
+
+> **v2.1.85+**: `if` field supports permission rule syntax for conditional hook execution. **v2.1.88** extended `if` matching to support compound commands (`ls && git push`) and commands with env-var prefixes (`FOO=bar git push`).
+-->
+
+## Permission Mode Guidance
+
+When spawning agents via the Agent tool, CC applies a default `mode` of `acceptEdits` if not explicitly specified. To maintain consistent permission behavior:
+
+1. **Agent frontmatter `permissionMode`**: Declares the agent's intended permission level. CC respects this when the agent is spawned via Agent tool.
+2. **Agent tool `mode` parameter**: Overrides frontmatter at spawn time. Routing skills should pass this explicitly.
+3. **Recommendation**: For agents that modify files, set `permissionMode: bypassPermissions` in frontmatter if the project uses `bypassPermissions` mode.
+
+| Mode | Behavior |
+|------|----------|
+| `default` | CC decides per-tool prompting |
+| `acceptEdits` | Auto-accept file edits, prompt for others |
+| `bypassPermissions` | Skip all permission prompts |
+| `plan` | Require plan approval |
+| `dontAsk` | Non-interactive, deny unapproved |
+| `auto` | AI decides safety |
+
+<!-- DETAIL: Isolation/Token/Limitations/Escalation details
+### Isolation Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `worktree` | Isolated git worktree copy | Code changes that need rollback safety |
+| `sandbox` | Restricted Bash environment | Agents running untrusted or scan commands |
+
+When `isolation: sandbox` is set, the agent's Bash calls run with restricted permissions. This is advisory metadata — enforcement depends on the execution environment.
+
+### Token Ceiling
+
+When `maxTokens` is set, it serves as advisory metadata for the orchestrator to manage agent turn budgets. The orchestrator should track output and consider escalation or task splitting when an agent approaches its ceiling.
+
+### Negative Capabilities (Limitations)
+
+The `limitations` field declares what an agent explicitly CANNOT or SHOULD NOT do. This enables:
+1. **Clearer routing**: Orchestrator knows agent boundaries
+2. **Safer delegation**: Prevents accidental capability overreach
+3. **Better documentation**: Makes agent scope explicit
+
+### Escalation Policy
+
+When `escalation.enabled: true`, the model-escalation hooks will track outcomes for this agent type and advise escalation when failures exceed the threshold. This is advisory-only — the orchestrator decides whether to accept the recommendation.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | false | Enable escalation tracking for this agent |
+| `path` | haiku → sonnet → opus | Model upgrade sequence |
+| `threshold` | 2 | Failure count before escalation advisory |
+-->
+
+## Memory Scopes
+
+| Scope | Location | Git Tracked |
+|-------|----------|-------------|
+| `user` | `~/.codex/agent-memory/<name>/` | No |
+| `project` | `.codex/agent-memory/<name>/` | Yes |
+| `local` | `.codex/agent-memory-local/<name>/` | No |
+
+When enabled: first 200 lines of MEMORY.md loaded into system prompt.
+
+## Soul Identity
+
+Optional per-agent identity layer. `soul: true` in frontmatter enables personality/style via `.codex/agents/souls/{name}.soul.md`. Behavioral memory (R011) overrides soul defaults.
+
+<!-- DETAIL: Soul Identity full spec
+| Aspect | Location | Purpose |
+|--------|----------|---------|
+| Capabilities | `.codex/agents/{name}.md` | WHAT the agent does |
+| Identity | `.codex/agents/souls/{name}.soul.md` | HOW the agent communicates |
+
+### Soul File Format: agent: {name}, version: 1.0.0 — Sections: Personality, Style, Anti-patterns
+### Activation: frontmatter soul:true → routing skill reads souls/{name}.soul.md at spawn (Step 5) → prepend to prompt → missing file = graceful fallback
+-->
+
+## Artifact Output Convention
+
+Skills persist output to `.codex/outputs/sessions/{YYYY-MM-DD}/{skill-name}-{HHmmss}.md`. Opt-in, git-untracked. Final subagent writes (R010).
+
+<!-- DETAIL: Artifact Output full spec
+**Format**: Metadata header with `skill`, `date`, `query` fields, followed by skill output content.
+**Rules**: Opt-in per skill, final subagent writes (R010 compliance), Skills create directory (mkdir -p), .codex/outputs/ is git-untracked, no indexing required.
+-->
+
+## Separation of Concerns
+
+| Location | Purpose | Contains |
+|----------|---------|----------|
+| `.codex/agents/` | WHAT the agent does | Role, capabilities, workflow |
+| `.codex/skills/` | HOW to do tasks | Instructions, scripts, rules |
+| `guides/` | Reference docs | Best practices, tutorials |
+
+Agent body: purpose, capabilities overview, workflow. NOT detailed instructions or reference docs.
+
+## Fast Mode
+
+Fast Mode uses the same model with faster output. Activated via `/fast` toggle or `fastMode` setting. Does NOT switch to a different model.
+
+| Aspect | Normal | Fast Mode |
+|--------|--------|-----------|
+| Model | As configured | Same model |
+| Output speed | Standard | ~2.5x faster |
+| Reasoning depth | Full | Reduced |
+
+### Activation
+
+- `/fast` — toggle in current session
+- `fastMode: true` in settings.json
+- `CLAUDE_CODE_DISABLE_FAST_MODE=1` — env var to disable
+
+### Interaction with Effort
+
+When Fast Mode is active, it reduces effective reasoning depth but does NOT override the `effort` frontmatter field. The effort field controls task complexity allocation; Fast Mode controls output generation speed.
+
+### Default Effort Change (CC v2.1.94+)
+
+Starting with Claude Code v2.1.94, the default effort level changed from `medium` to `high` for API-key, Bedrock/Vertex/Foundry, Team, and Enterprise users. Console (free-tier) users retain `medium` as the default.
+
+This means agents WITHOUT an explicit `effort` field now run at `high` effort by default on paid tiers. To maintain previous behavior, set `effort: medium` explicitly in agent frontmatter.
+
+## Skill Frontmatter
+
+Location: `.codex/skills/{name}/SKILL.md`
+
+### Required Fields
+
+```yaml
+name: skill-name           # Unique identifier (kebab-case)
+description: Brief desc    # One-line summary
+```
+
+### Optional Fields
+
+```yaml
+scope: core                # core | harness | package (default: core)
+context: fork              # Forked context for isolated execution
+version: 1.0.0             # Semantic version
+user-invocable: false      # Whether user can invoke directly
+disable-model-invocation: true  # Prevent model from auto-invoking
+effort: medium              # low | medium | high | default | max — overrides model effort level when invoked
+argument-hint: "<arg> [--flag]"  # CLI-style usage hint displayed in /help and command listings
+model: sonnet                      # Override spawned model when skill is invoked via Agent
+agent: mgr-creator                 # Preferred agent to execute this skill
+hooks:                             # Skill-specific hooks (same syntax as agent hooks)
+  PreToolUse:
+    - matcher: "Bash"
+      command: "echo hook"
+paths: ["src/**/*.ts"]             # Conditional loading — skill auto-injected when matching files are open
+shell: "bash"                      # Shell for embedded script execution
+allowed-tools: [Read, Write, Bash] # Restrict tools available during skill execution
+keep-coding-instructions: true     # Preserve coding instructions in plugin output styles (v2.1.94+)
+```
+
+When both an agent and its invoked skill specify `effort`, the skill's value takes precedence (more specific invocation-time setting).
+
+<!-- DETAIL: Skill Effectiveness Tracking
+Skills can optionally track effectiveness metrics via auto-populated fields:
+  effectiveness.invocations, effectiveness.success_rate (0.0-1.0), effectiveness.last_invoked (ISO-8601)
+Read-only from skill perspective — sys-memory-keeper updates at session end via task-outcome-recorder data.
+-->
+
+## Skill Scope
+
+| Scope | Purpose | Deployed via init? |
+|-------|---------|-------------------|
+| `core` | Universal development tools | Yes |
+| `harness` | Agent/skill/rule maintenance | Yes |
+| `package` | Package-specific (npm publish, etc.) | No |
+
+Default: `core` (when field is omitted)
+
+### Context Fork Criteria
+
+Use `context: fork` for multi-agent orchestration skills only. Cap: **12 total**. Current: 12/12 (secretary/dev-lead/de-lead/qa-lead-routing, dag-orchestration, task-decomposition, worker-reviewer-pipeline, pipeline-guards, deep-plan, professor-triage, evaluator-optimizer, sauron-watch).
+
+<!-- DETAIL: Context Fork decision table
+| Use context:fork | Do NOT use context:fork |
+| Routing skills, Workflow orchestration (DAG), Multi-agent coordination, Task decomposition | Best-practices skills, Hook/command skills, Single-agent reference, External tool integrations |
+-->
+
+## Naming
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Agent file | `kebab-case.md` | `fe-vercel-agent.md` |
+| Skill dir | `kebab-case/` | `react-best-practices/` |
+| Skill file | UPPERCASE | `SKILL.md` |

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

@@ -0,0 +1,77 @@
+# [MUST] Agent Identification Rules
+
+> **Priority**: MUST | **ID**: R007
+
+## Core Rule
+
+Every response MUST start with agent identification:
+
+```
+┌─ Agent: {agent-name} ({agent-type})
+├─ Skill: {skill-name} (if applicable)
+└─ Task: {brief-task-description}
+```
+
+Default (no specific agent): `┌─ Agent: claude (default)`
+
+## Simplified Format
+
+For brief responses: `[mgr-creator] Creating agent structure...`
+With skill: `[fe-vercel-agent → react-best-practices] Analyzing...`
+
+## Routing & Skill Context
+
+When the orchestrator uses a routing skill, identification should reflect the active context:
+
+```
+┌─ Agent: claude (secretary-routing)
+├─ Skill: secretary-routing
+└─ Task: route agent management request
+```
+
+| Context | Identification |
+|---------|---------------|
+| No routing active | `claude (default)` |
+| secretary-routing | `claude (secretary-routing)` |
+| dev-lead-routing | `claude (dev-lead-routing)` |
+| de-lead-routing | `claude (de-lead-routing)` |
+| qa-lead-routing | `claude (qa-lead-routing)` |
+| Skill invocation | `claude → {skill-name}` |
+
+## Skill Invocation Format
+
+When the orchestrator invokes a skill via the Skill tool, the skill name MUST be integrated into the identification block — NOT displayed as a separate tool call.
+
+```
+┌─ Agent: claude → {skill-name}
+└─ Task: {brief-task-description}
+```
+
+### Common Violations
+
+```
+Incorrect: Skill as separate display
+   ┌─ Agent: claude (default)
+   └─ Task: research topic analysis
+
+   Skill(research)    ← separate, disconnected
+
+Correct: Skill integrated into identification
+   ┌─ Agent: claude → research
+   └─ Task: research topic analysis
+
+Correct: With sub-skill
+   ┌─ Agent: claude → research
+   ├─ Skill: result-aggregation
+   └─ Task: aggregate team findings
+```
+
+## When to Display
+
+| Situation | Display |
+|-----------|---------|
+| Agent-specific task | Full header |
+| Using skill | Include skill name |
+| General conversation | "claude (default)" |
+| Long tasks | Show progress with agent context |
+| Skill invocation | Integrated `claude → {skill-name}` format |