cc-codeconductor 0.4.2 → 0.5.0

package/presets/cursor/commands/cc/tdd-cycle.md

@@ -0,0 +1,226 @@
+---
+description: >-
+  [cc: alias] Run a structured Red-Green-Refactor TDD cycle — write a failing
+  test first, implement the minimum code to pass it, then refactor with the
+  suite green.
+---
+
+# TDD Cycle — Red → Green → Refactor
+
+Scope: $ARGUMENTS
+
+Describe what behavior you want to implement. Include:
+
+- The function, method, or feature to implement
+- The expected behavior (inputs and outputs, or acceptance criteria)
+- Any known constraints or edge cases
+- Relevant files or modules (if known)
+
+---
+
+## Before you begin — mandatory pre-check
+
+This command enforces strict TDD discipline. The three phases are sequential and
+non-negotiable:
+
+1. **RED** — a failing test exists before any implementation code is written
+2. **GREEN** — the minimum implementation to make the test pass (no more)
+3. **REFACTOR** — clean up the code while keeping all tests green
+
+Do not write implementation code during RED. Do not refactor during GREEN.
+Mixing phases invalidates the cycle.
+
+---
+
+## Phase 1 — RED (Tester role)
+
+Invoke the `tester` subagent via the Task tool.
+
+### 1a — Scope clarification
+
+Before writing any test, confirm:
+
+- What is the unit of behavior being tested? (function, method, endpoint, domain
+  rule)
+- What are the inputs and expected outputs?
+- What are the failure cases?
+
+If the scope is ambiguous, ask one clarifying question and wait for the answer.
+
+### 1b — Write the failing test
+
+Write a test that:
+
+- Targets exactly the behavior described in the scope
+- Fails for the right reason (not a compile error, not a missing dependency —
+  the logic does not exist yet)
+- Has a name that describes the behavior: `given_X_when_Y_then_Z` or equivalent
+  in the project's test naming convention
+- Covers at minimum: one happy path, one edge case, one failure case
+
+Do not write the implementation. Do not make the test pass by any means other
+than the implementation that will follow in Phase 2.
+
+### 1c — Run the test suite and confirm RED
+
+Run the test suite. The new test must fail. Existing tests must pass.
+
+If the new test passes without implementation, the test is wrong. Fix the test
+before continuing.
+
+**RED Phase Report:**
+
+```
+## RED Phase Report
+
+**Test file**: [path/to/test/file]
+**Tests written**:
+- [test name] — [what it verifies]
+
+**Suite result**: [X passing, Y failing]
+**New test status**: FAIL ✓
+**Failure reason**: [quoted error or assertion message]
+**Existing tests**: [all passing | N failing — list]
+```
+
+**STOP. Show the RED Phase Report. Do not proceed to GREEN without
+confirmation.**
+
+---
+
+## Phase 2 — GREEN (Implementer role)
+
+Invoke the `implementer` subagent via the Task tool.
+
+### 2a — Read the failing test before writing any code
+
+Understand exactly what the test asserts. Write only the code that satisfies
+that assertion. Nothing more.
+
+### 2b — Implement the minimum
+
+Rules for GREEN phase:
+
+- Write the smallest amount of code that makes the failing test pass
+- Do not add features not tested
+- Do not clean up or restructure existing code — that is Refactor's job
+- Do not add new tests — that is another RED cycle
+- Hardcoding a return value is acceptable if it makes the test pass (the
+  Refactor phase will generalize it)
+
+### 2c — Run the test suite and confirm GREEN
+
+Run the test suite. The new test must pass. All previously passing tests must
+still pass.
+
+If any previously passing test now fails, you introduced a regression. Fix it
+before continuing.
+
+**GREEN Phase Report:**
+
+```
+## GREEN Phase Report
+
+**Files changed**:
+- [path/to/file] — [what was added, one sentence]
+
+**Implementation approach**: [one sentence — what the code does]
+**Suite result**: [X passing, Y failing]
+**New test status**: PASS ✓
+**Regressions**: [none | list failing tests]
+```
+
+**STOP. Show the GREEN Phase Report. Do not proceed to REFACTOR without
+confirmation.**
+
+---
+
+## Phase 3 — REFACTOR (Implementer role, then Reviewer role)
+
+Invoke the `implementer` subagent via the Task tool.
+
+### 3a — Assess what needs cleaning
+
+Before touching any code, identify:
+
+- Duplication introduced during GREEN
+- Names that do not clearly express intent
+- Abstractions that belong in a separate function or module
+- Logic that is hardcoded and should be generalized
+
+Do not invent improvements. Only address what is directly in the implementation
+written in Phase 2.
+
+### 3b — Refactor
+
+Rules for REFACTOR phase:
+
+- All tests must remain GREEN throughout — run the suite after each change
+- Do not add new behavior
+- Do not add new tests (if you discover untested behavior, note it for a new RED
+  cycle)
+- Do not change function signatures unless the original was clearly wrong
+
+### 3c — Run the test suite and confirm GREEN after refactor
+
+The full suite must pass. If any test fails during refactor, undo the last
+change and investigate.
+
+### 3d — Review (Reviewer role)
+
+Invoke the `reviewer` subagent via the Task tool.
+
+Review only the refactored code against these axes:
+
+| Axis          | What to check                                                   |
+| ------------- | --------------------------------------------------------------- |
+| Scope         | Did the refactor change any behavior?                           |
+| Correctness   | Does the logic still satisfy the original test intent?          |
+| Architecture  | Does the code follow existing project patterns?                 |
+| Test coverage | Are all written tests still meaningful (not trivially passing)? |
+
+Produce a Review Report. CRITICAL findings block completion.
+
+**REFACTOR Phase Report:**
+
+```
+## REFACTOR Phase Report
+
+**Changes made**:
+- [path/to/file] — [what was cleaned up]
+
+**Suite result**: [X passing, Y failing]
+**Behavioral changes**: none (refactor only)
+
+### Review findings
+**CRITICAL**: (none) | [list]
+**WARNING**: (none) | [list]
+**SUGGESTION**: (none) | [list]
+
+**Verdict**: approved | approved with warnings | blocked
+```
+
+---
+
+## Completion
+
+The TDD cycle is complete when:
+
+- RED: at least one failing test was written and confirmed failing
+- GREEN: the minimum implementation makes the test pass
+- REFACTOR: the code is clean, all tests pass, no CRITICAL review findings
+
+**Final Summary:**
+
+```
+## TDD Cycle Summary
+
+**Behavior implemented**: [one sentence]
+**Tests written**: [count] — [list test names]
+**Files changed**: [list]
+**Suite result**: [X passing, Y failing]
+**Cycle status**: complete | blocked (reason)
+```
+
+If the behavior requires additional test cases, start a new `/tdd-cycle` with
+the next scenario. One cycle = one behavior.

