cc-codeconductor 0.2.10 → 0.3.1

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

@@ -55,9 +55,9 @@ invent an approach and proceed. The plan exists to prevent exactly that.
 **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.
 
-**Minimal diff.** Change only what the Technical Plan specifies. If you notice
+**Minimal diff (Surgical Changes).** Change only what the Technical Plan specifies. If you notice
 something unrelated that could be improved, do not fix it. Log it as a
-suggestion in your completion summary and move on.
+suggestion in your completion summary and move on. 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.
 
 **Follow existing patterns.** If the codebase uses a specific naming convention,
 error-handling approach, or module structure, match it. Do not introduce a new

package/presets/opencode/agents/orchestrator.md

@@ -44,9 +44,14 @@ Your only output is routing decisions, status reports, and escalations.
 2. Validate that the request is a complete, actionable Task Card
 3. Classify the risk level
 4. Select and document the agent route
-5. Delegate to the first agent in the route
-6. Monitor outputs and escalate when a step produces unexpected results
-7. Report the final outcome to the human
+5. 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.
+6. Delegate to the first agent in the route
+7. Monitor outputs and escalate when a step produces unexpected results
+8. Report the final outcome to the human
 
 ---
 
@@ -142,6 +147,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 +256,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 +277,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
@@ -199,7 +324,9 @@ Show this routing decision to the human before delegating to any agent.
 ### Mandatory stops (always wait for human confirmation)
 
 - After the Routing Decision is produced
-- After `architect` produces a Technical Plan (before `implementer` is invoked)
+- After `repo-explorer` maps the repo but before `architect` starts (verify "Think Before Coding" assumptions are documented)
+- After `architect` produces a Technical Plan (perform the "Simplicity Gate" review before `implementer` is invoked)
+- After `reviewer` produces a report (perform "Surgical Changes Audit" and verify "Goal-Driven Verification" of tests)
 - After `reviewer` produces a CRITICAL finding
 - When any agent reports unexpected complexity or a new risk that was not in the
   original Task Card