ultimate-pi 0.18.0 → 0.19.0

package/.pi/skills/architecture/cqrs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: cqrs
+description: "Use when implementing CQRS: separate command and query models, explicit write invariants, optimized read projections, consistency boundaries, projection rebuilds, and tests for command/query behavior."
+---
+
+# CQRS
+
+Use this skill when reads and writes need different models, scaling, permissions, or performance profiles.
+
+## Fit
+
+Use for complex domains with strong write invariants and read-heavy/query-specific views.
+Avoid when simple CRUD is adequate; CQRS can double code paths and consistency work.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "CQRS command query responsibility segregation projections events"`.
+3. Identify commands that change state and queries that read views.
+4. Separate write model from read model incrementally.
+5. Define consistency and projection rebuild rules.
+6. Add tests for commands, projections, and stale reads.
+
+## Target Shape
+
+```text
+codebase/<bounded-context>/
+  commands/
+    handlers/
+    model/
+  queries/
+    handlers/
+    projections/
+  events/              # optional but common
+```
+
+## Implementation Rules
+
+- Commands express intent and enforce invariants through the write model.
+- Queries never mutate state.
+- Read models are optimized for consumers and may be denormalized.
+- Projection lag and stale-read behavior must be explicit.
+- Do not expose write entities directly as read DTOs.
+- Keep command and query contracts versioned if external.
+
+## Migration Steps
+
+1. Pick one painful read or one complex command.
+2. Create command handler and query handler folders.
+3. Move invariant logic into command handler/write model.
+4. Create a read projection or query representation.
+5. Wire projection update from transaction, event, or scheduled rebuild.
+6. Add tests for stale/missing projection behavior.
+
+## Verification
+
+- Use graphify to confirm query handlers do not call command mutation paths.
+- Test command invariants independently from query projection shape.
+- Test projection rebuild from durable source.
+
+## Output Contract
+
+Return: command/query split, consistency model, projection path, migration patch, and verification evidence.

package/.pi/skills/architecture/event-driven/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: event-driven
+description: "Use when implementing event-driven architecture: domain/integration events, producers, consumers, broker or mediator topology, eventual consistency, idempotency, ordering, retries, and observable asynchronous flows."
+---
+
+# Event-Driven Architecture
+
+Use this skill when agents need to decouple producers and consumers with events safely.
+
+## Fit
+
+Use for asynchronous workflows, multi-consumer reactions, integration boundaries, audit trails, and high-throughput decoupling.
+Avoid when immediate consistency and simple request/response are enough.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "event-driven architecture broker mediator topology eventual consistency"`.
+3. Identify facts worth publishing, not commands disguised as events.
+4. Choose broker/choreography or mediator/orchestration intentionally.
+5. Implement one event path end to end.
+6. Add idempotency, retry, and observability before expanding.
+
+## Target Shape
+
+```text
+codebase/events/
+  contracts/          # event schemas and versions
+  event-bus           # publish/subscribe port
+  handlers/           # consumers
+  outbox/             # reliable publish if DB-backed
+```
+
+## Implementation Rules
+
+- Events are past-tense facts: `OrderPlaced`, not `PlaceOrder`.
+- Event schemas are versioned and backward-compatible.
+- Consumers are idempotent and handle duplicate/out-of-order delivery.
+- Use an outbox/inbox pattern when database state and publishing must be reliable.
+- Prefer correlation IDs and causation IDs for traceability.
+- Do not hide core business invariants in eventually consistent consumers.
+
+## Migration Steps
+
+1. Name one event from a real business fact.
+2. Define schema, version, producer, and consumers.
+3. Publish after the owning transaction commits.
+4. Add one consumer with idempotency storage.
+5. Add retry/dead-letter behavior.
+6. Add tests for duplicate, missing, and stale events.
+
+## Verification
+
+- `graphify explain "<event name>"` should show producer and consumers.
+- Contract-test event schema compatibility.
+- Test retry and idempotency paths.
+
+## Output Contract
+
+Return: event catalog, topology choice, producer/consumer patch, consistency guarantees, failure handling, and verification.

