cc-codeconductor 0.2.10 → 0.3.1

package/presets/claude/skills/php-pro/references/testing-quality.md

@@ -0,0 +1,466 @@
+# Testing & Quality Assurance
+
+## PHPUnit with Strict Types
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Service;
+
+use App\Repository\UserRepositoryInterface;
+use App\Service\UserService;
+use App\Service\EmailService;
+use PHPUnit\Framework\TestCase;
+use PHPUnit\Framework\MockObject\MockObject;
+
+final class UserServiceTest extends TestCase
+{
+    private UserRepositoryInterface&MockObject $userRepository;
+    private EmailService&MockObject $emailService;
+    private UserService $userService;
+
+    protected function setUp(): void
+    {
+        $this->userRepository = $this->createMock(UserRepositoryInterface::class);
+        $this->emailService = $this->createMock(EmailService::class);
+        $this->userService = new UserService(
+            $this->userRepository,
+            $this->emailService
+        );
+    }
+
+    public function testCreateUserSuccessfully(): void
+    {
+        $email = 'test@example.com';
+        $password = 'SecurePass123!';
+
+        $this->userRepository
+            ->expects($this->once())
+            ->method('findByEmail')
+            ->with($email)
+            ->willReturn(null);
+
+        $this->userRepository
+            ->expects($this->once())
+            ->method('create')
+            ->willReturn($this->createUser($email));
+
+        $this->emailService
+            ->expects($this->once())
+            ->method('sendWelcomeEmail');
+
+        $user = $this->userService->createUser($email, $password);
+
+        $this->assertSame($email, $user->email);
+    }
+
+    public function testCreateUserThrowsExceptionWhenEmailExists(): void
+    {
+        $this->expectException(\DomainException::class);
+        $this->expectExceptionMessage('Email already exists');
+
+        $this->userRepository
+            ->method('findByEmail')
+            ->willReturn($this->createUser('test@example.com'));
+
+        $this->userService->createUser('test@example.com', 'password');
+    }
+
+    private function createUser(string $email): User
+    {
+        return new User(
+            id: 1,
+            email: $email,
+            password: password_hash('password', PASSWORD_ARGON2ID),
+        );
+    }
+}
+```
+
+## Data Providers
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Validator;
+
+use App\Validator\EmailValidator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class EmailValidatorTest extends TestCase
+{
+    #[Test]
+    #[DataProvider('validEmailProvider')]
+    public function itValidatesCorrectEmails(string $email): void
+    {
+        $validator = new EmailValidator();
+        $this->assertTrue($validator->isValid($email));
+    }
+
+    #[Test]
+    #[DataProvider('invalidEmailProvider')]
+    public function itRejectsInvalidEmails(string $email): void
+    {
+        $validator = new EmailValidator();
+        $this->assertFalse($validator->isValid($email));
+    }
+
+    public static function validEmailProvider(): array
+    {
+        return [
+            ['user@example.com'],
+            ['john.doe@company.co.uk'],
+            ['test+filter@domain.org'],
+        ];
+    }
+
+    public static function invalidEmailProvider(): array
+    {
+        return [
+            ['invalid'],
+            ['@example.com'],
+            ['user@'],
+            ['user space@example.com'],
+        ];
+    }
+}
+```
+
+## Laravel Feature Tests
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature;
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Foundation\Testing\WithFaker;
+use Tests\TestCase;
+
+final class UserControllerTest extends TestCase
+{
+    use RefreshDatabase, WithFaker;
+
+    public function testUserCanViewTheirProfile(): void
+    {
+        $user = User::factory()->create();
+
+        $response = $this->actingAs($user)->get('/api/users/me');
+
+        $response->assertOk()
+            ->assertJson([
+                'data' => [
+                    'id' => $user->id,
+                    'email' => $user->email,
+                ],
+            ]);
+    }
+
+    public function testUserCanUpdateTheirProfile(): void
+    {
+        $user = User::factory()->create();
+        $newName = $this->faker->name();
+
+        $response = $this->actingAs($user)->putJson('/api/users/me', [
+            'name' => $newName,
+        ]);
+
+        $response->assertOk();
+
+        $this->assertDatabaseHas('users', [
+            'id' => $user->id,
+            'name' => $newName,
+        ]);
+    }
+
+    public function testUnauthorizedUserCannotAccessProfile(): void
+    {
+        $response = $this->getJson('/api/users/me');
+
+        $response->assertUnauthorized();
+    }
+
+    public function testValidationFailsWithInvalidData(): void
+    {
+        $user = User::factory()->create();
+
+        $response = $this->actingAs($user)->putJson('/api/users/me', [
+            'email' => 'not-an-email',
+        ]);
+
+        $response->assertUnprocessable()
+            ->assertJsonValidationErrors(['email']);
+    }
+}
+```
+
+## Pest Testing (Modern Alternative)
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use App\Models\User;
+use App\Services\UserService;
+
+beforeEach(function () {
+    $this->userService = app(UserService::class);
+});
+
+it('creates a user successfully', function () {
+    $user = $this->userService->createUser(
+        email: 'test@example.com',
+        password: 'SecurePass123!'
+    );
+
+    expect($user)
+        ->toBeInstanceOf(User::class)
+        ->email->toBe('test@example.com');
+});
+
+it('validates email format', function (string $email, bool $valid) {
+    $validator = new EmailValidator();
+
+    expect($validator->isValid($email))->toBe($valid);
+})->with([
+    ['test@example.com', true],
+    ['invalid', false],
+    ['@example.com', false],
+]);
+
+test('authenticated user can view profile', function () {
+    $user = User::factory()->create();
+
+    $this->actingAs($user)
+        ->get('/api/users/me')
+        ->assertOk()
+        ->assertJson(['data' => ['email' => $user->email]]);
+});
+
+test('guest cannot access protected routes', function () {
+    $this->getJson('/api/users/me')
+        ->assertUnauthorized();
+});
+```
+
+## PHPStan Configuration
+
+```neon
+# phpstan.neon
+parameters:
+    level: 9
+    paths:
+        - src
+        - tests
+    excludePaths:
+        - src/bootstrap.php
+        - vendor
+    checkMissingIterableValueType: true
+    checkGenericClassInNonGenericObjectType: true
+    reportUnmatchedIgnoredErrors: true
+    tmpDir: var/cache/phpstan
+
+    ignoreErrors:
+        # Ignore specific Laravel magic
+        - '#Call to an undefined method Illuminate\\Database\\Eloquent\\Builder#'
+
+    type_coverage:
+        return_type: 100
+        param_type: 100
+        property_type: 100
+
+includes:
+    - vendor/phpstan/phpstan-strict-rules/rules.neon
+    - vendor/phpstan/phpstan-deprecation-rules/rules.neon
+```
+
+## PHPStan Annotations
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Repository;
+
+use App\Entity\User;
+use Doctrine\ORM\EntityRepository;
+
+/**
+ * @extends EntityRepository<User>
+ */
+final class UserRepository extends EntityRepository
+{
+    /**
+     * @return User[]
+     */
+    public function findActive(): array
+    {
+        return $this->createQueryBuilder('u')
+            ->where('u.status = :status')
+            ->setParameter('status', 'active')
+            ->getQuery()
+            ->getResult();
+    }
+
+    /**
+     * @param int[] $ids
+     * @return User[]
+     */
+    public function findByIds(array $ids): array
+    {
+        return $this->createQueryBuilder('u')
+            ->where('u.id IN (:ids)')
+            ->setParameter('ids', $ids)
+            ->getQuery()
+            ->getResult();
+    }
+}
+
+/**
+ * @template T
+ */
+final readonly class Result
+{
+    /**
+     * @param T $data
+     */
+    public function __construct(
+        public mixed $data,
+        public bool $success,
+    ) {}
+
+    /**
+     * @return T
+     */
+    public function getData(): mixed
+    {
+        return $this->data;
+    }
+}
+```
+
+## Mockery (Advanced Mocking)
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Service;
+
+use App\Repository\UserRepository;
+use App\Service\NotificationService;
+use Mockery;
+use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
+use PHPUnit\Framework\TestCase;
+
+final class NotificationServiceTest extends TestCase
+{
+    use MockeryPHPUnitIntegration;
+
+    public function testSendsNotificationToActiveUsers(): void
+    {
+        $repository = Mockery::mock(UserRepository::class);
+        $repository->shouldReceive('findActive')
+            ->once()
+            ->andReturn([
+                $this->createUser('user1@example.com'),
+                $this->createUser('user2@example.com'),
+            ]);
+
+        $service = new NotificationService($repository);
+        $result = $service->notifyActiveUsers('Important message');
+
+        $this->assertSame(2, $result->count());
+    }
+
+    public function testHandlesEmailServiceFailure(): void
+    {
+        $emailService = Mockery::mock(EmailService::class);
+        $emailService->shouldReceive('send')
+            ->once()
+            ->andThrow(new \RuntimeException('Email service down'));
+
+        $service = new NotificationService($emailService);
+
+        $this->expectException(\RuntimeException::class);
+        $service->sendNotification('test@example.com', 'Hello');
+    }
+
+    private function createUser(string $email): User
+    {
+        return new User(id: 1, email: $email, password: 'hashed');
+    }
+}
+```
+
+## Code Coverage
+
+```xml
+<!-- phpunit.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         failOnRisky="true"
+         failOnWarning="true"
+         stopOnFailure="false">
+    <testsuites>
+        <testsuite name="Unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="Feature">
+            <directory>tests/Feature</directory>
+        </testsuite>
+    </testsuites>
+    <coverage>
+        <include>
+            <directory suffix=".php">src</directory>
+        </include>
+        <exclude>
+            <directory>src/bootstrap</directory>
+            <file>src/Kernel.php</file>
+        </exclude>
+        <report>
+            <html outputDirectory="coverage/html"/>
+            <clover outputFile="coverage/clover.xml"/>
+        </report>
+    </coverage>
+    <php>
+        <env name="APP_ENV" value="testing"/>
+        <env name="DB_CONNECTION" value="sqlite"/>
+        <env name="DB_DATABASE" value=":memory:"/>
+    </php>
+</phpunit>
+```
+
+## Quick Reference
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| PHPUnit | Unit/Feature tests | `./vendor/bin/phpunit` |
+| Pest | Modern testing | `./vendor/bin/pest` |
+| PHPStan | Static analysis | `./vendor/bin/phpstan analyse` |
+| Psalm | Alternative static analysis | `./vendor/bin/psalm` |
+| PHP-CS-Fixer | Code style | `./vendor/bin/php-cs-fixer fix` |
+| PHPMD | Mess detector | `./vendor/bin/phpmd src text cleancode` |
+
+| Assertion | PHPUnit | Pest |
+|-----------|---------|------|
+| Equality | `$this->assertSame()` | `expect()->toBe()` |
+| Type | `$this->assertInstanceOf()` | `expect()->toBeInstanceOf()` |
+| Array | `$this->assertContains()` | `expect()->toContain()` |
+| Exception | `$this->expectException()` | `expect()->toThrow()` |
+| Count | `$this->assertCount()` | `expect()->toHaveCount()` |

