cc-codeconductor 0.2.9 → 0.3.0

package/presets/codex/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/opencode/README.md

@@ -46,16 +46,16 @@ providers)** models.
 
 ## Agent Modes
 
-| Agent             | Mode      | Description                                          |
-| ----------------- | --------- | ---------------------------------------------------- |
-| **Orchestrator**  | primary   | Main coordinator — Tab to switch to it               |
-| **Architect**     | subagent  | Invoked by Orchestrator for design work              |
-| **Implementer**   | subagent  | Invoked by Orchestrator for code implementation      |
-| **Tester**        | subagent  | Invoked by Orchestrator for test generation          |
-| **Reviewer**      | subagent  | Invoked by Orchestrator for code review              |
-| **Task Coach**    | subagent  | Invoked by Orchestrator for intake clarification     |
-| **Docs**          | subagent  | Invoked by Orchestrator for documentation updates    |
-| **Repo Explorer** | subagent  | Invoked by Orchestrator for codebase exploration     |
+| Agent             | Mode     | Description                                       |
+| ----------------- | -------- | ------------------------------------------------- |
+| **Orchestrator**  | primary  | Main coordinator — Tab to switch to it            |
+| **Architect**     | subagent | Invoked by Orchestrator for design work           |
+| **Implementer**   | subagent | Invoked by Orchestrator for code implementation   |
+| **Tester**        | subagent | Invoked by Orchestrator for test generation       |
+| **Reviewer**      | subagent | Invoked by Orchestrator for code review           |
+| **Task Coach**    | subagent | Invoked by Orchestrator for intake clarification  |
+| **Docs**          | subagent | Invoked by Orchestrator for documentation updates |
+| **Repo Explorer** | subagent | Invoked by Orchestrator for codebase exploration  |
 
 ---
 
@@ -183,6 +183,7 @@ export KIMI_API_KEY="your-key"
 - 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/opencode/agents/orchestrator.md

@@ -142,6 +142,102 @@ signals in order of priority:
 | `[tool.pytest.ini_options]` in `pyproject.toml` | pytest configured    |
 | `django-tenants` in deps                        | Multi-tenant Django  |
 | `build.gradle.kts` + `org.springframework.boot` | Spring Boot + Kotlin |
