pi-dev-team 0.2.0

package/skills/docker-image-audit/references/install-guide.md

@@ -0,0 +1,64 @@
+# Docker Audit Tool Installation Guide
+
+When the user is missing hadolint, trivy, or grype, share the relevant section below.
+
+## hadolint
+
+Hadolint is a Dockerfile linter that also integrates ShellCheck for `RUN` instructions.
+
+- **macOS**: `brew install hadolint`
+- **Windows** (Scoop): `scoop install hadolint`
+- **Linux** (binary):
+  ```bash
+  curl -sL -o /usr/local/bin/hadolint \
+    "https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64"
+  chmod +x /usr/local/bin/hadolint
+  ```
+- **Docker** (no install): `docker run --rm -i hadolint/hadolint < Dockerfile`
+- **All platforms**: Download from [GitHub releases](https://github.com/hadolint/hadolint/releases)
+
+## Trivy
+
+Trivy scans container images, filesystems, and git repos for vulnerabilities, misconfigurations, and secrets.
+
+- **macOS**: `brew install trivy`
+- **Linux** (apt):
+  ```bash
+  sudo apt-get install -y wget apt-transport-https gnupg lsb-release
+  wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
+  echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/trivy.list
+  sudo apt-get update && sudo apt-get install -y trivy
+  ```
+- **Linux** (rpm):
+  ```bash
+  cat << 'EOF' | sudo tee /etc/yum.repos.d/trivy.repo
+  [trivy]
+  name=Trivy repository
+  baseurl=https://aquasecurity.github.io/trivy-repo/rpm/releases/$basearch/
+  gpgcheck=0
+  enabled=1
+  EOF
+  sudo yum -y install trivy
+  ```
+- **Docker** (no install): `docker run --rm aquasec/trivy image <image-name>`
+- **All platforms**: See [aquasecurity/trivy installation docs](https://aquasecurity.github.io/trivy/latest/getting-started/installation/)
+
+## Grype
+
+Grype scans container images and filesystems for known vulnerabilities using Anchore's database.
+
+- **macOS**: `brew install grype`
+- **Linux / macOS** (install script):
+  ```bash
+  curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin
+  ```
+- **Docker** (no install): `docker run --rm anchore/grype:latest <image-name>`
+- **All platforms**: See [anchore/grype installation docs](https://github.com/anchore/grype#installation)
+
+## Verify installation
+
+```bash
+command -v hadolint && command -v trivy && command -v grype
+```
+
+If all three are installed, this prints their paths.

package/skills/docker-image-audit/references/report-template.md

@@ -0,0 +1,73 @@
+# Docker Audit Report Template
+
+Use this structure when writing the report file. Replace placeholders with actual findings.
+
+```markdown
+# Docker Image Audit Report
+
+**Image**: <image-name-or-dockerfile-path>
+**Date**: <date>
+**Tools**: hadolint <version>, Trivy <version>, Grype <version>
+
+## Executive Summary
+
+| Category | Critical | High | Medium | Low | Info |
+|----------|----------|------|--------|-----|------|
+| Dockerfile issues (hadolint) | X | X | X | X | X |
+| Structural issues (manual) | X | X | X | X | - |
+| OS vulnerabilities (Trivy) | X | X | X | X | - |
+| OS vulnerabilities (Grype) | X | X | X | X | - |
+| App dependency vulnerabilities | X | X | X | X | - |
+| Image size & efficiency | - | X | X | X | - |
+| **Total** | **X** | **X** | **X** | **X** | **X** |
+
+**Image size**: XXX MB
+**Recommended target**: XXX MB (using <recommended-base>)
+**Non-root user**: Yes/No
+**Health check**: Present/Missing
+
+## Critical and High Findings
+
+### [SEVERITY] Finding title
+- **Source**: hadolint/Trivy/Grype/structural
+- **Rule/CVE**: DL3006 / CVE-2024-XXXXX
+- **Component**: package name and version
+- **Description**: What the vulnerability or issue is
+- **Fix**: Specific action to take (show before/after for Dockerfile changes, version to upgrade to, or mitigation if no fix available)
+
+## Medium and Low Findings
+
+Same structure, grouped by category for readability.
+
+## Image Size Analysis
+
+### Current Layer Breakdown
+| Size | Layer |
+|------|-------|
+| XX MB | RUN apt-get install ... |
+| XX MB | COPY . . |
+
+### Size Reduction Recommendations
+1. Recommendation with estimated size savings
+
+## Cross-Validation Summary
+
+Findings detected by both Trivy and Grype have high confidence.
+Findings detected by only one scanner should be investigated but may be false positives.
+
+| CVE | Trivy | Grype | Confidence |
+|-----|-------|-------|------------|
+| CVE-2024-XXXXX | Yes | Yes | High |
+| CVE-2024-YYYYY | Yes | No | Medium |
+
+## Recommended Dockerfile Changes
+
+Group changes by priority:
+
+1. **Separation of concerns** (move CI/CD steps out of Dockerfile)
+2. **Security fixes** (secrets to BuildKit mounts, non-root user, TLS, base image)
+3. **Vulnerability remediation** (package upgrades, base image swap)
+4. **Build correctness** (Debug/Release mismatch, remove post-build workarounds)
+5. **Cache & size optimization** (COPY ordering, .dockerignore, layer consolidation, distroless)
+6. **Best practices** (HEALTHCHECK, labels, WORKDIR, dead stage cleanup)
+```

package/skills/docker-image-create/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: docker-image-create
+description: Generate production-ready Dockerfiles from project source code. Detects language/framework automatically and produces multi-stage builds with minimal, distroless, or slim base images. Use this skill whenever the user wants to containerize an application, create a Dockerfile, dockerize a project, build a Docker image, or says things like "make this run in Docker", "create a container for this app", "I need a Dockerfile", "package this for deployment", or "containerize this service". Also trigger when the user has an existing Dockerfile and wants it rewritten for production use, or when they ask about Docker best practices for their project.
+role: worker
+user-invocable: true
+---
+
+# Docker Image Creation
+
+Generate production-ready Dockerfiles by analyzing language, framework, and dependencies. Output is a multi-stage build optimized for small image size, fast builds, and minimal attack surface.
+
+**Default base image strategy**: distroless when possible (only the app and its runtime — no shell, no package manager, no OS utilities; minimal CVE exposure). Fall back to slim (`node:22-slim`, `python:3.12-slim`) when the runtime needs OS-level libraries or a shell for debugging.
+
+## Workflow
+
+### Step 1: Detect the project
+
+Scan the project root to identify:
+
+1. **Language + version** (from version files / configs):
+   - `package.json` (Node.js — `engines.node`)
+   - `go.mod` (Go — `go` directive)
+   - `requirements.txt` / `pyproject.toml` / `Pipfile` (Python — `python_requires` / `.python-version`)
+   - `pom.xml` / `build.gradle{,kts}` (Java/Kotlin — `sourceCompatibility`)
+   - `*.csproj` / `*.fsproj` (C#/F# — `TargetFramework`)
+   - `mix.exs` (Elixir), `Gemfile` (Ruby)
+
+2. **Framework** (drives build command + output structure):
+   - Node.js: Next.js, Remix, Express, Fastify, NestJS, Astro, SvelteKit
+   - Python: FastAPI, Flask, Django
+   - Go: net/http, Gin, Echo, Fiber
+   - Java: Spring Boot, Quarkus, Micronaut
+   - .NET: ASP.NET Core, Blazor, gRPC, minimal APIs
+
+3. **Package manager** (drives install command):
+   - Node.js: npm (`package-lock.json`), yarn (`yarn.lock`), pnpm (`pnpm-lock.yaml`), bun (`bun.lockb`)
+   - Python: pip (`requirements.txt`), poetry (`poetry.lock`), pipenv (`Pipfile.lock`), uv (`uv.lock`)
+
+4. **Entry point**: `package.json` `scripts.start` / `main`, `Procfile`, existing Dockerfile `CMD`, or framework convention (`main.go`, `app.py`, `Application.java`).
+
+5. **Existing Docker artifacts**: `.dockerignore`, existing `Dockerfile`, `docker-compose.yml`.
+
+Present a detection summary to the user and ask: "Want me to adjust anything before generating?"
+
+### Step 2: Ask about registry and build tools
+
+Ask:
+
+1. **Container registry?** (Docker Hub, ghcr.io, ECR, GCR, ACR) — affects `FROM` paths and login steps.
+2. **Build tool?** Default: BuildKit (`DOCKER_BUILDKIT=1`). Enables cache mounts, secret mounts, and parallel stages.
+3. **Generate `.dockerignore`?** If missing or sparse.
+4. **Generate `docker-compose.yml`?** For local development.
+
+Proceed with sensible defaults if the user says "just go with defaults."
+
+### Step 3: Generate the Dockerfile
+
+**Layer order** (least-changed → most-changed) for cache efficiency: base image → system deps → dependency manifest + install → source code → build → final stage with only the runtime artifact.
+
+**Cache-friendly install** — copy manifests first, install, then copy source:
+
+```dockerfile
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+```
+
+Never `COPY . .` before install — busts the cache on every source change.
+
+**Stages**: `deps` (install) → `build` (compile/bundle) → `runtime` (minimal base with artifact only). Two stages suffice for interpreted languages without a build step.
+
+**Base image table**:
+
+| Language | Build stage | Runtime stage |
+|---|---|---|
+| Go | `golang:<version>` | `gcr.io/distroless/static-debian12` |
+| Java | `eclipse-temurin:<version>` | `gcr.io/distroless/java21-debian12` |
+| Node.js | `node:<version>` | `node:<version>-slim` or `gcr.io/distroless/nodejs22-debian12` |
+| Python | `python:<version>` | `python:<version>-slim` |
+| .NET | `mcr.microsoft.com/dotnet/sdk:<version>` | `mcr.microsoft.com/dotnet/aspnet:<version>-alpine` |
+
+Pin major.minor (e.g., `node:22.12`, not `node:latest`). Digest-pin only for high-security environments.
+
+**Security defaults**:
+- Run as non-root in the final stage (`USER nonroot` for distroless; create a user for slim bases)
+- Never copy `.env`, secrets, or credentials into the image
+- Use `--frozen-lockfile` / `--ci` for reproducible installs
+- Set `NODE_ENV=production` or equivalent
+- Use `COPY --chown` to set ownership without running as root
+
+**Health checks** (when the app exposes HTTP):
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD ["wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"] || exit 1
+```
+
+Distroless images lack `wget`/`curl` — skip HEALTHCHECK and rely on the orchestrator (Kubernetes liveness probes etc.).
+
+**OCI labels**:
+
+```dockerfile
+LABEL org.opencontainers.image.source="https://github.com/OWNER/REPO"
+LABEL org.opencontainers.image.description="Brief description"
+```
+
+### Step 4: Generate .dockerignore
+
+If absent or sparse, write one tailored to the detected language. Common patterns:
+
+```
+.git
+.github
+node_modules
+dist
+build
+*.md
+.env*
+.vscode
+.idea
+Dockerfile*
+docker-compose*
+.dockerignore
+coverage
+.nyc_output
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+bin/
+obj/
+```
+
+Drop language-irrelevant patterns (no Python patterns for a Go project).
+
+### Step 5: Generate docker-compose.yml (if requested)
+
+Development-focused: volume mounts for live reload, port mappings, env-file references, dependent services (database, cache) if detected.
+
+### Step 6: Provide build and run instructions
+
+```bash
+docker build -t my-app .
+docker run -p 3000:3000 my-app
+
+# With BuildKit
+DOCKER_BUILDKIT=1 docker build -t my-app .
+```
+
+Include framework-specific notes (e.g., Next.js standalone mode requires `output: 'standalone'` in `next.config.js`).
+
+## Language-specific patterns
+
+### Node.js / Next.js (standalone)
+- `--frozen-lockfile` for reproducible installs
+- For Next.js: enable standalone output and copy `.next/standalone` + `.next/static` + `public/`
+- Set `NODE_ENV=production` before the build step (for tree-shaking)
+- Use the `node` user (built-in to slim images)
+
+### Go
+- `CGO_ENABLED=0` for fully static binaries (works with distroless/static)
+- Copy only the binary to the final stage
+- Use scratch or distroless/static — Go binaries are self-contained
+- Strip debug info: `GOFLAGS="-trimpath"` + `-ldflags="-s -w"`
+
+### Python
+- `--no-cache-dir` with pip (don't bake wheels into the image)
+- Poetry: export to requirements.txt in the build stage, pip-install in runtime
+- `--no-install-recommends` for `apt-get`
+- Consider `uv` for faster installs
+
+### C# / .NET
+- Build stage `mcr.microsoft.com/dotnet/sdk:<version>`; runtime `mcr.microsoft.com/dotnet/aspnet:<version>-alpine`
+- Restore first for cache efficiency: `COPY *.csproj ./` → `dotnet restore` → copy source → `dotnet publish`
+- `dotnet publish -c Release -o /app --no-restore` (skip redundant restore)
+- Self-contained: `dotnet publish -c Release --self-contained -r linux-musl-x64 -p:PublishTrimmed=true`
+- Globalization invariant if no culture-specific formatting: `ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=true` (saves ~30MB)
+- Multi-project solutions: copy all `.csproj` preserving structure, restore, copy everything, publish entry-point project
+- `USER app` (built-in non-root in .NET 8+), `ASPNETCORE_URLS=http://+:8080` (default for non-root)
+
+### Java (Spring Boot)
+- Layered jars: `java -Djarmode=layertools -jar app.jar extract`; copy dependencies, spring-boot-loader, snapshot-dependencies, application as separate layers
+- `jlink` for custom minimal JRE
+- `-XX:+UseContainerSupport` for correct memory detection in containers

package/skills/domain-analysis/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: domain-analysis
+description: Strategic DDD health assessment of an existing system. Use whenever someone asks to analyze their architecture, assess domain health, find coupling problems, map bounded contexts, trace event flows across services, or understand what is slowing down delivery. Trigger on phrases like "what's wrong with our architecture", "where is the coupling", "assess our domain", "event storming", "value stream", "friction report", "bounded contexts", or "why is everything so tangled". Apply to existing codebases — use domain-driven-design skill for greenfield modeling.
+role: worker
+user-invocable: true
+---
+
+# Domain Analysis
+
+Role: worker. This command produces a domain-health report — it is analytical,
+not prescriptive; it does not redesign code or write implementation.
+
+## Overview
+
+Assess the domain health of an existing multi-component system. Produce a structured report covering bounded context boundaries, context map relationships, domain event flows, value stream throughput, and a friction report identifying where the architecture inhibits continuous delivery.
+
+This skill is analytical, not prescriptive. It describes what *is*, not what should be built. For greenfield design, use `skills/domain-driven-design/SKILL.md`. For code-level violations (anemic model, missing DTOs, wrong layer), use `agents/domain-review.md`.
+
+## Scope
+
+Before starting, determine scope from the user's request:
+
+- **Single repo**: analyze folder structure, package boundaries, shared models
+- **Multi-repo / microservices**: analyze service boundaries, shared libraries, event contracts, API dependencies
+
+## Evidence requirement
+
+Every finding must be grounded in something you actually read. When reporting a God Object, a missing ACL, a coupling trap, or a friction item, cite the specific `file:line` or `file` where the evidence was observed. Do not assert that a pattern exists based on naming conventions alone — open the file and confirm it.
+
+Classify each finding by confidence:
+
+- **observed** — directly visible in a file you read (an import statement, a shared type, a method call)
+- **inferred** — visible at folder or module level without reading implementation (directory name, package dependency in package.json)
+- **suspected** — requires runtime knowledge or cannot be confirmed from static analysis alone
+
+**Graph-assisted evidence gathering.** Prefer CodeGraph/Repowise over raw `Grep`
+for tracing imports, call relationships, and cross-context dependencies — they're
+cheaper and more accurate than re-deriving the call graph from text search. See
+[`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md)
+for tool selection and the fallback contract.
+
+## Analysis Framework
+
+### 1. Bounded Context Identification
+
+Start here — structure reveals intent without reading implementation. Look at folder names, module names, and package boundaries first, then confirm with data schemas.
+
+- Derive contexts from top-level folders, packages, or service names
+- Flag **God Objects**: types that appear in multiple components under different meanings (e.g., `User` in Auth, Orders, and Billing with diverging fields) — these signal missing context boundaries
+- Identify whether each context owns its model exclusively or borrows from neighbors
+- A God Object is only a problem if its semantics diverge across contexts; the same name with the same meaning is fine
+
+### 2. Context Mapping
+
+For each inter-context relationship, classify the integration pattern. This matters because the pattern determines who can change what without coordinating with a neighbor.
+
+| Pattern | Signal in code |
+| --- | --- |
+| **Anti-Corruption Layer** | Translator/mapper class at the boundary; explicit model conversion |
+| **Shared Kernel** | Shared library or package co-owned by two contexts |
+| **Customer/Supplier** | Downstream negotiates with upstream via contracts or versioned APIs |
+| **Conformist** | Downstream uses upstream's model with no translation |
+| **Open Host Service** | Published protocol (REST, gRPC, event schema) consumed by many |
+| **Separate Ways** | No code path between two contexts that a naive reading would expect to integrate — sometimes deliberate and correct, not always a gap |
+
+Flag missing ACLs: direct dependencies between contexts that pass domain objects across boundaries without translation. These are the highest-risk coupling points — a schema change in one context silently breaks another.
+
+### 3. Behavioral Event Storm
+
+Domain events are the seams that let contexts evolve independently. Missing events are missing seams.
+
+- Identify Domain Events: past-tense named events (`OrderPlaced`, `InventoryReserved`) crossing component boundaries
+- Trace each event: which component emits it, which consume it, and whether consumers react synchronously or asynchronously
+- Flag events that are missing (cross-boundary state changes with no event) or implicit (direct method calls that should be events)
+
+### 4. Value Stream Flow
+
+Trace a single unit of value through the system. Begin from a specific entrypoint you can point to in the code (e.g., a CLI command, an HTTP handler, a message consumer) — name it explicitly. Do not construct a hypothetical flow; trace the actual one.
+
+- Identify the happy path: ordered sequence of component handoffs from entrypoint to outcome
+- Flag synchronous handoffs where async would decouple the components (latency and availability risk)
+- Flag handoffs with high coupling: caller must know too much about the downstream component's internals
+- Identify missing compensating actions for failure mid-stream (e.g., payment charged but order not created)
+
+### 5. Coupling Trap Detection
+
+Identify feedback loops and cascading-change risks — the architectural patterns that make every deploy a coordination exercise.
+
+- **Circular dependencies**: Component A depends on B, B depends on A (directly or transitively)
+- **Coupling traps**: a change to one component's domain model forces breaking changes in others — signals missing abstraction or a misplaced boundary
+- **Shared mutable state**: two contexts writing to the same tables or caches without clear ownership
+
+### 6. Core Domain Distillation
+
+Where is the team's modeling effort actually going, and does that match where the value is? This is the strategic prioritization lens — it tells you where deeper design pays off and where it is waste.
+
+Classify each bounded context:
+
+| Class | Signal | What it means |
+| --- | --- | --- |
+| **Core** | Bespoke, frequently-changed business logic central to why the product exists | Invest the best design here |
+| **Supporting** | Business-specific but not differentiating | Build simply; adequate is fine |
+| **Generic** | Solved problems — auth, notifications, currency, scheduling, file storage | Buy/adopt; custom code here is usually waste |
+
+Flag **effort misallocation** — the friction this lens exists to find:
+
+- **Over-built generic**: an elaborate custom model in a Generic subdomain (a hand-rolled auth/permissions engine, a bespoke job scheduler) — candidates to replace with a library or service
+- **Neglected Core**: the context most central to the business is the most anemic or tangled — the strongest design investment is going to the wrong place
+- Classification is a judgment call; mark it `suspected` unless commit frequency or bespoke complexity makes it `observed`
+
+## Steps
+
+1. Map bounded contexts from directory structure and naming conventions
+2. Identify God Objects spanning multiple contexts — open files to confirm semantic divergence
+3. Chart context relationships using the integration pattern table
+4. Locate missing ACLs by reading import statements across context boundaries
+5. Run the event storm: list events, emitters, and consumers
+6. Identify the value stream entrypoint in code; trace the happy path step by step
+7. Identify coupling traps and circular dependencies
+8. Classify each context as Core / Supporting / Generic; flag effort misallocation
+9. Write the Friction Report
+
+## Output
+
+### Bounded Contexts
+
+Table: context name, owning file/package, primary aggregate or concern, upstream/downstream relationships.
+
+### God Objects
+
+List each: type name, contexts it appears in, diverging semantics, evidence (`file:line`). Omit types that appear in multiple places with consistent meaning.
+
+### Context Map
+
+Table of context relationships and their integration patterns. Flag missing ACLs with ⚠ and cite the import or call that crosses the boundary without translation.
+
+### Domain Event Inventory
+
+Table: event name, emitting context, consuming contexts, sync/async. If no domain events exist, say so explicitly — do not omit the section.
+
+### Value Stream
+
+State the entrypoint (file and function/command). Then list the ordered handoffs with coupling severity (low / medium / high) and confidence tier.
+
+### Subdomain Classification
+
+Table: context name, class (Core / Supporting / Generic), evidence for the class, confidence tier. Add a one-line Domain Vision for the context judged Core. Flag any over-built Generic or neglected Core as a Friction Report item with the `effort-misallocation` category.
+
+### Friction Report
+
+Each item: category tag, specific files/components involved, confidence tier, and a concrete fix direction. Use this format:
+
+```
+[category] file-a → file-b (confidence: observed)
+Description of the coupling or gap.
+Fix: <specific action, e.g., "introduce ACL", "extract context", "replace sync call with domain event">
+```
+
+Categories: `deployment-coupling` | `data-coupling` | `semantic-coupling` | `event-gap` | `effort-misallocation`
+
+**Example:**
+
+```
+[semantic-coupling] output.ts → enricher.ts (confidence: observed, output.ts:3)
+output.ts imports classifyDDD() from enricher.ts — business logic that runs at render time
+belongs in the enrichment phase. This creates a reverse dependency: Output depends on
+Enrichment internals.
+Fix: run classifyDDD during enrichment and store results on contextMap.dddInsights;
+output.ts reads the pre-computed field.
+```
+
+## Constraints
+
+- Do not redesign. Describe what exists; note what is missing.
+- Do not flag code-level violations — those belong to `agents/domain-review.md`
+- Scope coupling trap findings to cross-context boundaries; intra-context coupling is out of scope
+- **Do not reframe infrastructure as a domain.** CI/CD stages, Terraform modules, deploy scripts, and Makefiles are not bounded contexts or aggregates. If no application logic exists, the skip applies regardless of how the concern layers are labeled.
+
+## Guidelines
+
+- Start with folder/package structure before reading any code — structure reveals intended boundaries
+- Friction Report items must cite the specific file (and line if possible) where the coupling is observable
+- If the system has no domain model (pure infrastructure, scripts, configs, build tools), return a brief note — two to three sentences — explaining that and skip the full report. Do not produce an "operational domain" or "infrastructure domain" analysis in its place.