package/presets/codex/AGENTS.md

@@ -8,6 +8,24 @@ project root as `AGENTS.md` (or merge it into an existing `AGENTS.md`).
 Codex reads `AGENTS.md` recursively from the project root. All agent roles are
 embedded here as workflow instructions.
 
+## Behavioral Discipline
+
+These principles apply to **all agents** in every workflow. They reduce common
+LLM coding mistakes and bias toward caution over speed.
+
+1. **Think Before Coding** — State assumptions explicitly. If uncertain, ask. If
+   multiple interpretations exist, present them — don't pick silently. If a
+   simpler approach exists, say so.
+2. **Simplicity First** — Minimum code that solves the problem. No features
+   beyond what was asked. No abstractions for single-use code. No speculative
+   "flexibility." Ask: "Would a senior engineer say this is overcomplicated?"
+3. **Surgical Changes** — Touch only what you must. Don't "improve" adjacent
+   code. Match existing style. Remove only what YOUR changes made unused. Every
+   changed line must trace directly to the user's request.
+4. **Goal-Driven Execution** — Transform tasks into verifiable goals with
+   success criteria. For multi-step tasks, state a plan with verification
+   checks. Loop until verified.
+
 ---
 
 ## Workflow Contract
@@ -111,8 +129,13 @@ a complete plan before implementation.
 1. Validate the Task Card before doing anything else.
 2. Classify the risk level using the table above.
 3. Select and document the agent route.