package/presets/cursor/commands/cc/test-plan.md

@@ -0,0 +1,138 @@
+---
+description: >-
+  [cc: alias] Generate a structured test plan for a feature or module — covers
+  unit, integration, contract, and edge cases without writing implementation code.
+---
+
+# Test Plan Workflow
+
+Scope: $ARGUMENTS
+
+Specify what to plan tests for. Examples:
+
+- A feature name: `user authentication`
+- A module or file path: `src/orders/OrderService.kt`
+- A Task Card title: `Add paginated product listing endpoint`
+- A PR or branch: `feature/payment-retry`
+
+If $ARGUMENTS is empty, describe the scope in your next message before
+proceeding.
+
+---
+
+## Step 1 — Scope confirmation
+
+Before generating the test plan, confirm the scope is well-defined.
+
+A valid scope includes:
+
+- The behavior or module under test
+- The acceptance criteria or expected behavior (from the Task Card if available)
+- Known edge cases or failure modes
+
+If the scope is vague (e.g., "test the whole service"), ask one clarifying
+question and wait for the answer.
+
+---
+
+## Step 2 — Test plan generation (Tester role, planning mode)
+
+Invoke the `tester` subagent via the Task tool.
+
+Produce a test plan document — not test code. The plan will be used as input
+when tests are actually written.
+
+Cover the following layers:
+
+**Unit tests**
+
+- Individual functions or methods in isolation
+- One test per behavior, not per method
+- Input/output contracts, null handling, type coercion
+
+**Integration tests**
+
+- Interactions between two or more components
+- Database read/write cycles (if applicable)
+- External service boundaries (mocked or stubbed)
+
+**Contract tests**
+
+- API endpoint contracts: request shape, response shape, status codes
+- Event schema contracts (if event-driven components are in scope)
+
+**Edge cases**
+
+- Empty inputs, boundary values, max/min limits
+- Concurrent access (if shared state is involved)
+- Failure paths: what happens when a dependency is unavailable
+
+**Regression cases**
+
+- Known past bugs that must not recur (include reference if available)
+
+---
+
+## Step 3 — Test Plan format
+
+Produce the plan in this format:
+
+```markdown
+## Test Plan — [Scope Name]
+
+### Scope
+[What is being tested and why]
+
+### Unit Tests
+| Test ID | Target | Scenario | Expected Result |
+| ------- | ------ | -------- | --------------- |
+| U-001   | ...    | ...      | ...             |
+
+### Integration Tests
+| Test ID | Components | Scenario | Expected Result |
+| ------- | ---------- | -------- | --------------- |
+| I-001   | ...        | ...      | ...             |
+
+### Contract Tests
+| Test ID | Endpoint/Event | Property | Expected Value |
+| ------- | -------------- | -------- | -------------- |
+| C-001   | ...            | ...      | ...            |
+
+### Edge Cases
+| Test ID | Input/Condition | Expected Behavior |
+| ------- | --------------- | ----------------- |
+| E-001   | ...             | ...               |
+
+### Regression Cases
+| Test ID | Reference | Scenario | Must Not Happen |
+| ------- | --------- | -------- | --------------- |
+| R-001   | ...       | ...      | ...             |
+
+### Coverage Targets
+- Minimum unit coverage: [% or "all acceptance criteria covered"]
+- Integration scenarios: [count]
+- Contract validations: [count]
+
+### Out of Scope
+[What this test plan explicitly does not cover and why]
+```
+
+---
+
+## Step 4 — Human review
+
+Show the Test Plan before any tests are written. The Test Plan is an artifact
+for review and approval.
+
+Writing test code is a separate action — run `/feature` or add a test task to
+implement from this plan.
+
+---
+
+## Completion
+
+Deliver the complete Test Plan document. Save it as
+`docs/test-plans/[scope-slug].md` if requested.
+
+This command produces a plan, not test files. No production code and no test
+code is written during this command.

