cc-codeconductor 0.2.9 → 0.3.0

package/presets/claude/skills/workflow-orchestration-patterns/references/details.md

@@ -0,0 +1,223 @@
+# workflow-orchestration-patterns — detailed patterns and worked examples
+
+## Critical Design Decision: Workflows vs Activities
+
+**The Fundamental Rule** (Source: temporal.io/blog/workflow-engine-principles):
+
+- **Workflows** = Orchestration logic and decision-making
+- **Activities** = External interactions (APIs, databases, network calls)
+
+### Workflows (Orchestration)
+
+**Characteristics:**
+
+- Contain business logic and coordination
+- **MUST be deterministic** (same inputs → same outputs)
+- **Cannot** perform direct external calls
+- State automatically preserved across failures
+- Can run for years despite infrastructure failures
+
+**Example workflow tasks:**
+
+- Decide which steps to execute
+- Handle compensation logic
+- Manage timeouts and retries
+- Coordinate child workflows
+
+### Activities (External Interactions)
+
+**Characteristics:**
+
+- Handle all external system interactions
+- Can be non-deterministic (API calls, DB writes)
+- Include built-in timeouts and retry logic
+- **Must be idempotent** (calling N times = calling once)
+- Short-lived (seconds to minutes typically)
+
+**Example activity tasks:**
+
+- Call payment gateway API
+- Write to database
+- Send emails or notifications
+- Query external services
+
+### Design Decision Framework
+
+```
+Does it touch external systems? → Activity
+Is it orchestration/decision logic? → Workflow
+```
+
+## Core Workflow Patterns
+
+### 1. Saga Pattern with Compensation
+
+**Purpose**: Implement distributed transactions with rollback capability
+
+**Pattern** (Source: temporal.io/blog/compensating-actions-part-of-a-complete-breakfast-with-sagas):
+
+```
+For each step:
+  1. Register compensation BEFORE executing
+  2. Execute the step (via activity)
+  3. On failure, run all compensations in reverse order (LIFO)
+```
+
+**Example: Payment Workflow**
+
+1. Reserve inventory (compensation: release inventory)
+2. Charge payment (compensation: refund payment)
+3. Fulfill order (compensation: cancel fulfillment)
+
+**Critical Requirements:**
+
+- Compensations must be idempotent
+- Register compensation BEFORE executing step
+- Run compensations in reverse order
+- Handle partial failures gracefully
+
+### 2. Entity Workflows (Actor Model)
+
+**Purpose**: Long-lived workflow representing single entity instance
+
+**Pattern** (Source: docs.temporal.io/evaluate/use-cases-design-patterns):
+
+- One workflow execution = one entity (cart, account, inventory item)
+- Workflow persists for entity lifetime
+- Receives signals for state changes
+- Supports queries for current state
+
+**Example Use Cases:**
+
+- Shopping cart (add items, checkout, expiration)
+- Bank account (deposits, withdrawals, balance checks)
+- Product inventory (stock updates, reservations)
+
+**Benefits:**
+
+- Encapsulates entity behavior
+- Guarantees consistency per entity
+- Natural event sourcing
+
+### 3. Fan-Out/Fan-In (Parallel Execution)
+
+**Purpose**: Execute multiple tasks in parallel, aggregate results
+
+**Pattern:**
+
+- Spawn child workflows or parallel activities
+- Wait for all to complete
+- Aggregate results
+- Handle partial failures
+
+**Scaling Rule** (Source: temporal.io/blog/workflow-engine-principles):
+
+- Don't scale individual workflows
+- For 1M tasks: spawn 1K child workflows × 1K tasks each
+- Keep each workflow bounded
+
+### 4. Async Callback Pattern
+
+**Purpose**: Wait for external event or human approval
+
+**Pattern:**
+
+- Workflow sends request and waits for signal
+- External system processes asynchronously
+- Sends signal to resume workflow
+- Workflow continues with response
+
+**Use Cases:**
+
+- Human approval workflows
+- Webhook callbacks
+- Long-running external processes
+
+## State Management and Determinism
+
+### Automatic State Preservation
+
+**How Temporal Works** (Source: docs.temporal.io/workflows):
+
+- Complete program state preserved automatically
+- Event History records every command and event
+- Seamless recovery from crashes
+- Applications restore pre-failure state
+
+### Determinism Constraints
+
+**Workflows Execute as State Machines**:
+
+- Replay behavior must be consistent
+- Same inputs → identical outputs every time
+
+**Prohibited in Workflows** (Source: docs.temporal.io/workflows):
+
+- ❌ Threading, locks, synchronization primitives
+- ❌ Random number generation (`random()`)
+- ❌ Global state or static variables
+- ❌ System time (`datetime.now()`)
+- ❌ Direct file I/O or network calls
+- ❌ Non-deterministic libraries
+
+**Allowed in Workflows**:
+
+- ✅ `workflow.now()` (deterministic time)
+- ✅ `workflow.random()` (deterministic random)
+- ✅ Pure functions and calculations
+- ✅ Calling activities (non-deterministic operations)
+
+### Versioning Strategies
+
+**Challenge**: Changing workflow code while old executions still running
+
+**Solutions**:
+
+1. **Versioning API**: Use `workflow.get_version()` for safe changes
+2. **New Workflow Type**: Create new workflow, route new executions to it
+3. **Backward Compatibility**: Ensure old events replay correctly
+
+## Resilience and Error Handling
+
+### Retry Policies
+
+**Default Behavior**: Temporal retries activities forever
+
+**Configure Retry**:
+
+- Initial retry interval
+- Backoff coefficient (exponential backoff)
+- Maximum interval (cap retry delay)
+- Maximum attempts (eventually fail)
+
+**Non-Retryable Errors**:
+
+- Invalid input (validation failures)
+- Business rule violations
+- Permanent failures (resource not found)
+
+### Idempotency Requirements
+
+**Why Critical** (Source: docs.temporal.io/activities):
+
+- Activities may execute multiple times
+- Network failures trigger retries
+- Duplicate execution must be safe
+
+**Implementation Strategies**:
+
+- Idempotency keys (deduplication)
+- Check-then-act with unique constraints
+- Upsert operations instead of insert
+- Track processed request IDs
+
+### Activity Heartbeats
+
+**Purpose**: Detect stalled long-running activities
+
+**Pattern**:
+
+- Activity sends periodic heartbeat
+- Includes progress information
+- Timeout if no heartbeat received
+- Enables progress-based retry