-4. Surface blockers rather than working around them.
-5. Declare completion only when all Deliverables are produced and verified.
+4. Enforce **Behavioral Discipline Gates**:
+   - **Think Before Coding Checkpoint**: Verify assumptions are explicitly documented before architect starts.
+   - **Simplicity Gate**: Review Technical Plan to ensure no speculative code or abstractions are planned.
+   - **Surgical Changes Audit**: Audit reviewer report and diff to verify only planned files were modified.
+   - **Goal-Driven Verification**: Confirm all acceptance criteria have passing tests.
+5. Surface blockers rather than working around them.
+6. Declare completion only when all Deliverables are produced and verified.
 
 **Task Card validation — required fields before routing:**
 
@@ -400,6 +423,7 @@ tests.
   module structure already present in the codebase.
 - **No scope creep.** If the plan says "add one endpoint," add one endpoint.
 - **Run tests before declaring done.** If any test fails, investigate and fix.
+- **Surgical Changes.** Modify ONLY planned files. Do not improve adjacent code, comments, or formatting. Match existing style. Remove imports/variables/functions made unused by YOUR changes. Do not touch existing dead code.
 
 **Completion Summary format:**
 
@@ -527,6 +551,8 @@ changes.
 | Error handling | Are failure cases handled explicitly and safely?                 |
 | Test coverage  | Do the tests verify all acceptance criteria?                     |
 | Technical debt | Does the implementation introduce debt without acknowledging it? |
+| Simplicity     | Flag overcomplicated or speculative code (overbuilt patterns).   |
+| Surgical       | Verify that NO adjacent or unrelated code/comments were changed. |
 
 **Finding categories:**
 
@@ -819,6 +845,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:
 
@@ -831,6 +864,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.

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. |