package/presets/cursor/rules/behavioral-discipline.mdc

@@ -0,0 +1,14 @@
+---
+description: Behavioral discipline for all code changes — think before coding, simplicity first, surgical changes, goal-driven execution.
+globs: "**/*"
+alwaysApply: false
+---
+
+# Behavioral Discipline
+
+1. **Think Before Coding** — State assumptions explicitly. If uncertain, ask.
+2. **Simplicity First** — Minimum code that solves the problem. No speculative abstractions.
+3. **Surgical Changes** — Touch only what you must. Match existing style.
+4. **Goal-Driven Execution** — Define verifiable success criteria. Loop until verified.
+
+See @AGENTS.md for full routing policy and agent contracts.

package/presets/cursor/rules/context-budget.mdc

@@ -0,0 +1,12 @@
+---
+description: Context budget and token optimization — use when conversation is long or switching tasks.
+alwaysApply: false
+---
+
+# Context Budget
+
+- Execute `/clear` when switching to an unrelated task type.
+- Use `/summarize` or `/compress` before re-delegating with large context.
+- Delegate verbose exploration to background subagents (`repo-explorer`).
+- Prefer `@filename` references over pasting full file contents.
+- Respect `.cursorignore` — do not read excluded paths unless explicitly required.

package/presets/cursor/rules/orchestration.mdc

@@ -0,0 +1,12 @@
+---
+description: Cursor subagent orchestration patterns — multitask, parallel delegation, model tiers.
+alwaysApply: false
+---
+
+# Orchestration Patterns
+
+- Use `/multitask` for independent parallel steps (review + docs).
+- Invoke subagents via Task tool: `orchestrator`, `architect`, `implementer`, `tester`, `reviewer`, `security-reviewer`, `complexity-auditor`, `docs`, `task-coach`, `repo-explorer`.
+- High-risk routes: `architect` → `implementer` → `tester` → `security-reviewer` → `reviewer`.
+- Run `repo-explorer` as background subagent for codebase mapping.
+- See `.cursor/agents/orchestrator.md` for full routing table.

package/presets/cursor/rules/yagni-stdlib.mdc

@@ -0,0 +1,11 @@
+---
+description: YAGNI and stdlib-first constraints for source code changes.
+globs: "src/**"
+alwaysApply: false
+---
+
+# YAGNI and Stdlib-First
+
+- Do not build features or abstractions not explicitly requested.
+- Prefer the language standard library over third-party packages.
+- Every line must solve a problem that exists now.

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

@@ -0,0 +1,122 @@
+---
+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
+paths:
+  - "**/*.kt"
+  - "**/AndroidManifest.xml"
+---
+
+# 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. |