claude-code-pilot 3.0.0 → 3.1.1

package/src/skills/hexagonal-architecture/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: hexagonal-architecture
+description: Design, implement, and refactor Ports & Adapters systems with clear domain boundaries, dependency inversion, and testable use-case orchestration across TypeScript, Java, Kotlin, and Go services.
+origin: ECC
+---
+
+# Hexagonal Architecture
+
+Hexagonal architecture (Ports and Adapters) keeps business logic independent from frameworks, transport, and persistence details. The core app depends on abstract ports, and adapters implement those ports at the edges.
+
+## When to Use
+
+- Building new features where long-term maintainability and testability matter.
+- Refactoring layered or framework-heavy code where domain logic is mixed with I/O concerns.
+- Supporting multiple interfaces for the same use case (HTTP, CLI, queue workers, cron jobs).
+- Replacing infrastructure (database, external APIs, message bus) without rewriting business rules.
+
+Use this skill when the request involves boundaries, domain-centric design, refactoring tightly coupled services, or decoupling application logic from specific libraries.
+
+## Core Concepts
+
+- **Domain model**: Business rules and entities/value objects. No framework imports.
+- **Use cases (application layer)**: Orchestrate domain behavior and workflow steps.
+- **Inbound ports**: Contracts describing what the application can do (commands/queries/use-case interfaces).
+- **Outbound ports**: Contracts for dependencies the application needs (repositories, gateways, event publishers, clock, UUID, etc.).
+- **Adapters**: Infrastructure and delivery implementations of ports (HTTP controllers, DB repositories, queue consumers, SDK wrappers).
+- **Composition root**: Single wiring location where concrete adapters are bound to use cases.
+
+Outbound port interfaces usually live in the application layer (or in domain only when the abstraction is truly domain-level), while infrastructure adapters implement them.
+
+Dependency direction is always inward:
+
+- Adapters -> application/domain
+- Application -> port interfaces (inbound/outbound contracts)
+- Domain -> domain-only abstractions (no framework or infrastructure dependencies)
+- Domain -> nothing external
+
+## How It Works
+
+### Step 1: Model a use case boundary
+
+Define a single use case with a clear input and output DTO. Keep transport details (Express `req`, GraphQL `context`, job payload wrappers) outside this boundary.
+
+### Step 2: Define outbound ports first
+
+Identify every side effect as a port:
+
+- persistence (`UserRepositoryPort`)
+- external calls (`BillingGatewayPort`)
+- cross-cutting (`LoggerPort`, `ClockPort`)
+
+Ports should model capabilities, not technologies.
+
+### Step 3: Implement the use case with pure orchestration
+
+Use case class/function receives ports via constructor/arguments. It validates application-level invariants, coordinates domain rules, and returns plain data structures.
+
+### Step 4: Build adapters at the edge
+
+- Inbound adapter converts protocol input to use-case input.
+- Outbound adapter maps app contracts to concrete APIs/ORM/query builders.
+- Mapping stays in adapters, not inside use cases.
+
+### Step 5: Wire everything in a composition root
+
+Instantiate adapters, then inject them into use cases. Keep this wiring centralized to avoid hidden service-locator behavior.
+
+### Step 6: Test per boundary
+
+- Unit test use cases with fake ports.
+- Integration test adapters with real infra dependencies.
+- E2E test user-facing flows through inbound adapters.
+
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+  Client["Client (HTTP/CLI/Worker)"] --> InboundAdapter["Inbound Adapter"]
+  InboundAdapter -->|"calls"| UseCase["UseCase (Application Layer)"]
+  UseCase -->|"uses"| OutboundPort["OutboundPort (Interface)"]
+  OutboundAdapter["Outbound Adapter"] -->|"implements"| OutboundPort
+  OutboundAdapter --> ExternalSystem["DB/API/Queue"]
+  UseCase --> DomainModel["DomainModel"]
+```
+
+## Suggested Module Layout
+
+Use feature-first organization with explicit boundaries:
+
+```text
+src/
+  features/
+    orders/
+      domain/
+        Order.ts
+        OrderPolicy.ts
+      application/
+        ports/
+          inbound/
+            CreateOrder.ts
+          outbound/
+            OrderRepositoryPort.ts
+            PaymentGatewayPort.ts
+        use-cases/
+          CreateOrderUseCase.ts
+      adapters/
+        inbound/
+          http/
+            createOrderRoute.ts
+        outbound/
+          postgres/
+            PostgresOrderRepository.ts
+          stripe/
+            StripePaymentGateway.ts
+      composition/
+        ordersContainer.ts
+```
+
+## TypeScript Example
+
+### Port definitions
+
+```typescript
+export interface OrderRepositoryPort {
+  save(order: Order): Promise<void>;
+  findById(orderId: string): Promise<Order | null>;
+}
+
+export interface PaymentGatewayPort {
+  authorize(input: { orderId: string; amountCents: number }): Promise<{ authorizationId: string }>;
+}
+```
+
+### Use case
+
+```typescript
+type CreateOrderInput = {
+  orderId: string;
+  amountCents: number;
+};
+
+type CreateOrderOutput = {
+  orderId: string;
+  authorizationId: string;
+};
+
+export class CreateOrderUseCase {
+  constructor(
+    private readonly orderRepository: OrderRepositoryPort,
+    private readonly paymentGateway: PaymentGatewayPort
+  ) {}
+
+  async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
+    const order = Order.create({ id: input.orderId, amountCents: input.amountCents });
+
+    const auth = await this.paymentGateway.authorize({
+      orderId: order.id,
+      amountCents: order.amountCents,
+    });
+
+    // markAuthorized returns a new Order instance; it does not mutate in place.
+    const authorizedOrder = order.markAuthorized(auth.authorizationId);
+    await this.orderRepository.save(authorizedOrder);
+
+    return {
+      orderId: order.id,
+      authorizationId: auth.authorizationId,
+    };
+  }
+}
+```
+
+### Outbound adapter
+
+```typescript
+export class PostgresOrderRepository implements OrderRepositoryPort {
+  constructor(private readonly db: SqlClient) {}
+
+  async save(order: Order): Promise<void> {
+    await this.db.query(
+      "insert into orders (id, amount_cents, status, authorization_id) values ($1, $2, $3, $4)",
+      [order.id, order.amountCents, order.status, order.authorizationId]
+    );
+  }
+
+  async findById(orderId: string): Promise<Order | null> {
+    const row = await this.db.oneOrNone("select * from orders where id = $1", [orderId]);
+    return row ? Order.rehydrate(row) : null;
+  }
+}
+```
+
+### Composition root
+
+```typescript
+export const buildCreateOrderUseCase = (deps: { db: SqlClient; stripe: StripeClient }) => {
+  const orderRepository = new PostgresOrderRepository(deps.db);
+  const paymentGateway = new StripePaymentGateway(deps.stripe);
+
+  return new CreateOrderUseCase(orderRepository, paymentGateway);
+};
+```
+
+## Multi-Language Mapping
+
+Use the same boundary rules across ecosystems; only syntax and wiring style change.
+
+- **TypeScript/JavaScript**
+    - Ports: `application/ports/*` as interfaces/types.
+    - Use cases: classes/functions with constructor/argument injection.
+    - Adapters: `adapters/inbound/*`, `adapters/outbound/*`.
+    - Composition: explicit factory/container module (no hidden globals).
+- **Java**
+    - Packages: `domain`, `application.port.in`, `application.port.out`, `application.usecase`, `adapter.in`, `adapter.out`.
+    - Ports: interfaces in `application.port.*`.
+    - Use cases: plain classes (Spring `@Service` is optional, not required).
+    - Composition: Spring config or manual wiring class; keep wiring out of domain/use-case classes.
+- **Kotlin**
+    - Modules/packages mirror the Java split (`domain`, `application.port`, `application.usecase`, `adapter`).
+    - Ports: Kotlin interfaces.
+    - Use cases: classes with constructor injection (Koin/Dagger/Spring/manual).
+    - Composition: module definitions or dedicated composition functions; avoid service locator patterns.
+- **Go**
+    - Packages: `internal/<feature>/domain`, `application`, `ports`, `adapters/inbound`, `adapters/outbound`.
+    - Ports: small interfaces owned by the consuming application package.
+    - Use cases: structs with interface fields plus explicit `New...` constructors.
+    - Composition: wire in `cmd/<app>/main.go` (or dedicated wiring package), keep constructors explicit.
+
+## Anti-Patterns to Avoid
+
+- Domain entities importing ORM models, web framework types, or SDK clients.
+- Use cases reading directly from `req`, `res`, or queue metadata.
+- Returning database rows directly from use cases without domain/application mapping.
+- Letting adapters call each other directly instead of flowing through use-case ports.
+- Spreading dependency wiring across many files with hidden global singletons.
+
+## Migration Playbook
+
+1. Pick one vertical slice (single endpoint/job) with frequent change pain.
+2. Extract a use-case boundary with explicit input/output types.
+3. Introduce outbound ports around existing infrastructure calls.
+4. Move orchestration logic from controllers/services into the use case.
+5. Keep old adapters, but make them delegate to the new use case.
+6. Add tests around the new boundary (unit + adapter integration).
+7. Repeat slice-by-slice; avoid full rewrites.
+
+### Refactoring Existing Systems
+
+- **Strangler approach**: keep current endpoints, route one use case at a time through new ports/adapters.
+- **No big-bang rewrites**: migrate per feature slice and preserve behavior with characterization tests.
+- **Facade first**: wrap legacy services behind outbound ports before replacing internals.
+- **Composition freeze**: centralize wiring early so new dependencies do not leak into domain/use-case layers.
+- **Slice selection rule**: prioritize high-churn, low-blast-radius flows first.
+- **Rollback path**: keep a reversible toggle or route switch per migrated slice until production behavior is verified.
+
+## Testing Guidance (Same Hexagonal Boundaries)
+
+- **Domain tests**: test entities/value objects as pure business rules (no mocks, no framework setup).
+- **Use-case unit tests**: test orchestration with fakes/stubs for outbound ports; assert business outcomes and port interactions.
+- **Outbound adapter contract tests**: define shared contract suites at port level and run them against each adapter implementation.
+- **Inbound adapter tests**: verify protocol mapping (HTTP/CLI/queue payload to use-case input and output/error mapping back to protocol).
+- **Adapter integration tests**: run against real infrastructure (DB/API/queue) for serialization, schema/query behavior, retries, and timeouts.
+- **End-to-end tests**: cover critical user journeys through inbound adapter -> use case -> outbound adapter.
+- **Refactor safety**: add characterization tests before extraction; keep them until new boundary behavior is stable and equivalent.
+
+## Best Practices Checklist
+
+- Domain and use-case layers import only internal types and ports.
+- Every external dependency is represented by an outbound port.
+- Validation occurs at boundaries (inbound adapter + use-case invariants).
+- Use immutable transformations (return new values/entities instead of mutating shared state).
+- Errors are translated across boundaries (infra errors -> application/domain errors).
+- Composition root is explicit and easy to audit.
+- Use cases are testable with simple in-memory fakes for ports.
+- Refactoring starts from one vertical slice with behavior-preserving tests.
+- Language/framework specifics stay in adapters, never in domain rules.

package/src/skills/iterative-retrieval/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: iterative-retrieval
+description: Pattern for progressively refining context retrieval to solve the subagent context problem
+origin: ECC
+---
+
+# Iterative Retrieval Pattern
+
+Solves the "context problem" in multi-agent workflows where subagents don't know what context they need until they start working.
+
+## When to Activate
+
+- Spawning subagents that need codebase context they cannot predict upfront
+- Building multi-agent workflows where context is progressively refined
+- Encountering "context too large" or "missing context" failures in agent tasks
+- Designing RAG-like retrieval pipelines for code exploration
+- Optimizing token usage in agent orchestration
+
+## The Problem
+
+Subagents are spawned with limited context. They don't know:
+- Which files contain relevant code
+- What patterns exist in the codebase
+- What terminology the project uses
+
+Standard approaches fail:
+- **Send everything**: Exceeds context limits
+- **Send nothing**: Agent lacks critical information
+- **Guess what's needed**: Often wrong
+
+## The Solution: Iterative Retrieval
+
+A 4-phase loop that progressively refines context:
+
+```
+┌─────────────────────────────────────────────┐
+│                                             │
+│   ┌──────────┐      ┌──────────┐            │
+│   │ DISPATCH │─────│ EVALUATE │            │
+│   └──────────┘      └──────────┘            │
+│        ▲                  │                 │
+│        │                  ▼                 │
+│   ┌──────────┐      ┌──────────┐            │
+│   │   LOOP   │─────│  REFINE  │            │
+│   └──────────┘      └──────────┘            │
+│                                             │
+│        Max 3 cycles, then proceed           │
+└─────────────────────────────────────────────┘
+```
+
+### Phase 1: DISPATCH
+
+Initial broad query to gather candidate files:
+
+```javascript
+// Start with high-level intent
+const initialQuery = {
+  patterns: ['src/**/*.ts', 'lib/**/*.ts'],
+  keywords: ['authentication', 'user', 'session'],
+  excludes: ['*.test.ts', '*.spec.ts']
+};
+
+// Dispatch to retrieval agent
+const candidates = await retrieveFiles(initialQuery);
+```
+
+### Phase 2: EVALUATE
+
+Assess retrieved content for relevance:
+
+```javascript
+function evaluateRelevance(files, task) {
+  return files.map(file => ({
+    path: file.path,
+    relevance: scoreRelevance(file.content, task),
+    reason: explainRelevance(file.content, task),
+    missingContext: identifyGaps(file.content, task)
+  }));
+}
+```
+
+Scoring criteria:
+- **High (0.8-1.0)**: Directly implements target functionality
+- **Medium (0.5-0.7)**: Contains related patterns or types
+- **Low (0.2-0.4)**: Tangentially related
+- **None (0-0.2)**: Not relevant, exclude
+
+### Phase 3: REFINE
+
+Update search criteria based on evaluation:
+
+```javascript
+function refineQuery(evaluation, previousQuery) {
+  return {
+    // Add new patterns discovered in high-relevance files
+    patterns: [...previousQuery.patterns, ...extractPatterns(evaluation)],
+
+    // Add terminology found in codebase
+    keywords: [...previousQuery.keywords, ...extractKeywords(evaluation)],
+
+    // Exclude confirmed irrelevant paths
+    excludes: [...previousQuery.excludes, ...evaluation
+      .filter(e => e.relevance < 0.2)
+      .map(e => e.path)
+    ],
+
+    // Target specific gaps
+    focusAreas: evaluation
+      .flatMap(e => e.missingContext)
+      .filter(unique)
+  };
+}
+```
+
+### Phase 4: LOOP
+
+Repeat with refined criteria (max 3 cycles):
+
+```javascript
+async function iterativeRetrieve(task, maxCycles = 3) {
+  let query = createInitialQuery(task);
+  let bestContext = [];
+
+  for (let cycle = 0; cycle < maxCycles; cycle++) {
+    const candidates = await retrieveFiles(query);
+    const evaluation = evaluateRelevance(candidates, task);
+
+    // Check if we have sufficient context
+    const highRelevance = evaluation.filter(e => e.relevance >= 0.7);
+    if (highRelevance.length >= 3 && !hasCriticalGaps(evaluation)) {
+      return highRelevance;
+    }
+
+    // Refine and continue
+    query = refineQuery(evaluation, query);
+    bestContext = mergeContext(bestContext, highRelevance);
+  }
+
+  return bestContext;
+}
+```
+
+## Practical Examples
+
+### Example 1: Bug Fix Context
+
+```
+Task: "Fix the authentication token expiry bug"
+
+Cycle 1:
+  DISPATCH: Search for "token", "auth", "expiry" in src/**
+  EVALUATE: Found auth.ts (0.9), tokens.ts (0.8), user.ts (0.3)
+  REFINE: Add "refresh", "jwt" keywords; exclude user.ts
+
+Cycle 2:
+  DISPATCH: Search refined terms
+  EVALUATE: Found session-manager.ts (0.95), jwt-utils.ts (0.85)
+  REFINE: Sufficient context (2 high-relevance files)
+
+Result: auth.ts, tokens.ts, session-manager.ts, jwt-utils.ts
+```
+
+### Example 2: Feature Implementation
+
+```
+Task: "Add rate limiting to API endpoints"
+
+Cycle 1:
+  DISPATCH: Search "rate", "limit", "api" in routes/**
+  EVALUATE: No matches - codebase uses "throttle" terminology
+  REFINE: Add "throttle", "middleware" keywords
+
+Cycle 2:
+  DISPATCH: Search refined terms
+  EVALUATE: Found throttle.ts (0.9), middleware/index.ts (0.7)
+  REFINE: Need router patterns
+
+Cycle 3:
+  DISPATCH: Search "router", "express" patterns
+  EVALUATE: Found router-setup.ts (0.8)
+  REFINE: Sufficient context
+
+Result: throttle.ts, middleware/index.ts, router-setup.ts
+```
+
+## Integration with Agents
+
+Use in agent prompts:
+
+```markdown
+When retrieving context for this task:
+1. Start with broad keyword search
+2. Evaluate each file's relevance (0-1 scale)
+3. Identify what context is still missing
+4. Refine search criteria and repeat (max 3 cycles)
+5. Return files with relevance >= 0.7
+```
+
+## Best Practices
+
+1. **Start broad, narrow progressively** - Don't over-specify initial queries
+2. **Learn codebase terminology** - First cycle often reveals naming conventions
+3. **Track what's missing** - Explicit gap identification drives refinement
+4. **Stop at "good enough"** - 3 high-relevance files beats 10 mediocre ones
+5. **Exclude confidently** - Low-relevance files won't become relevant
+
+## Related
+
+- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) - Subagent orchestration section
+- `continuous-learning` skill - For patterns that improve over time
+- Agent definitions bundled with ECC (manual install path: `agents/`)