ultimate-pi 0.18.1 → 0.19.0

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.

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

@@ -0,0 +1,60 @@
+---
+name: service-mesh
+description: "Use when applying the service mesh pattern to service architectures: move cross-cutting network concerns such as retries, mTLS, routing, observability, policy, and traffic shaping out of service code while preserving domain ownership."
+---
+
+# Service Mesh Pattern
+
+Use this skill when cross-service networking concerns are polluting service code or need centralized policy.
+
+## Fit
+
+Use with multiple networked services that need consistent traffic policy, mTLS, observability, retries, or progressive delivery.
+Avoid for small systems where a mesh would add platform complexity without clear benefit.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "service mesh pattern microservices network policy observability"`.
+3. Identify cross-cutting network behavior embedded in services.
+4. Decide what belongs in mesh/platform versus application code.
+5. Remove one cross-cutting concern from service code safely.
+6. Add tests/config checks for equivalent behavior.
+
+## Target Shape
+
+```text
+services/<service>/code/     # domain/application code without mesh vendor logic
+platform/mesh/
+  policies/
+  routes/
+  telemetry/
+  security/
+```
+
+## Implementation Rules
+
+- Service code owns business behavior, data, and explicit dependency calls.
+- Mesh/platform owns mTLS, traffic routing, retries where safe, timeouts, telemetry, and policy.
+- Do not hide business retries or non-idempotent compensation in mesh config.
+- Timeout and retry budgets must align with application semantics.
+- Mesh config is versioned, reviewed, and tested like code.
+
+## Migration Steps
+
+1. Inventory duplicated network concerns in services.
+2. Pick one safe concern such as telemetry headers or mTLS policy.
+3. Add mesh/platform config with rollout guardrails.
+4. Remove redundant service code.
+5. Validate runtime behavior in tests or staging.
+6. Document ownership and rollback.
+
+## Verification
+
+- Use graphify to confirm service modules no longer depend on platform/mesh internals.
+- Test timeout/retry behavior for idempotent and non-idempotent calls.
+- Validate telemetry, route, and security policies with existing platform checks.
+
+## Output Contract
+
+Return: concern inventory, mesh/app ownership split, config/code patch, rollout plan, verification, and operational risks.

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

@@ -0,0 +1,60 @@
+---
+name: space-based
+description: "Use when implementing space-based architecture: horizontally scalable processing units, in-memory/distributed state, partitioning, eventual persistence, backpressure, replication, and operational safeguards for high-volume systems."
+---
+
+# Space-Based Architecture
+
+Use this skill for systems where database bottlenecks and burst traffic dominate the design.
+
+## Fit
+
+Use for high-volume, bursty, low-latency workloads needing horizontal scaling and elastic processing.
+Avoid for ordinary CRUD systems; this pattern adds serious operational complexity.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "space-based architecture processing units partitioning replication"`.
+3. Identify the scalability bottleneck and partition key.
+4. Isolate processing unit logic from persistence.
+5. Make state ownership, replication, and recovery explicit.
+6. Add load, failover, and backpressure checks.
+
+## Target Shape
+
+```text
+codebase/space/
+  processing-unit/    # stateless-ish compute plus owned partition state
+  partitioning        # keying and routing
+  state-store         # distributed/in-memory state port
+  persistence-sync    # async persistence/replication
+```
+
+## Implementation Rules
+
+- Choose a stable partition key before code changes.
+- Processing units own only their partition's hot state.
+- Persistence is asynchronous where possible; consistency must be stated.
+- Backpressure, retries, and overload behavior are part of the architecture.
+- Recovery must rebuild state from durable sources or snapshots.
+- Do not introduce distributed cache/state without observability.
+
+## Migration Steps
+
+1. Measure or identify the bottleneck.
+2. Extract hot-path processing into a processing-unit boundary.
+3. Add a state-store port with one implementation.
+4. Route requests/events by partition key.
+5. Add async persistence or snapshot/replay.
+6. Add load and failover tests around the boundary.
+
+## Verification
+
+- Use graphify to confirm hot path does not synchronously depend on the old bottleneck.
+- Test partition routing, duplicate processing, restart recovery, and overloaded dependencies.
+- Record latency/throughput assumptions in an ADR.
+
+## Output Contract
+
+Return: bottleneck, partition key, processing-unit patch, state/recovery model, verification, and operational risks.