ultimate-pi 0.18.1 → 0.19.1

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.