package/presets/codex/AGENTS.md

@@ -34,16 +34,17 @@ Skipping any step is not an optimization. It is a defect.
 Codex does not load custom slash commands from this preset. Use these natural
 language patterns to activate each workflow:
 
-| Workflow     | Trigger phrase                                    |
-| ------------ | ------------------------------------------------- |
-| Full feature | "Run the feature workflow for: [description]"     |
-| Bug fix      | "Run the fix workflow for: [description]"         |
-| Refactor     | "Run the refactor workflow for: [scope]"          |
-| API contract | "Run the API contract workflow for: [change]"     |
+| Workflow     | Trigger phrase                                     |
+| ------------ | -------------------------------------------------- |
+| Full feature | "Run the feature workflow for: [description]"      |
+| Bug fix      | "Run the fix workflow for: [description]"          |
+| Refactor     | "Run the refactor workflow for: [scope]"           |
+| API contract | "Run the API contract workflow for: [change]"      |
 | DB migration | "Run the database migration workflow for: [scope]" |
-| Code review  | "Run a structured review of: [target]"            |
-| Test plan    | "Create a test plan for: [scope]"                 |
-| Task intake  | "Help me define a Task Card for: [vague request]" |
+| Code review  | "Run a structured review of: [target]"             |
+| Test plan    | "Create a test plan for: [scope]"                  |
+| Task intake  | "Help me define a Task Card for: [vague request]"  |
+| PageSpeed    | "Run a PageSpeed audit for: [url]"                 |
 
 ---
 
@@ -373,15 +374,16 @@ designed. Minimal diff. No scope creep. No invented architecture.
   `npm run lint`, `uv run pytest`, `make tests`)
 - network: `deny`
 
-**Does not:** Design architecture. Force push. Declare done before running tests.
+**Does not:** Design architecture. Force push. Declare done before running
+tests.
 
 **Model:** `{{MODEL_CODEX}}`
 
 **Pre-implementation checklist:**
 
 0. Create a Git Worktree for this session before opening any file for editing:
-   `git worktree add ../<branch>-session <branch>`
-   All changes happen inside this worktree. Never modify the main working tree directly.
+   `git worktree add ../<branch>-session <branch>` All changes happen inside
+   this worktree. Never modify the main working tree directly.
 1. Read the Technical Plan completely.
 2. Read each file listed under "Files Affected."
 3. Understand existing patterns in those files.
@@ -391,7 +393,8 @@ designed. Minimal diff. No scope creep. No invented architecture.
 **Implementation rules:**
 
 - **Work in a worktree.** Create a session worktree before touching any file.
-  All edits happen inside it. Include the worktree path in the Implementation Summary.
+  All edits happen inside it. Include the worktree path in the Implementation
+  Summary.
 - **Minimal diff.** Change only what the plan specifies.
 - **Follow existing patterns.** Match naming conventions, error handling, and
   module structure already present in the codebase.
@@ -590,7 +593,8 @@ incorrectly.
 - bash: `deny`
 - network: `deny`
 
-**Does not:** Write implementation code. Document behavior that was not implemented. Omit CHANGELOG entries.
+**Does not:** Write implementation code. Document behavior that was not
+implemented. Omit CHANGELOG entries.
 
 **Model:** `{{MODEL_CODEX}}`
 
@@ -815,6 +819,13 @@ Available skills:
 | `django-testing`       | Django test patterns, tenant-aware testing          |
 | `python-fastapi-stack` | FastAPI routers, endpoints, schemas                 |
 | `sqlalchemy`           | SQLAlchemy models, sessions, Alembic migrations     |
+| `nextjs-typescript`    | Next.js components, Server Actions, App Router      |
+| `astro`                | Astro pages, islands, content collections           |
+| `android`              | Android Kotlin, Jetpack Compose, Media3 components  |
+| `laravel-specialist`   | Laravel models, routes, API resources, Livewire     |
+| `php-pro`              | PHPStan static analysis, modern PHP 8.3+ features   |
+| `security`             | Backend security, authorization, data validation    |
+| `a11y-debugging`       | Debugging frontend accessibility and web standards  |
 
 To activate a skill, include in your request:
 
@@ -827,6 +838,18 @@ or, in a combined setup:
 
 ---
 
+## Loop Agent & Monorepo Workspaces
+
+### Loop Agent Mode (Intense Workflows)
+- If tests fail during verification, route the logs back to the Implementer.
+- Run the cycle: Implementer (applies fix) -> Tester (verifies suite) up to 3 times.
+- If still failing, stop and report back with findings.
+
+### Monorepo Workspaces
+- Note that this is a monorepo. Focus operations strictly within the specified sub-package or workspace directory in the Task Card scope. Avoid modifying files or running commands outside this package directory.
+
+---
+
 ## Scorecard Format
 
 Every Deliverable should be evaluated against a Scorecard before it is accepted.