package/.pi/skills/architecture/hexagonal-ports-adapters/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: hexagonal-ports-adapters
+description: "Use when implementing hexagonal architecture / ports and adapters: domain core isolated from delivery and infrastructure mechanisms, inbound and outbound ports, adapters for external interfaces, dependency inversion, and testable business logic."
+---
+
+# Hexagonal Architecture / Ports and Adapters
+
+Use this skill to make business logic independent of delivery mechanisms and infrastructure.
+
+## Fit
+
+Use when domain logic is valuable, tests are brittle due to delivery/infrastructure coupling, or adapters change often.
+Avoid if the system is a tiny CRUD wrapper where abstraction would be ceremony.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "hexagonal architecture ports adapters domain operational coupling"`.
+3. Identify the core domain/application use case.
+4. Define inbound and outbound ports around it.
+5. Move delivery/infrastructure-specific code to adapters.
+6. Test the core through ports without infrastructure.
+
+## Target Shape
+
+```text
+codebase/
+  core/
+    domain/
+    application/
+    ports/
+      inbound-port
+      outbound-port
+  adapters/
+    inbound/external-interface/
+    inbound/operator-interface/
+    outbound/persistence/
+    outbound/messaging/
+```
+
+## Implementation Rules
+
+- Core owns domain and application behavior.
+- Inbound adapters translate external requests into use-case calls.
+- Outbound adapters implement core-defined ports for persistence, messaging, time, IDs, and external APIs.
+- Dependencies point inward: adapters reference core, core does not reference adapters.
+- Use dependency injection/composition at the edge.
+
+## Migration Steps
+
+1. Pick one use case entangled with delivery or persistence infrastructure.
+2. Extract its input/output contracts and port interfaces into core.
+3. Move business decisions into application/domain.
+4. Wrap existing persistence/integration code as an outbound adapter.
+5. Wire adapters in the composition root.
+6. Add core tests with fake outbound ports.
+
+## Verification
+
+- `graphify explain "core"` should show no outbound adapter or infrastructure references.
+- Search core paths for delivery, persistence, messaging, filesystem, environment, or platform dependencies.
+- Test core without starting external infrastructure.
+
+## Output Contract
+
+Return: core boundary, ports, adapters, composition root change, tests, and remaining coupling.

package/.pi/skills/architecture/layered/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: layered
+description: "Use when designing, refactoring, or validating a codebase as layered architecture: delivery/interface, application/use-case, domain, and infrastructure/data layers with one-way dependency rules and minimal cross-layer coupling."
+---
+
+# Layered Architecture
+
+Use this skill to help an agent implement layered architecture, not just describe it.
+
+## Fit
+
+Use when the system is mostly CRUD, workflow-oriented, or policy-heavy and benefits from clear dependency direction.
+Avoid when independent deployment, high autonomous scaling, or highly asynchronous collaboration is the main driver.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md` before source files.
+2. Run `graphify query "layered architecture dependencies presentation application domain infrastructure"`.
+3. Infer the actual layers from packages, modules, and graph communities.
+4. Define allowed dependencies before moving code.
+5. Make the smallest refactor that improves directionality.
+6. Add a fitness check that prevents backsliding.
+
+## Target Shape
+
+Typical dependency direction:
+
+```text
+presentation/api -> application/use-cases -> domain -> infrastructure interfaces
+                                      infrastructure adapters -> domain/application ports
+```
+
+Prefer these directories when introducing structure:
+
+```text
+codebase/
+  delivery/           # external-interface adapters
+  application/        # use cases, commands, queries, units of work
+  domain/             # entities, value objects, policies, domain services
+  infrastructure/     # persistence, network, messaging, filesystem, platform adapters
+```
+
+## Implementation Rules
+
+- Domain code must not reference delivery mechanisms, persistence tooling, messaging systems, clocks, environment, or global configuration.
+- Application code orchestrates use cases and owns transaction boundaries.
+- Delivery/interface code maps external contracts to application inputs; it does not hold business rules.
+- Infrastructure implements interfaces/ports declared inward.
+- Shared utilities must be boring, stable, and dependency-free; do not create a junk drawer.
+
+## Migration Steps
+
+1. Pick one vertical use case.
+2. Move business decisions from entrypoint handlers into `domain/`.
+3. Create an application use-case routine around it.
+4. Place infrastructure behind explicit interfaces.
+5. Leave old entrypoints as thin adapters.
+6. Repeat by use case, not by sweeping folders.
+
+## Verification
+
+- Use `graphify explain "<domain symbol>"` to confirm it has no outbound delivery/infrastructure edges.
+- Search domain paths for forbidden references to delivery, persistence, messaging, environment, or platform mechanisms.
+- Add dependency-boundary tests with the repo's existing verification tooling.
+
+## Output Contract
+
+Return: inferred layers, violations, minimal migration patch, verification run, and remaining risks.