+| `next.config.js` / `next.config.mjs` / `next.config.ts` | Next.js              |
+| `requirements.txt` / `pyproject.toml` with `fastapi` | FastAPI              |
+| `pnpm-workspace.yaml` / `go.work`               | Monorepo Workspace   |
+| `go.mod` / `Cargo.toml` without django/fastapi   | Generic Backend      |
+| `index.html` / react/vue dependencies           | Generic Frontend     |
+| `AndroidManifest.xml` present                  | Android              |
+| `artisan` present                              | Laravel              |
+| `composer.json` or `*.php` present             | PHP                  |
+
+### Next.js
+
+When a Next.js project is detected, include the following skill invocation
+instruction in the delegation message for each agent:
+
+| Delegated agent | Instruction to include in delegation                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `architect`     | "Invoke the `nextjs-typescript` skill before designing."                                                                 |
+| `implementer`   | "Invoke `nextjs-typescript` before writing any code."                                                                    |
+| `tester`        | "Invoke `testing-tdd` and write Next.js unit and integration tests (using Vitest or Playwright)."                        |
+| `reviewer`      | "Invoke the `nextjs-typescript` skill to check component boundaries (RSC vs RCC) and validation rules."                  |
+
+### FastAPI
+
+When a FastAPI project is detected, include the following skill invocation
+instruction in the delegation message for each agent:
+
+| Delegated agent | Instruction to include in delegation                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `architect`     | "Invoke the `python-fastapi-stack` and `sqlalchemy` skills before designing."                                            |
+| `implementer`   | "Invoke `python-fastapi-stack` and `sqlalchemy` before writing any code."                                                |
+| `tester`        | "Invoke Python testing guidelines to write FastAPI endpoint contract tests."                                             |
+| `reviewer`      | "Invoke `python` to verify FastAPI routers and SQLAlchemy async patterns."                                               |
+
+### Generic Backend
+
+When a generic backend project is detected, include the following skill invocation
+instruction in the delegation message for each agent:
+
+| Delegated agent | Instruction to include in delegation                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `architect`     | "Invoke the `security` skill to review backend boundaries, authentication schemes, and data validation rules."           |
+| `implementer`   | "Invoke `security` to ensure inputs are validated, parameterized queries are used, and secrets are not exposed."         |
+| `reviewer`      | "Invoke `security` to check for injection vulnerabilities, resource leaks, and lack of authorization checks."            |
+
+### Android
+
+When an Android project is detected, include the following skill invocation instruction in the delegation message for each agent:
+
+| Delegated agent | Instruction to include in delegation                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `architect`     | "Invoke the `android` skill before designing."                                                                           |
+| `implementer`   | "Invoke `android` before writing any code."                                                                              |
+| `tester`        | "Invoke the `android` skill to write unit or instrumentation tests (JUnit 5, MockK, Espresso, Compose UI Testing)."      |
+| `reviewer`      | "Invoke the `android` skill to verify Jetpack Compose components stability, ExoPlayer resource cleanup, and Kotlin Coroutines/Flows dispatchers." |
+
+### Laravel
+
+When a Laravel project is detected, include the following skill invocation instruction in the delegation message for each agent:
+
+| Delegated agent | Instruction to include in delegation                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `architect`     | "Invoke the `laravel-specialist` and `php-pro` skills before designing."                                                 |
+| `implementer`   | "Invoke `laravel-specialist` and `php-pro` before writing any code."                                                     |
+| `tester`        | "Invoke the `laravel-specialist` skill to write Pest/PHPUnit tests for Laravel features."                                |
+| `reviewer`      | "Invoke the `laravel-specialist` skill to verify Eloquent queries, Sanctum authentication, and Livewire components."     |
+
+### PHP
+
+When a PHP project is detected, include the following skill invocation instruction in the delegation message for each agent:
+
+| Delegated agent | Instruction to include in delegation                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `architect`     | "Invoke the `php-pro` skill before designing."                                                                           |
+| `implementer`   | "Invoke `php-pro` before writing any code."                                                                              |
+| `tester`        | "Invoke PHP testing and quality assurance guidelines in the `php-pro` skill."                                            |
+| `reviewer`      | "Invoke the `php-pro` skill to analyze strict typing, PHPStan level 9 violations, and PSR standards."                    |
+
+### Generic Frontend
+
+When a generic frontend project is detected, include the following skill invocation
+instruction in the delegation message for each agent:
+
+| Delegated agent | Instruction to include in delegation                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `architect`     | "Invoke the `security` skill and accessibility guidelines to plan keyboard navigation and semantic HTML structures."     |
+| `implementer`   | "Invoke `modern-web-guidance` and accessibility rules to implement semantically clean and keyboard-accessible UI."       |
+| `tester`        | "Invoke `a11y-debugging` to verify focus handling, tab order, and screen reader labels."                                 |
+| `reviewer`      | "Verify compliance with frontend security standards and web accessibility guidelines."                                    |
+
+### Monorepo Workspaces
+
+When a monorepo workspace signal is present, include this instruction for ALL agents:
+
+> "This is a monorepo. Focus all file reads, edits, and commands strictly within
+> the sub-package or workspace directory specified in the Task Card scope. Avoid
+> modifying files or running commands outside this package's directory."
 
 ### Python / Django / PostgreSQL
 
@@ -155,7 +251,7 @@ instruction in the delegation message for each agent:
 | `tester`        | "Invoke `django-testing` before writing any test. The project uses multi-tenant PostgreSQL — do not use `TestCase` for tenant app models."              |
 | `reviewer`      | "Invoke `python` to check clean code conventions before reviewing."                                                                                     |
 
