oh-my-customcodex 0.1.0

package/templates/.claude/skills/springboot-best-practices/examples/repository-example.java

@@ -0,0 +1,17 @@
+package com.example.demo.repository;
+
+import com.example.demo.entity.User;
+import com.example.demo.entity.UserStatus;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+import java.util.Optional;
+
+public interface UserRepository extends JpaRepository<User, Long> {
+    Optional<User> findByEmail(String email);
+
+    @Query("SELECT u FROM User u WHERE u.status = :status")
+    List<User> findByStatus(@Param("status") UserStatus status);
+}

package/templates/.claude/skills/springboot-best-practices/examples/repository-test-example.java

@@ -0,0 +1,23 @@
+package com.example.demo.repository;
+
+import com.example.demo.entity.User;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
+
+import java.util.Optional;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+class UserRepositoryTest {
+    @Autowired
+    private UserRepository userRepository;
+
+    @Test
+    void findByEmail_shouldReturnUser() {
+        User user = userRepository.save(new User("test@example.com"));
+        Optional<User> found = userRepository.findByEmail("test@example.com");
+        assertThat(found).isPresent();
+    }
+}

package/templates/.claude/skills/springboot-best-practices/examples/security-config-example.java

@@ -0,0 +1,27 @@
+package com.example.demo.config;
+
+import lombok.RequiredArgsConstructor;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.config.http.SessionCreationPolicy;
+import org.springframework.security.web.SecurityFilterChain;
+
+@Configuration
+@EnableWebSecurity
+@RequiredArgsConstructor
+public class SecurityConfig {
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            .csrf(csrf -> csrf.disable())
+            .sessionManagement(session ->
+                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/v1/auth/**").permitAll()
+                .requestMatchers("/api/v1/admin/**").hasRole("ADMIN")
+                .anyRequest().authenticated())
+            .build();
+    }
+}

package/templates/.claude/skills/springboot-best-practices/examples/service-example.java

@@ -0,0 +1,33 @@
+package com.example.demo.service;
+
+import com.example.demo.dto.UserRequest;
+import com.example.demo.dto.UserResponse;
+import com.example.demo.entity.User;
+import com.example.demo.exception.UserNotFoundException;
+import com.example.demo.mapper.UserMapper;
+import com.example.demo.repository.UserRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+@Transactional(readOnly = true)
+@RequiredArgsConstructor
+public class UserServiceImpl implements UserService {
+    private final UserRepository userRepository;
+    private final UserMapper userMapper;
+
+    @Override
+    public UserResponse findById(Long id) {
+        User user = userRepository.findById(id)
+            .orElseThrow(() -> new UserNotFoundException(id));
+        return userMapper.toResponse(user);
+    }
+
+    @Override
+    @Transactional
+    public UserResponse create(UserRequest request) {
+        User user = userMapper.toEntity(request);
+        return userMapper.toResponse(userRepository.save(user));
+    }
+}

package/templates/.claude/skills/status/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: omcodex:status
+description: Show system status and health checks
+scope: harness
+argument-hint: "[--verbose] [--health]"
+user-invocable: true
+---
+
+# System Status Skill
+
+Show comprehensive system status including agents, skills, guides, and health checks.
+
+## Options
+
+```
+--verbose, -v    Detailed status
+--health, -h     Health checks only
+```
+
+## Output Format
+
+### Default Status
+```
+AI Agent System - Status
+
+System:
+  Rules: 10 loaded (R000-R009)
+
+Agents:
+  Orchestrator:     1 (secretary)
+  Manager:          3 (mgr-creator, mgr-updater, mgr-supplier)
+  SW Engineer:      6
+  Backend Engineer: 3
+  Infra Engineer:   2
+  Total:           15 agents
+
+Skills:
+  Development:     8
+  Backend:         3
+  Infrastructure:  2
+  Total:          13 skills
+
+Guides:            12 loaded
+Commands:          10 available
+
+Health: ✓ OK
+```
+
+### Verbose Status
+```
+status --verbose
+
+AI Agent System - Detailed Status
+
+Rules:
+  MUST:
+    ✓ R000 language-policy
+    ✓ R001 safety
+    ✓ R002 permissions
+    ✓ R006 agent-design
+
+  SHOULD:
+    ✓ R003 interaction
+    ✓ R004 error-handling
+    ✓ R007 agent-identification
+    ✓ R008 tool-identification
+
+  MAY:
+    ✓ R005 optimization
+    ✓ R009 parallel-execution
+
+Agents:
+  orchestrator/
+    ✓ secretary (internal)
+
+  manager/
+    ✓ mgr-creator (internal)
+    ✓ mgr-updater (internal)
+    ✓ mgr-supplier (internal)
+
+  sw-engineer/
+    ✓ lang-golang-expert (internal)
+    ✓ lang-python-expert (internal)
+    ✓ lang-rust-expert (internal)
+    ✓ lang-kotlin-expert (internal)
+    ✓ lang-typescript-expert (internal)
+    ✓ fe-vercel-agent (external v1.0.0)
+
+  sw-engineer/backend/
+    ✓ be-fastapi-expert (internal)
+    ✓ be-springboot-expert (internal)
+    ✓ be-go-backend-expert (internal)
+
+  infra-engineer/
+    ✓ infra-docker-expert (internal)
+    ✓ infra-aws-expert (internal)
+
+Skills:
+  development/
+    ✓ go-best-practices
+    ✓ python-best-practices
+    ✓ rust-best-practices
+    ✓ kotlin-best-practices
+    ✓ typescript-best-practices
+    ✓ react-best-practices
+    ✓ web-design-guidelines
+    ✓ vercel-deploy
+
+  backend/
+    ✓ fastapi-best-practices
+    ✓ springboot-best-practices
+    ✓ go-backend-best-practices
+
+  infrastructure/
+    ✓ docker-best-practices
+    ✓ aws-best-practices
+
+Guides:
+  ✓ claude-code, web-design
+  ✓ golang, python, rust, kotlin, typescript
+  ✓ fastapi, springboot, go-backend
+  ✓ docker, aws
+
+Commands:
+  system:    lists, status, help
+  manager:   create-agent, update-docs, update-external, audit-agents, fix-refs
+  dev:       dev-review, dev-refactor
+
+All systems operational.
+```
+
+### Health Check
+```
+status --health
+
+Health Checks:
+
+Agents:
+  ✓ 15/15 agents valid
+  ✓ All agent files exist in .codex/agents/
+
+Dependencies:
+  ✓ All skill references valid
+  ✓ All guide references valid
+
+External Sources:
+  ✓ fe-vercel-agent (github: reachable)
+
+Documentation:
+  ✓ AGENTS.md in sync
+  ✓ All .codex/agents/*.md files valid
+  ✓ All .codex/skills/*/SKILL.md files valid
+
+Result: HEALTHY
+```

package/templates/.claude/skills/structured-dev-cycle/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: structured-dev-cycle
+description: 6-stage structured development cycle with stage-based tool restrictions
+scope: core
+version: 1.0.0
+user-invocable: true
+---
+
+# Structured Development Cycle
+
+A disciplined 6-stage development cycle that enforces quality through stage-based tool restrictions. Prevents premature implementation by requiring planning and verification phases.
+
+## Background
+
+Inspired by Pi Coding Agent Workflow Extension's structured development approach. The core insight: restricting file modification tools during planning phases forces thorough analysis before code changes.
+
+## Stages
+
+| # | Stage | Allowed Tools | Blocked Tools | Purpose |
+|---|-------|---------------|---------------|---------|
+| 1 | **Plan** | Read, Glob, Grep, WebSearch, WebFetch | Write, Edit, Bash (modifying) | Define approach, analyze requirements |
+| 2 | **Verify Plan** | Read, Glob, Grep | Write, Edit, Bash | Review plan from different perspective |
+| 3 | **Implement** | All tools | None | Write code, create files |
+| 4 | **Verify Implementation** | Read, Glob, Grep, Bash (tests only) | Write, Edit | Review code, run tests |
+| 5 | **Compound** | Read, Bash (tests only) | Write, Edit | Integration testing, cross-module validation |
+| 6 | **Done** | Read | Write, Edit, Bash | Summary and documentation |
+
+### Stage Model Recommendations
+
+Following the [reasoning-sandwich](/skills/reasoning-sandwich) pattern:
+
+| Stage | Recommended Model | Rationale |
+|-------|------------------|-----------|
+| 1: Plan | opus | Architectural reasoning, requirement analysis |
+| 2: Verify Plan | opus | Edge case detection, alternative evaluation |
+| 3: Implement | sonnet | Code generation, file creation optimized |
+| 4: Verify Implementation | sonnet | Test execution, structural review |
+| 5: Compound | sonnet | Integration testing, cross-module validation |
+| 6: Done | haiku | Checklist validation, summary generation |
+
+Model selection is advisory — the orchestrator may override based on task complexity.
+
+## Stage Tracking
+
+Stage state is tracked via a marker file for hook enforcement:
+
+```bash
+# Set stage (used by orchestrator or skill)
+echo "plan" > /tmp/.codex-dev-stage
+
+# Valid stage values (all block Write/Edit except 'implement'):
+# plan, verify-plan, implement, verify-impl, compound, done
+
+# Clear stage (disable blocking)
+rm -f /tmp/.codex-dev-stage
+```
+
+A PreToolUse hook in `.codex/hooks/hooks.json` checks this marker and blocks Write/Edit tools during non-implementation stages.
+
+## Workflow
+
+### Stage 1: Plan
+```
+[Stage 1/6: Plan]
+├── Analyze requirements and constraints
+├── Read existing code for context
+├── Search for related patterns
+├── Define approach with rationale
+└── Output: Implementation plan document
+```
+
+**Exit criteria**: Clear plan with file list, approach description, and risk assessment.
+
+### Stage 2: Verify Plan
+```
+[Stage 2/6: Verify Plan]
+├── Review plan for completeness
+├── Check for missing edge cases
+├── Validate against existing patterns
+├── Consider alternative approaches
+└── Output: Plan approval or revision requests
+```
+
+**Exit criteria**: Plan verified by different perspective (ideally different model via multi-model-verification).
+
+### Stage 3: Implement
+```
+[Stage 3/6: Implement]
+├── Follow verified plan
+├── Create/modify files as specified
+├── Write tests alongside code
+├── Track deviations from plan
+└── Output: Implementation complete
+```
+
+**Codex-Exec Hybrid Option**: When entering Stage 3:
+1. Check `/tmp/.codex-env-status-*` for codex CLI availability
+2. If available AND task involves new file creation → automatically delegate scaffolding to `/codex-exec`:
+   - Display: `[Codex Hybrid] Delegating scaffolding to codex-exec...`
+   - codex-exec generates initial code (strength: fast generation)
+   - Claude expert reviews and refines codex output (strength: reasoning, quality)
+3. If unavailable → display `[Codex] Unavailable — proceeding with Claude experts directly` and proceed with standard implementation via Claude experts
+
+Suitable for codex hybrid: new files, boilerplate, test stubs, scaffolding
+Not suitable: modifying existing code, architecture-dependent changes
+
+**Exit criteria**: All planned files created/modified, tests written.
+
+### Stage 4: Verify Implementation
+```
+[Stage 4/6: Verify Implementation]
+├── Run test suite
+├── Review code quality
+├── Check for plan deviations
+├── Validate error handling
+└── Output: Verification report
+```
+
+**Exit criteria**: All tests pass, no critical issues found. If issues found, return to Stage 3.
+
+### Stage 5: Compound
+```
+[Stage 5/6: Compound]
+├── Run integration tests
+├── Cross-module validation
+├── Check for side effects
+├── Verify documentation accuracy
+└── Output: Integration report
+```
+
+**Exit criteria**: No integration issues. If issues found, return to Stage 3.
+
+### Stage 6: Done
+```
+[Stage 6/6: Done]
+├── Summarize changes made
+├── List files modified
+├── Note any deviations from plan
+├── Suggest follow-up tasks
+└── Output: Completion summary
+```
+
+## Integration
+
+### With EnterPlanMode
+Stage 1 (Plan) maps to Claude Code's `EnterPlanMode`. When the structured cycle is active:
+- EnterPlanMode triggers Stage 1
+- ExitPlanMode transitions to Stage 2 (Verify Plan), not directly to implementation
+
+### With Multi-Model Verification
+Stage 2 (Verify Plan) and Stage 4 (Verify Implementation) can invoke the `multi-model-verification` skill for comprehensive review.
+
+### With PreToolUse Hooks
+The stage marker file (`/tmp/.codex-dev-stage`) is read by a PreToolUse hook that enforces tool restrictions. This provides a safety net beyond instruction-based compliance.
+
+### With Agent Teams
+For complex tasks, Agent Teams is **preferred** when available (R018):
+- Plan: architect agent
+- Verify: reviewer agent(s) — multi-model-verification via Agent Teams
+- Implement: domain expert agent (+ codex-exec hybrid if available)
+- Compound: QA agent
+
+When Agent Teams is enabled AND task involves 3+ agents or review→fix cycles, using Agent Teams is MANDATORY per R018.
+
+## When to Use
+
+| Task Complexity | Recommended Cycle |
+|----------------|-------------------|
+| Simple fix (< 3 files) | Skip — direct implementation |
+| Medium feature (3-10 files) | Stages 1, 3, 4, 6 (skip verify plan, compound) |
+| Complex feature (10+ files) | Full 6-stage cycle |
+| Architecture change | Full 6-stage cycle with multi-model verification |
+| Security-critical code | Full 6-stage cycle (mandatory) |
+
+## Stage Transition Commands
+
+```bash
+# Orchestrator manages transitions:
+echo "plan" > /tmp/.codex-dev-stage           # Enter planning
+echo "verify-plan" > /tmp/.codex-dev-stage     # Enter plan verification
+echo "implement" > /tmp/.codex-dev-stage       # Enter implementation
+echo "verify-impl" > /tmp/.codex-dev-stage     # Enter impl verification
+echo "compound" > /tmp/.codex-dev-stage        # Enter compound testing
+echo "done" > /tmp/.codex-dev-stage            # Mark done
+rm -f /tmp/.codex-dev-stage                    # Clear (disable blocking)
+```
+
+## Limitations
+
+- **Single session**: The fixed path `/tmp/.codex-dev-stage` does not support concurrent Claude Code sessions. Running multiple sessions simultaneously may cause stage state conflicts.
+- **World-writable path**: The `/tmp/` directory is accessible to all users. For multi-user environments, consider using a user-scoped path like `/tmp/.codex-dev-stage-$(id -u)`.
+
+## Display Format
+
+```
+═══ Structured Dev Cycle ═══════════════════════════
+ [■■□□□□] Stage 2/6: Verify Plan
+ Files planned: 5 | Risks identified: 2
+═════════════════════════════════════════════════════
+```

package/templates/.claude/skills/stuck-recovery/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: stuck-recovery
+description: Detect stuck loops and advise recovery strategies
+scope: core
+user-invocable: false
+---
+
+# Stuck Recovery Skill
+
+Detects when tasks are stuck in repetitive failure loops and advises recovery strategies. **Advisory-only** — the orchestrator decides the action (R010).
+
+## Detection Signals
+
+| Signal | Pattern | Threshold |
+|--------|---------|-----------|
+| Repeated error | Same error message appears 3+ times | 3 occurrences |
+| Edit loop | Same file edited 3+ times in sequence | 3 edits |
+| Agent retry | Same agent_type fails 3+ times consecutively | 3 failures |
+| Tool loop | Same tool called 5+ times with similar input | 5 calls |
+
+## Recovery Strategies
+
+| Strategy | When | Action |
+|----------|------|--------|
+| Fresh context | Repeated same error | Suggest rephrasing the task |
+| Model escalation | Agent retry loop | Trigger model-escalation advisory |
+| Alternative approach | Edit loop detected | Suggest different file/method |
+| Human intervention | All automated strategies exhausted | Ask user for guidance |
+| Context reset | Long-running task (>30min) or context >80% | Structured handoff: save state to memory, create fresh session with task summary |
+
+## Architecture
+
+```
+PostToolUse (Edit, Write, Bash, Task) → stuck-detector.sh
+  Tracks: tool_name, file_path, error_hash, agent_type
+  Storage: /tmp/.codex-tool-history-$PPID (JSON lines, max 100)
+  Detection: sliding window pattern matching
+  Output: stderr advisory when loop detected
+```
+
+## Advisory Format
+
+```
+--- [Stuck Detection] Loop detected ---
+  Signal: {signal_type}
+  Pattern: {description}
+  Occurrences: {count}/{threshold}
+  💡 Recovery: {suggested_strategy}
+---
+```
+
+## Integration
+
+- Complements model-escalation skill (escalation is one recovery strategy)
+- Respects R010 (advisory only, orchestrator decides)
+- Uses same PPID-scoped temp file pattern as other hooks
+- Works with task-outcome-recorder.sh data when available
+
+## Context Reset Strategy
+
+For long-running tasks (>30 minutes) or when context usage exceeds 80%, context reset is preferred over compaction:
+
+1. **Save state**: Write current progress, decisions, and open items to native auto-memory
+2. **Create handoff**: Generate structured task summary with:
+   - Completed steps and their outcomes
+   - Current step and its state
+   - Remaining steps
+   - Key decisions made and their rationale
+3. **Reset**: Start fresh session with handoff document as input
+
+Context reset preserves decision quality by avoiding the information loss inherent in compaction. Based on Anthropic's finding that models experience "context anxiety" — prematurely concluding tasks due to perceived token limits.
+
+### When to Use
+
+| Condition | Strategy |
+|-----------|----------|
+| Context < 60% | Continue normally |
+| Context 60-80% | Consider `/compact` |
+| Context > 80% OR duration > 30min | Context reset recommended |
+| Repeated compaction in same session | Context reset required |

package/templates/.claude/skills/supabase-postgres-best-practices/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: supabase-postgres-best-practices
+description: PostgreSQL performance optimization guidelines from Supabase. Apply when writing SQL, designing schemas, configuring RLS, or optimizing database performance.
+scope: core
+user-invocable: false
+---
+
+## Supabase PostgreSQL Best Practices
+
+> Source: https://github.com/supabase/agent-skills
+
+### Rule Categories (Prioritized by Impact)
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Query Performance | CRITICAL | query- |
+| 2 | Connection Management | CRITICAL | conn- |
+| 3 | Security & RLS | CRITICAL | security- |
+| 4 | Schema Design | HIGH | schema- |
+| 5 | Concurrency & Locking | MEDIUM-HIGH | lock- |
+| 6 | Data Access Patterns | MEDIUM | data- |
+| 7 | Monitoring & Diagnostics | LOW-MEDIUM | monitor- |
+| 8 | Advanced Features | LOW | advanced- |
+
+### 1. Query Performance (CRITICAL)
+
+- Always add indexes for columns used in WHERE, JOIN, and ORDER BY clauses
+- Use partial indexes for filtered queries: `CREATE INDEX idx_active ON users(email) WHERE active = true`
+- Prefer `EXISTS` over `IN` for subqueries
+- Avoid `SELECT *` - specify only needed columns
+- Use `EXPLAIN ANALYZE` to verify query plans
+- Add composite indexes for multi-column queries (column order matters)
+- Use covering indexes to avoid heap lookups
+
+### 2. Connection Management (CRITICAL)
+
+- Use Supabase connection pooler (PgBouncer) for serverless/edge functions
+- Use transaction mode for short-lived queries
+- Use session mode only when needed (prepared statements, advisory locks)
+- Set appropriate pool size limits
+- Release connections promptly - avoid holding connections during external calls
+- Use connection timeouts to prevent leaks
+
+### 3. Security & RLS (CRITICAL)
+
+- Enable RLS on ALL tables exposed via Supabase API
+- Write policies using `auth.uid()` and `auth.jwt()`
+- Avoid functions marked `SECURITY DEFINER` unless necessary
+- Use `SECURITY INVOKER` as default for functions
+- Never trust client-side data - validate in policies
+- Test RLS policies with different roles
+- Use `USING` for read policies, `WITH CHECK` for write policies
+
+### 4. Schema Design (HIGH)
+
+- Use appropriate data types (e.g., `uuid` for IDs, `timestamptz` for times)
+- Add `NOT NULL` constraints where applicable
+- Use `CHECK` constraints for data validation
+- Prefer `text` over `varchar(n)` unless length limit is meaningful
+- Use partial indexes instead of filtered queries
+- Design schemas for the access patterns, not just the data model
+
+### 5. Concurrency & Locking (MEDIUM-HIGH)
+
+- Use `SELECT ... FOR UPDATE SKIP LOCKED` for queue patterns
+- Keep transactions short to minimize lock contention
+- Avoid long-running transactions during migrations
+- Use advisory locks for application-level coordination
+- Be aware of lock ordering to prevent deadlocks
+
+### 6. Data Access Patterns (MEDIUM)
+
+- Use Supabase client libraries for standard CRUD
+- Use RPC functions for complex operations
+- Implement pagination with cursor-based approach (not OFFSET)
+- Use realtime subscriptions judiciously
+- Batch operations where possible
+
+### 7. Monitoring & Diagnostics (LOW-MEDIUM)
+
+- Monitor `pg_stat_statements` for slow queries
+- Check `pg_stat_user_indexes` for unused indexes
+- Monitor connection count and pool utilization
+- Set up alerts for long-running queries
+- Review lock waits periodically
+
+### 8. Advanced Features (LOW)
+
+- Use CTEs for readable complex queries (but note CTE materialization)
+- Leverage PostgreSQL extensions (pgvector, pg_trgm, etc.)
+- Use generated columns for computed values
+- Consider table partitioning for very large tables
+- Use LISTEN/NOTIFY for event-driven patterns
+
+### References
+- Supabase Documentation: https://supabase.com/docs
+- PostgreSQL Official Docs: https://www.postgresql.org/docs/
+- Supabase Agent Skills: https://github.com/supabase/agent-skills
+
+For detailed rule files with specific examples, see templates/guides/supabase-postgres/.