package/.pi/skills/architecture/microkernel/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: microkernel
+description: "Use when building plugin or extension architecture: a stable core kernel with explicit extension points, plugin contracts, registration, isolation, versioning, and compatibility checks."
+---
+
+# Microkernel / Plugin Architecture
+
+Use this skill when the codebase needs a small core and independently variable plugins.
+
+## Fit
+
+Use for CLIs, editors, rules engines, integrations, workflow engines, agent tools, and product variants.
+Avoid when variation is low or plugin isolation would add more complexity than it removes.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "microkernel plugin extension points core adapters"`.
+3. Identify stable core responsibilities versus variable behavior.
+4. Define extension contracts before extracting plugins.
+5. Move one variable feature behind a plugin boundary.
+6. Add compatibility and registration checks.
+
+## Target Shape
+
+```text
+codebase/kernel/
+  contracts           # plugin interfaces, capabilities, lifecycle
+  registry            # discovery, validation, ordering
+  runtime             # core orchestration
+codebase/plugins/
+  <plugin-name>/
+    entrypoint        # manifest + implementation
+    tests/
+```
+
+## Implementation Rules
+
+- Kernel owns orchestration, lifecycle, contracts, capability negotiation, and safe defaults.
+- Plugins own optional behavior only; they must not mutate kernel internals.
+- Plugin APIs are versioned and narrow.
+- Registration validates name, version, capabilities, dependencies, and conflicts.
+- Side effects are exposed through kernel-provided services, not global imports.
+
+## Migration Steps
+
+1. Name the extension point.
+2. Create contract and manifest types.
+3. Implement an in-process registry.
+4. Wrap one existing variation as the first built-in plugin.
+5. Replace direct branching with registry dispatch.
+6. Add contract tests reused by every plugin.
+
+## Verification
+
+- `graphify explain "registry"` should show kernel-to-plugin direction, not plugin-to-kernel internals.
+- Add tests for plugin registration, invalid manifests, lifecycle failures, and version mismatch.
+- Search for plugin imports of kernel private paths.
+
+## Output Contract
+
+Return: kernel boundary, extension points, plugin contract, migrated plugin, compatibility tests, and known limitations.

package/.pi/skills/architecture/microservices/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: microservices
+description: "Use when designing, extracting, or repairing microservices: independently deployable bounded-context services with owned data, explicit contracts, observability, resilience, distributed workflow choices, and operational readiness checks."
+---
+
+# Microservices Architecture
+
+Use this skill only when service independence is worth distributed-system cost.
+
+## Fit
+
+Use when services need independent deployability, independent scaling, domain autonomy, and separate data ownership.
+Avoid when boundaries are unclear, teams cannot operate services, or a modular monolith would solve the problem.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "microservices bounded context data isolation choreography orchestration sagas"`.
+3. Identify bounded contexts and fracture planes.
+4. Choose one extraction candidate with high cohesion and low coupling.
+5. Define API/events/data ownership before moving code.
+6. Add production-readiness controls with the first extraction.
+
+## Target Shape
+
+```text
+services/
+  orders/
+    code/
+    contract/          # API specs, event schemas
+    migrations/
+    deploy/
+  billing/
+    ...
+shared/                # generated clients/contracts only; no shared domain model
+```
+
+## Implementation Rules
+
+- Each service owns its data; no cross-service table writes.
+- Contracts are explicit: API schema, event schema, or generated client.
+- Distributed workflows use choreography, orchestration, or saga intentionally.
+- Every network call has timeout, retry policy, circuit breaker/backoff as appropriate, and observability.
+- Avoid shared domain libraries; share contracts, not internals.
+- Extraction must include deployment, rollback, monitoring, and incident path.
+
+## Migration Steps
+
+1. Prove the boundary with a modular monolith facade first when possible.
+2. Create service contract and data ownership doc.
+3. Duplicate or migrate data behind an anti-corruption layer.
+4. Route one use case through the new service.
+5. Add contract tests and consumer-driven compatibility checks.
+6. Add traces, metrics, logs, health checks, and rollback.
+
+## Verification
+
+- `graphify explain "<service>"` should show contract edges, not private code sharing.
+- Test API compatibility, idempotency, failure, timeout, and degraded dependency behavior.
+- Verify no direct database access across service boundaries.
+
+## Output Contract
+
+Return: service boundary, contracts, data ownership, extraction patch, resilience controls, verification, and ops risks.