-**TDD gate for medium and high risk Python tasks:**
+**TDD gate for medium and high risk Python/Backend tasks:**
 
 For tasks classified medium or high, modify the agent sequence to enforce
 test-first development:
@@ -176,6 +272,30 @@ Include this instruction in the `implementer` delegation:
 
 ---
 
+## Intense Workflow — Loop Agent Mode
+
+For high-complexity tasks, or when verification tests fail, the orchestrator
+routes the agents through an iterative feedback loop:
+
+1. **Cycle**: Implementer -> Tester -> Orchestrator validation.
+2. If the `tester` reports failing tests:
+   - Route back to `implementer` with the specific test failures.
+   - Instruct the implementer to make target adjustments to resolve the failures.
+3. This cycle repeats up to 3 times. If tests are still failing after the 3rd iteration, escalate to the human with a full diagnostics summary.
+
+---
+
+## Multi-Team / Teammate Delegation
+
+When the preset target supports multi-team execution (e.g. Claude Code with
+`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` enabled):
+1. Spawn parallel teammates (`tester`, `reviewer`, etc.) to run verification and checks concurrently when possible.
+2. Assign the most cost-efficient models for secondary roles:
+   - Primary Orchestrator / Architect: `sonnet` / `pro` (maximum context / reasoning).
+   - Task Coach, Docs, Repo Explorer, Reviewer: `haiku` / `flash` (fast, cost-effective).
+
+---
+
 ## Routing documentation
 
 Every routing decision must be documented in this format before the first agent

package/presets/opencode/agents/reviewer.md

@@ -123,6 +123,37 @@ _(none)_ — if no suggestions
 - **approved with warnings** — no CRITICAL, at least one WARNING
 - **approved** — no CRITICAL, no WARNING (suggestions do not block)
 
+## Stricter Stack-Specific Checklist
+
+Apply these detailed checks based on the detected stack:
+
+### Next.js
+- [ ] RSC vs RCC boundary: Client directives (`"use client"`) are only placed on interactive leaf node files, not on static layouts/pages.
+- [ ] Server Actions input: Every Server Action validates `FormData` or arguments using a schema library (like Zod) before performing mutations. No raw data is trusted.
+- [ ] Browser APIs: Window, document, and localStorage access are guarded (e.g. `typeof window !== 'undefined'`) or only run inside `useEffect`.
+
+### FastAPI
+- [ ] Request Typing: All endpoints use typed Pydantic models (v2) for request bodies and path/query parameters.
+- [ ] Dependency Injection: Middleware, databases, and services are injected cleanly using FastAPI `Depends`.
+
+### Generic Backend
+- [ ] No SQL Injection: Database queries use parameterized placeholders or proper ORM queries; string concatenation or template literals for SQL are block-worthy.
+- [ ] Resource management: Connections, files, sockets, and sessions are closed explicitly or via context managers (e.g. `with` block).
+
+### Generic Frontend
+- [ ] Keyboard accessibility: All interactive elements are focusable (using `button`, `a`, or explicit `tabindex="0"`) and react to both click and keydown (Enter/Space) events.
+- [ ] ARIA & alt text: All images have descriptive `alt` attributes. Form fields have corresponding `<label>` or `aria-label` tags.
+- [ ] Semantic HTML: Page structures use semantic landmarks (`<main>`, `<header>`, `<footer>`, `<nav>`, `<article>`, `<section>`).
+
+### Android
+- [ ] Jetpack Compose Stability: Ensure all custom state model classes passed to Composables are immutable (annotated with `@Immutable` or `@Stable`) to prevent unnecessary recompositions.
+- [ ] ExoPlayer / Media3 Resource Management: Verify that ExoPlayer or Media3 player instances are properly cleaned up and released (e.g. in `onDestroy` or when the service is stopped) to prevent resource/memory leaks.
+- [ ] Coroutine Dispatchers: Ensure Coroutines are launched using injected dispatchers rather than hardcoding `Dispatchers.IO` or `Dispatchers.Default` directly in ViewModels or domain/data service classes.
+- [ ] Battery & Wake Locks: Verify that Wake Locks are managed carefully and released when playback is paused or stopped to prevent draining the user's battery.
+
+### Monorepo Workspaces
+- [ ] Workspace boundary: No relative imports escape a workspace package root to reference another package's files directly. Inter-package imports must resolve through configured workspace dependencies.
+
 ## What You Never Do
 
 - Edit any file — source, test, documentation, or configuration