@@ -879,6 +902,7 @@ Contract version:** v0.1.0 **Date:** [YYYY-MM-DD] **Evaluator:** [human name or
 - Keep solutions simple and direct.
 - User instructions always override this file.
 - When using tools, be precise and minimal with context.
+{{LANGUAGE_INSTRUCTIONS}}
 
 ## Context Budget
 

package/presets/codex/skills/android/SKILL.md

@@ -0,0 +1,119 @@
+---
+id: android
+version: 1.0.0
+name: Android + Kotlin (Jetpack Compose & Media3)
+description: >
+  Provides expert knowledge for building modern native Android apps using Kotlin, Jetpack Compose, Material Design 3, MVI architecture, Hilt dependency injection, and Media3/ExoPlayer.
+
+user-invokable: true
+license: MIT
+metadata:
+  author: lgzarturo
+  category: mobile
+
+compatibility:
+  tools: [claude, codex, gemini, agy, opencode]
+  stacks:
+    languages: [kotlin, java]
+    frameworks: [android]
+
+risk:
+  level: medium
+  can_execute_shell: true
+  can_modify_files: true
+  requires_network: false
+
+inputs: []
+
+outputs: []
+
+quality:
+  reviewed_by: codeconductor-core
+  version: 0.1.0
+---
+
+# Android + Kotlin (Jetpack Compose & Media3)
+
+This playbook defines the architecture, UI design system, performance guidelines, and testing strategy for native Android applications.
+
+---
+
+## 1. Lead Architect & Modularization
+
+### Architecture (MVI / MVVM with Clean Architecture)
+- Prefer **MVI (Model-View-Intent)** for state management. Ensure a strict unidirectional data flow:
+  - **UiState**: Single source of truth for the UI state.
+  - **UiIntent**: Actions initiated by the user or system.
+  - **UiEffect**: One-time events (navigation, toasts, snackbars).
+- Separate the project into clean logical modules:
+  - `app`: Application entry point, launcher activity, global dependency injection configuration.
+  - `core`: Shared resources, network layer, media playback logic (ExoPlayer/Media3), storage.
+  - `feature`: Individual business features (isolated and independent of other features).
+
+### Dependency Injection (Hilt)
+- Annotate the Application class with `@HiltAndroidApp`.
+- Annotate Activities and Fragments with `@AndroidEntryPoint`.
+- Use constructor injection for ViewModels with `@HiltViewModel`.
+
+---
+
+## 2. Jetpack Compose UI/UX
+
+### Recomposition & State Management
+- Consume `StateFlow` from ViewModels safely using `collectAsStateWithLifecycle()` to respect the activity lifecycle.
+- Keep data models immutable. Mark configuration classes with `@Immutable` or `@Stable` to prevent redundant recompositions.
+- Use `contentType` and `key` in `LazyColumn` and `LazyRow` to optimize item recycling and rendering performance.
+- Avoid fixed hardcoded margins. Apply `WindowInsets` to support modern edge-to-edge screens.
+
+---
+
+## 3. Performance & Multimedia (Media3 / ExoPlayer)
+
+### Playback & Services
+- Run `ExoPlayer` / `Media3` inside a robust `Foreground Service` (using `MediaSessionService`) to ensure playback continues when the app is in the background.
+- Clean up resources: release player instances in `onDestroy` or when the service is stopped.
+- Control wake locks strictly to avoid draining the user's battery when playback is paused.
+
+### Kotlin Coroutines & Threading
+- Always inject `CoroutineDispatcher` instances instead of hardcoding them:
+  - `Dispatchers.IO`: Database access, network operations, file reading.
+  - `Dispatchers.Default`: CPU-intensive operations (parsing JSON, filtering large lists).
+  - `Dispatchers.Main`: UI modifications and light interactions.
+
+### R8 & Resource Optimization
+- Enable shrinking and obfuscation in production builds:
+  - `isMinifyEnabled = true`
+  - `isShrinkResources = true`
+- Convert all static images to the modern `WebP` format to minimize the application binary size.
+
+---
+
+## 4. Quality Assurance & Automated Testing
+
+### Unit Testing
+- Use JUnit 5 and MockK for mocking dependencies.
+- Test ViewModels and Reducers by asserting StateFlow updates. Use `Turbine` to easily test Kotlin Flows.
+- Mock all multimedia/ExoPlayer components to avoid loading actual audio/video resources in unit tests.
+
+### UI Testing
+- Create UI tests using Compose test rules: `createComposeRule()` or `createAndroidComposeRule<MainActivity>()`.
+- Assert correct rendering, visibility states, and user interactions without executing real network calls.
+
+---
+
+## 5. Key Gradle & ADB Commands
+
+Use these commands for building, checking code style, running tests, and profiling performance:
+
+| Command | Action |
+| ------- | ------ |
+| `./gradlew init` | Initialize a new Gradle project structure. |
+| `./gradlew app:dependencies` | List all dependencies of the application module. |
+| `./gradlew assembleDebug` | Validate compilation and generate debug APK. |
+| `./gradlew ktlintCheck` | Run KtLint check to enforce Kotlin style guidelines. |
+| `./gradlew lintDebug` | Run Android Lint tool to inspect code quality and UI issues. |
+| `./gradlew testDebugUnitTest` | Run unit tests for debug build variant. |
+| `./gradlew connectedAndroidTest` | Run instrumented UI tests on connected emulator or device. |
+| `./gradlew assembleRelease` | Generate release build variant with R8 optimizations. |
+| `adb shell dumpsys batterystats` | Profile system battery consumption metrics. |
+| `adb shell am dumpheap <package> heap.hprof` | Dump application heap memory file for profiling. |

package/presets/codex/skills/conductor-setup/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: conductor-setup
+description: Configure a Rails project to work with Conductor (parallel coding agents)
+allowed-tools: Bash(chmod *), Bash(bundle *), Bash(npm *), Bash(script/server)
+context: fork
+risk: unknown
+source: community
+metadata:
+  author: Shpigford
+  version: "1.0"
+---
+
+Set up this Rails project for Conductor, the Mac app for parallel coding agents.
+
+## When to Use
+- You need to configure a Rails project so it runs correctly inside Conductor workspaces.
+- The project should support parallel coding agents with isolated ports, Redis settings, and shared secrets.
+- You want the standard `conductor.json`, `bin/conductor-setup`, and `script/server` scaffolding for a Rails repo.
+
+# What to Create
+
+## 1. conductor.json (project root)
+
+Create `conductor.json` in the project root if it doesn't already exist:
+
+```json
+{
+  "scripts": {
+    "setup": "bin/conductor-setup",
+    "run": "script/server"
+  }
+}
+```
+
+## 2. bin/conductor-setup (executable)
+
+Create `bin/conductor-setup` if it doesn't already exist:
+
+```bash
+#!/bin/bash
+set -e
+
+# Symlink .env from repo root (where secrets live, outside worktrees)
+[ -f "$CONDUCTOR_ROOT_PATH/.env" ] && ln -sf "$CONDUCTOR_ROOT_PATH/.env" .env
+
+# Symlink Rails master key
+[ -f "$CONDUCTOR_ROOT_PATH/config/master.key" ] && ln -sf "$CONDUCTOR_ROOT_PATH/config/master.key" config/master.key
+
+# Install dependencies
+bundle install
+npm install
+```
+
+Make it executable with `chmod +x bin/conductor-setup`.
+
+## 3. script/server (executable)
+
+Create the `script` directory if needed, then create `script/server` if it doesn't already exist:
+
+```bash
+#!/bin/bash
+
+# === Port Configuration ===
+export PORT=${CONDUCTOR_PORT:-3000}
+export VITE_RUBY_PORT=$((PORT + 1000))
+
+# === Redis Isolation ===
+if [ -n "$CONDUCTOR_WORKSPACE_NAME" ]; then
+  HASH=$(printf '%s' "$CONDUCTOR_WORKSPACE_NAME" | cksum | cut -d' ' -f1)
+  REDIS_DB=$((HASH % 16))
+  export REDIS_URL="redis://localhost:6379/${REDIS_DB}"
+fi
+
+exec bin/dev
+```
+
+Make it executable with `chmod +x script/server`.
+
+## 4. Update Rails Config Files
+
+For each of the following files, if they exist and contain Redis configuration, update them to use `ENV.fetch('REDIS_URL', ...)` or `ENV['REDIS_URL']` with a fallback:
+
+### config/initializers/sidekiq.rb
+If this file exists and configures Redis, update it to use:
+```ruby
+redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
+```
+
+### config/cable.yml
+If this file exists, update the development adapter to use:
+```yaml
+development:
+  adapter: redis
+  url: <%= ENV.fetch('REDIS_URL', 'redis://localhost:6379/1') %>
+```
+
+### config/environments/development.rb
+If this file configures Redis for caching, update to use:
+```ruby
+config.cache_store = :redis_cache_store, { url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0') }
+```
+
+### config/initializers/rack_attack.rb
+If this file exists and configures a Redis cache store, update to use:
+```ruby
+Rack::Attack.cache.store = ActiveSupport::Cache::RedisCacheStore.new(url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0'))
+```
+
+# Implementation Notes
+
+- **Don't overwrite existing files**: Check if conductor.json, bin/conductor-setup, and script/server exist before creating them. If they exist, skip creation and inform the user.
+- **Rails config updates**: Only modify Redis-related configuration. If a file doesn't exist or doesn't use Redis, skip it gracefully.
+- **Create directories as needed**: Create `script/` directory if it doesn't exist.
+
+# Verification
+
+After creating the files:
+1. Confirm all Conductor files exist and scripts are executable
+2. Run `script/server` to verify it starts without errors
+3. Check that Rails configs properly reference `ENV['REDIS_URL']` or `ENV.fetch('REDIS_URL', ...)`
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.