package/.pi/skills/architecture/modular-monolith/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: modular-monolith
+description: "Use when designing, splitting, or repairing a modular monolith: one deployable application with explicit business modules, bounded contexts, private internals, stable module APIs, and database boundaries that can later support service extraction."
+---
+
+# Modular Monolith
+
+Use this skill when an agent should preserve monolith simplicity while creating real architectural boundaries.
+
+## Fit
+
+Use when one deployable is acceptable but the codebase needs independent business modules, lower coupling, and clearer ownership.
+Avoid premature microservices when deployment independence, team autonomy, and operational maturity are not proven.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "modular monolith bounded context module boundaries coupling"`.
+3. Identify business capabilities and their current code communities.
+4. Pick one module boundary to harden.
+5. Introduce module APIs before moving persistence or transport code.
+6. Verify no private internals leak across modules.
+
+## Target Shape
+
+```text
+codebase/modules/
+  billing/
+    public-api         # exported commands/events/types only
+    application/
+    domain/
+    infrastructure/
+    internal/          # never imported by other modules
+  identity/
+    public-api
+    ...
+codebase/shared-kernel/ # tiny, stable cross-module primitives only
+```
+
+## Implementation Rules
+
+- Modules communicate through an explicit public API/facade, application commands, domain events, or explicit query APIs.
+- No module imports another module's `internal/`, `domain/`, or infrastructure files.
+- Keep one process and one deployment until extraction pressure is real.
+- Prefer per-module schemas/tables or clear ownership comments for shared DBs.
+- Shared kernel must be small; duplicated domain language is often better than false sharing.
+
+## Migration Steps
+
+1. Name the bounded context using domain vocabulary.
+2. Create the module directory and public API/facade.
+3. Move one cohesive use case behind the facade.
+4. Replace external imports with facade calls.
+5. Add a dependency-boundary rule.
+6. Document the module's owned data and events.
+
+## Verification
+
+- `graphify explain "<module name>"` should show few cross-module private edges.
+- Use structural search for imports from `modules/*/internal`, `domain`, or `infrastructure` across module boundaries.
+- Add tests at module API boundaries, not only end-to-end tests.
+
+## Output Contract
+
+Return: proposed modules, public APIs, forbidden imports, migration patch, fitness check, and extraction readiness notes.

package/.pi/skills/architecture/orchestration-driven-soa/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: orchestration-driven-soa
+description: "Use when implementing orchestration-driven service-oriented architecture: central workflow orchestration across services, explicit process models, compensations, service contracts, long-running transactions, and governance boundaries."
+---
+
+# Orchestration-Driven SOA
+
+Use this skill when a central process coordinator is the clearest way to manage cross-service workflows.
+
+## Fit
+
+Use for long-running business processes, compliance-heavy flows, and integrations where visibility and control matter more than local autonomy.
+Avoid when simple choreography is sufficient or a central orchestrator would become a god service.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "orchestration driven service oriented architecture workflow compensation"`.
+3. Identify the end-to-end business process and participating services.
+4. Model the workflow states before code.
+5. Implement the orchestrator as a thin state machine, not a business blob.
+6. Add compensation and timeout behavior.
+
+## Target Shape
+
+```text
+codebase/workflows/
+  <workflow>/
+    states
+    orchestrator
+    participants
+    compensations
+    tests/
+codebase/services/*/contract
+```
+
+## Implementation Rules
+
+- Orchestrator owns process state, sequencing, timeouts, and compensation.
+- Domain services own local business invariants and data.
+- Participant contracts are explicit and versioned.
+- Every remote step has timeout, retry, and compensation semantics.
+- Avoid embedding service internals in the orchestrator.
+
+## Migration Steps
+
+1. Draw the workflow as states and transitions.
+2. Define participant ports/contracts.
+3. Implement a state store for workflow instances.
+4. Move cross-service sequencing into the orchestrator.
+5. Add compensating actions for partial failure.
+6. Add trace IDs across all participant calls.
+
+## Verification
+
+- `graphify explain "orchestrator"` should show workflow-to-contract dependencies, not service internals.
+- Test happy path, participant failure, retry exhaustion, timeout, compensation failure, and resume after crash.
+
+## Output Contract
+
+Return: workflow state model, participant contracts, orchestrator patch, compensation matrix, and verification evidence.

package/.pi/skills/architecture/pipeline/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pipeline
+description: "Use when implementing pipeline architecture: data or task processing split into ordered filters/stages with explicit inputs, outputs, composition, error handling, and observability across the flow."
+---
+
+# Pipeline Architecture
+
+Use this skill to transform tangled sequential processing into composable stages.
+
+## Fit
+
+Use for compilers, ETL, media/document processing, validation chains, enrichment, agent workflows, and deterministic multi-step transformations.
+Avoid when stages require heavy bidirectional coordination or shared mutable state.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "pipeline stages filters processing flow"`.
+3. Identify the current implicit sequence and data passed between steps.
+4. Define a typed stage contract.
+5. Extract one stage at a time.
+6. Add tests per stage and for the assembled pipeline.
+
+## Target Shape
+
+```text
+codebase/pipeline/
+  stage-contract      # Stage<Input, Output>, context, errors
+  stages/
+    parse
+    validate
+    enrich
+    persist
+  compose             # ordering and short-circuit rules
+```
+
+## Implementation Rules
+
+- Each stage has one responsibility and explicit input/output.
+- Stages do not reach backward into previous stages' internals.
+- Shared context is read-mostly; stage outputs carry facts forward.
+- Treat retries, dead letters, partial failures, and idempotency as first-class.
+- Put composition outside stages so ordering is visible.
+
+## Migration Steps
+
+1. Write the stage interface.
+2. Wrap the existing process as one stage-preserving facade.
+3. Extract the first pure transformation.
+4. Add fixture tests for that stage.
+5. Extract side-effecting stages behind ports/adapters.
+6. Make observability emit stage name, duration, input id, and failure class.
+
+## Verification
+
+- Use `graphify explain "compose"` or the pipeline entrypoint to inspect stage dependencies.
+- Test stages independently with fixtures.
+- Test full ordering with one integration test.
+- Confirm stages do not directly depend on each other except through composition.
+
+## Output Contract
+
+Return: stage map, stage contracts, extracted stage patch, failure semantics, and verification evidence.