package/presets/opencode/commands/cc-pagespeed.md

@@ -0,0 +1,100 @@
+---
+description: >-
+  Run the PageSpeed performance audit — 80/20 analysis of Core Web Vitals using
+  the PageSpeed Insights API.
+---
+
+# PageSpeed Performance Audit
+
+Audit URL: $ARGUMENTS
+
+---
+
+## Step 1 — Pre-flight (pagespeed-perf skill)
+
+Invoke `pagespeed-perf` skill.
+
+Read `PAGESPEED_API_KEY` from the environment. Compute the output filename:
+`{YYYY-MM-DD}_pagespeed-{hostname}-claude.md`.
+
+Log whether the API key was found. Proceed regardless — lab data is available
+without a key, but CrUX field data requires it.
+
+---
+
+## Step 2 — Collect
+
+Call the PageSpeed Insights API for the URL provided above.
+
+- Strategy: `both` (mobile + desktop) unless the user specified otherwise.
+- If Bun is available, use `~/.claude/skills/pagespeed-perf/scripts/run.ts`.
+- If Bun is unavailable, call PSI directly via WebFetch and fetch the HTML
+  source for manual resource-hint analysis.
+
+---
+
+## Step 3 — Analyze
+
+Extract from the PSI response:
+
+- Core Web Vitals: LCP, INP, CLS, FCP, TBT, TTFB
+- LCP element (type, selector, HTML snippet)
+- Third-party scripts ordered by blocking time
+- Render-blocking resources
+- Unused JavaScript and CSS (savings in bytes and ms)
+
+From the HTML source:
+
+- Resource hints (`<link rel="preload|preconnect|prefetch">`)
+- Images: lazy loading, `fetchpriority`, format, dimensions
+- Fonts: `font-display`, preloaded subsets
+- Blocking scripts in `<head>` (no `async`/`defer`)
+
+---
+
+## Step 4 — Prioritize
+
+Score each identified optimization using the 80/20 matrix:
+`Score = Impact × Ease` (each 1–5, max 25).
+
+Order findings by descending score. Mark optimizations with Score ≥ 20 as
+**Critical 20%**.
+
+---
+
+## Step 5 — Report
+
+Write the full performance report to
+`{YYYY-MM-DD}_pagespeed-{hostname}-claude.md` in the current directory.
+
+Required sections:
+1. Resumen Ejecutivo (2–3 paragraphs)
+2. Métricas Actuales (lab vs field table)
+3. Recursos con Mayor Impacto
+4. Plan de Acción Priorizado (80/20 table)
+5. Solución Técnica Detallada (per finding: problem, evidence, code, expected gain)
+6. Quick Wins / High Impact Changes / Roadmap
+
+End every report with:
+```
+---
+*Informe generado el {YYYY-MM-DD} · Herramienta: Claude Code + pagespeed-perf skill*
+*API Key usada: {Sí / No} · Datos CrUX: {Disponibles / No disponibles}*
+```
+
+---
+
+## Requirements
+
+**`PAGESPEED_API_KEY`** — Optional but strongly recommended.
+
+- With key: real CrUX field data + 25,000 requests/day quota.
+- Without key: lab data only (Lighthouse); shared rate limit applies.
+
+Set in your shell:
+```powershell
+$env:PAGESPEED_API_KEY = "your-api-key"   # Windows PowerShell
+export PAGESPEED_API_KEY="your-api-key"    # macOS / Linux
+```
+
+Get a free key: <https://developers.google.com/speed/docs/insights/v5/get-started>