package/.pi/skills/architecture/service-based/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: service-based
+description: "Use when implementing service-based architecture: coarse-grained domain services inside a mostly centralized system, with explicit service contracts, transaction boundaries, shared infrastructure discipline, and fewer operational costs than microservices."
+---
+
+# Service-Based Architecture
+
+Use this skill to carve coarse domain services without forcing full microservice overhead.
+
+## Fit
+
+Use when modules need clearer runtime/service boundaries but can share deployment, database infrastructure, or platform operations.
+Avoid when independent deployability and data ownership per service are already mandatory.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "service-based architecture coarse services database boundaries transactions"`.
+3. Identify coarse business services and shared resources.
+4. Define service contracts and transaction ownership.
+5. Extract one service facade and move callers behind it.
+6. Add contract and dependency checks.
+
+## Target Shape
+
+```text
+codebase/services/
+  customer/
+    contract
+    service
+    data-access
+  order/
+    contract
+    service
+    data-access
+codebase/platform/     # shared runtime, config, logging, persistence connection
+```
+
+## Implementation Rules
+
+- Services are coarse-grained and domain-aligned, not one service per entity.
+- Services expose contracts; callers do not reach into service internals.
+- Transaction boundaries are explicit and usually owned by the called service.
+- Shared DB is allowed, but table ownership and cross-service writes must be documented.
+- Avoid distributed systems ceremony unless deployment separation is real.
+
+## Migration Steps
+
+1. Pick one domain service with many scattered callers.
+2. Create the service contract and service facade.
+3. Move behavior behind the facade.
+4. Replace direct data writes from other areas with service calls.
+5. Document data ownership.
+6. Add tests for service contract and transaction behavior.
+
+## Verification
+
+- Use `graphify explain "<service name>"` to inspect inbound/outbound coupling.
+- Search for cross-service imports into internal files.
+- Test that callers use contracts and cannot mutate owned data directly.
+
+## Output Contract
+
+Return: service boundaries, contracts, transaction rules, migrated callers, verification, and microservice-readiness caveats.