bigpowers 2.2.0 → 2.4.0

package/.pi/skills/model-domain/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: model-domain
+description: "Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates specs/tech-architecture/tech-stack.md and specs/adr/ inline as decisions crystallise. Use when user wants to stress-test a plan against their project's domain language and documented decisions."
+---
+
+
+# Model Domain
+
+**Distinct from `define-language` and `deepen-architecture`:** Use this skill to stress-test a plan through a grilling interview that resolves domain model decisions and captures invariants. Use `define-language` to produce a canonical glossary of terms. Use `deepen-architecture` to find module-level refactoring opportunities in code.
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+> **HARD GATE** — Capture invariants (what MUST always be true) and state machines (what transitions are legal) for core entities. If these are fuzzy, design will fail.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## Domain awareness
+
+During codebase exploration, also look for existing documentation:
+
+### File structure
+
+Most repos have a single context:
+
+```
+/
+├── specs/
+│   ├── CONTEXT.md
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `specs/tech-architecture/tech-stack.md` exists, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── specs/
+│   ├── CONTEXT-MAP.md
+│   └── adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   └── specs/
+    │       ├── CONTEXT.md
+    │       └── adr/                  ← context-specific decisions
+    └── billing/
+        └── specs/
+            ├── CONTEXT.md
+            └── adr/
+```
+
+Create files lazily — only when you have something to write. If no `specs/tech-architecture/tech-stack.md` exists, create it when the first term is resolved. If no `specs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `specs/tech-architecture/tech-stack.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update specs/tech-architecture/tech-stack.md inline
+
+When a term is resolved, update `specs/tech-architecture/tech-stack.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+Don't couple `specs/tech-architecture/tech-stack.md` to implementation details. Only include terms that are meaningful to domain experts.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+
+## Concurrency safety audit
+
+When the plan touches shared state, async, or multi-threaded code:
+
+- [ ] List every **shared mutable** location (globals, singletons, module-level caches).
+- [ ] For each: who reads, who writes, synchronization mechanism (lock, actor, immutable copy).
+- [ ] Flag **race risks** (check-then-act, non-atomic read-modify-write) with severity.
+- [ ] Record findings in `specs/tech-architecture/tech-stack.md` under `## Concurrency` or in an ADR if architectural.
+
+---
+
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.
+
+---
+
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+A customer's request to purchase one or more items.
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+- An **Invoice** belongs to exactly one **Customer**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/.pi/skills/orchestrate-project/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: orchestrate-project
+description: "Meta-skill that enforces the 6-phase core loop (discover → elaborate → plan → build → verify → release) with hard gates. Use to coordinate multi-phase projects with guaranteed quality checkpoints. One-time command for the entire project lifecycle."
+---
+
+
+# Orchestrate
+> **HARD GATE** — **HARD GATE** — Do NOT invoke orchestrate-project unless you have a clear multi-phase workflow. Single-skill tasks should use dedicated skills instead. Orchestrate is for complex, multi-stage work that requires coordination across phases.
+
+
+The orchestrate skill coordinates projects through a prescriptive 6-phase core loop with hard gates, ensuring consistent quality and preventing scope creep.
+
+## Quick Start
+
+```bash
+# Start a new project (initializes specs/ YAML cockpit and begins discover phase)
+claude /orchestrate --mode standard
+
+# Or resume an existing project at the current phase
+claude /orchestrate --mode standard --resume
+
+# For low-risk scenarios (hotfixes, refactors on well-tested code)
+claude /orchestrate --mode fast-track
+```
+
+## The 6-Phase Core Loop
+
+1. **DISCOVER** (3-6 hours): Understand problem. Deliverables: `requirements/VISION_LATEST.yaml`, `requirements/SCOPE_LATEST.yaml`, `plans/TECH_STACK_LATEST.md`.
+2. **ELABORATE** (3-6 hours): Research solutions. Deliverables: Prior art in scope YAML, ADRs in `specs/adr/`.
+3. **PLAN** (2-4 hours): Write verifiable plan. Deliverables: `release-plan.yaml`, `epics/eNN-*.yaml` with `verify:` per task.
+4. **BUILD** (1-8 hours): Execute plan. Runs build-epic once per story in WSJF order. Deliverables: Code; update `execution-status.yaml`.
+5. **VERIFY** (1-3 hours): Validate success criteria. Deliverables: UAT evidence, `specs/EVALS-*.md` if used.
+6. **RELEASE** (30 min - 2 hours): Ship to production. Deliverables: Release tag (vX.Y.Z), `state.yaml` `release.last_tag`.
+
+See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate types.
+
+## How Orchestrate Works
+
+1. **Maintains state.yaml** — Tracks current phase, `active_epic`, `active_flow`, decisions, risks.
+2. **Spawns appropriate skills** — Routes by `model:` frontmatter. Decisions pass only via `specs/state.yaml` `handoff` between spawns.
+3. **Methodology lenses** — If `specs/tech-architecture/test.md` or ADRs exist, apply at phase gates.
+4. **Enforces gates** — Hard stops if success criteria not met.
+5. **The Gatekeeper** — Between stories in BUILD: read `specs/execution-status.yaml`; previous story must be `done` before starting the next; use `build-epic` for the 8-step epic cycle.
+6. **Pauses for confirmation** — After each phase, asks "Ready to proceed?".
+7. **Snapshots** — `bash scripts/bp-yaml-snapshot.sh` before major release cuts.
+
+## Orchestration Modes
+
+- **Standard**: Enforce all gates. Use for new features and major refactors.
+- **Fast-Track**: Skip negotiable gates. Use for hotfixes and minor improvements.
+- **Ad-Hoc**: Warnings only. Use for prototyping and spikes (non-production).
+
+See [REFERENCE.md](REFERENCE.md) for full mode behaviors.
+
+## Verification
+
+All phases complete with artifacts:
+```bash
+verify: test -f specs/state.yaml && test -f specs/release-plan.yaml && test -f specs/product/SCOPE_LATEST.yaml && ls specs/epics/*.yaml 1>/dev/null && echo "✅ All phases complete"
+```
+
+---
+
+# Orchestrate Reference: Phases, Modes, and Workflows
+
+Detailed documentation for the `orchestrate-project` meta-skill.
+
+## The 6-Phase Core Loop
+
+### PHASE 1: DISCOVER
+- **Goal**: Understand the problem completely and map existing context.
+- **Deliverables**: `requirements/VISION_LATEST.yaml`, `requirements/SCOPE_LATEST.yaml`, `plans/TECH_STACK_LATEST.md`.
+- **Skills**: `survey-context`, `elaborate-spec`, `grill-me`.
+- **Gate**: Confirm ("Is the problem clear?").
+
+### PHASE 2: ELABORATE
+- **Goal**: Research solutions and lock architectural design.
+- **Deliverables**: Prior art in scope YAML, ADRs in `specs/adr/`.
+- **Skills**: `grill-me`, `model-domain`, `define-language`, `deepen-architecture`, `design-interface`.
+- **Gate**: Quality ≥94% (via `request-review`) + Confirm ("Are decisions locked?").
+
+### PHASE 3: PLAN
+- **Goal**: Write a verifiable implementation plan with success criteria.
+- **Deliverables**: `release-plan.yaml`, `epics/eNN-*.yaml` with `verify:` per task.
+- **Skills**: `scope-work`, `slice-tasks`, `define-success`, `plan-work`.
+- **Gate**: Quality (request-review ≥94%) + slopcheck [SUS]/[SLOP].
+
+### PHASE 4: BUILD
+- **Goal**: Execute the plan story-by-story using the 8-step `build-epic` cycle with TDD and vertical slices.
+- **Deliverables**: Code; `execution-status.yaml` updated per story; `specs/metrics/cycle-times.yaml` row per story.
+- **Skills**: `build-epic` (conductor) → per-story: `survey-context`, `plan-work`, `kickoff-branch`, `develop-tdd`, `verify-work`, `audit-code`, `commit-message`, `release-branch`.
+- **BCP tracking**: `plan-release` sizes each story in Business Complexity Points (BCP) before the build queue; `plan-work` confirms and writes the size to `state.yaml` as `epic_cycle.story_bcps`. See `docs/references/bcp.md` for the canonical sizing method.
+- **Timestamps**: `survey-context` stamps `metrics.story_start`; `release-branch` stamps `metrics.story_end` and writes BCP/hr to `specs/metrics/cycle-times.yaml`.
+- **next_skill**: Each critical-path skill writes `handoff.next_skill` to `state.yaml`. Agents resume by reading `state.yaml` — no guessing.
+- **Dashboard**: `npm run dashboard` (TUI) or `npm run dashboard:web` (browser, port 7742) shows live pipeline, epic queue, BCP metrics, and cycle-time ledger.
+- **Gate**: Integration tests PASS; all 8 build-epic steps completed per story.
+
+### PHASE 5: VERIFY
+- **Goal**: Validate success criteria and ensure production readiness.
+- **Deliverables**: UAT evidence, eval results.
+- **Skills**: `run-evals`, `verify-work`, `audit-code`, `request-review` (optional).
+- **Gate**: Verification Script confirmed; `verify-work` not on `main`/`master`.
+
+### PHASE 6: RELEASE (Integrate)
+- **Goal**: Ship to `main` with full traceability.
+- **Deliverables**: Release tag (vX.Y.Z), release notes via semantic-release.
+- **Skills**: `commit-message`, `release-branch`.
+- **Git arc**:
+  1. Plan on `main` (Discover / Plan)
+  2. `kickoff-branch` → worktree + feature branch + clean baseline
+  3. Build / Verify / Review on feature branch
+  4. Integrate: **solo-local** (`scripts/land-branch.sh`) or **team-pr** (`gh pr create` → squash merge)
+  5. Cleanup worktree; **end on `main`** in primary repo root
+- **Gate**: Safety ("About to land on main. Confirm?").
+
+---
+
+## Orchestration Modes
+
+### Mode 1: Standard (Enforce All Gates)
+**Use Case**: New features, major refactors, architectural changes.
+**Behavior**:
+- All Confirm gates require explicit user approval.
+- All Quality gates are hard stops if threshold is not met.
+- No shortcuts or phase skipping.
+
+### Mode 2: Fast-Track (Skip Negotiable Gates)
+**Use Case**: Hotfixes, minor improvements, refactors on well-tested code.
+**Behavior**:
+- Skip Discover if `requirements/SCOPE_LATEST.yaml` exists.
+- Skip Elaborate if design decisions are already locked.
+- Skip Verify if coverage ≥95% + all tests PASS.
+- Soft gates auto-approve if baseline conditions are met.
+
+### Mode 3: Ad-Hoc (Legacy, Warnings Only)
+**Use Case**: Exploration, prototyping, spikes (NOT for production).
+**Behavior**:
+- Gates emit warnings but do not block execution.
+- User can manually skip any phase.
+- No enforced quality thresholds.
+
+---
+
+## Gate & Checkpoint Types
+*See `docs/references/gates.md` and `docs/references/checkpoints.md` for full specs.*
+
+- **Confirm**: Requires human "yes/no" decision.
+- **Quality**: Automated threshold check (e.g., coverage, audit score).
+- **Safety**: Destructive actions require risk acknowledgment.
+- **Transition**: Mandatory artifact presence check.
+- **slopcheck**: Identification of [SUS] (Suspicious) or [SLOP] (High-risk) packages.
+
+---
+
+## Error Recovery & State
+Orchestrate maintains `specs/state.yaml` to track:
+- **Current flow / epic**: `active_flow`, `active_epic_id`, `epic_cycle`.
+- **Handoff**: `last_step_completed`, `open_decisions`, `required_reading`, `next_skill`.
+- **Git**: `branch`, `hash` for session continuity.
+- **Progress**: Story status lives in `execution-status.yaml` only.
+
+In the event of a crash or exit, run `claude /orchestrate --resume` to pick up exactly where the session left off.

package/.pi/skills/organize-workspace/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: organize-workspace
+description: "Scans the active workspace for disposable artifacts—logs, caches, stale build output, and stray draft markdown—and proposes consolidation of scattered assets. Produces a reviewable list, asks for explicit confirmation before any delete or move, and optionally revises .gitignore. Use when the user says "clean my room", "organize workspace", "workspace cleanup", "remove temp files", "organize assets", "gitignore", or wants a safe tidy pass."
+---
+
+
+# Organize Workspace
+> **HARD GATE** — **HARD GATE** — Workspace structure must reflect domain structure. If the codebase feels disorganized, flag it. Disorganization != 'just a style thing;' it is a signal of domain misalignment.
+
+
+## Principles
+
+- **Read-only first**: inventory and size (`du`, `ls -la`) before any change.
+- **Never delete or move** without a numbered list and **explicit user approval** (item-level or "approve all").
+- **Prefer `fd` / `ripgrep` / `find`** in that order; avoid blind `rm -rf` on vague globs.
+- **Do not** touch `.git/`, `node_modules/`, `venv/`, `.env*`, or SSH keys; flag them only if the user asked about them.
+- Confirm prompts in the **user's language** if they are not writing in English.
+
+## 1. Establish scope
+
+- Default: **current project root** (where the user is working) or the path they name.
+- Record OS (macOS vs Linux) for ignore patterns (e.g. `.DS_Store`).
+
+## 2. Classify candidates (scan)
+
+Group findings under these **buckets**:
+
+| Bucket | Examples | Typical action |
+|--------|----------|----------------|
+| **Logs & temp** | `*.log`, `logs/`, `tmp/`, `temp/`, `*.pid` | Delete after confirm |
+| **Build / cache** | `dist/`, `build/`, `.next/`, `coverage/`, `.turbo/` | Delete if rebuildable |
+| **Package caches** | root `.cache/`, `__pycache__/` | Offer delete |
+| **Stray drafts** | root-level `*.md` named `draft`, `scratch`, `temp` | User picks: delete, move to `specs/`, or keep |
+| **Duplicate / dump dirs** | `old/`, `backup/`, `copy/`, `*_backup` | List + ask |
+
+Use quick size hints: `du -sh` per top-level dir; sort large items first.
+
+## 3. Assets & data (organize, not only delete)
+
+If the user wants **organization**:
+
+1. Propose a **single convention**, e.g.:
+   - `assets/` — images, fonts, static media
+   - `data/` — JSON, CSV, fixtures, samples
+   - `specs/` — all planning and domain documents
+2. For each cluster of loose files, suggest **one target path** and a short rationale.
+3. Use **git-aware moves** when in a repo: `git mv` if tracked; otherwise `mv` and report.
+4. Never move secrets or production DB dumps into `docs/` or public `assets/`.
+
+## 4. Present the plan
+
+Output a table or numbered list:
+
+- Path
+- Kind (log / build / draft / asset / other)
+- Approx size
+- Proposed action: **delete** | **move to …** | **keep**
+
+Ask: *"Delete items 1–3? Move 4–5? Skip 6?"*
+
+## 5. Execute after approval
+
+- Deletes: on macOS, prefer a Trash-capable tool (e.g. `trash` from Homebrew) if installed; else `rm` with paths echoed back.
+- Moves: create dirs with `mkdir -p` first; one batch at a time.
+- **Verify**: re-run listing on affected parents; if anything failed, report stderr.
+
+## 6. Post-cleanup and `.gitignore` revision
+
+Do this when the repo is under Git and the cleanup surfaced **untracked** noise:
+
+1. **Inventory ignore sources**: root `.gitignore`, `.git/info/exclude`, any subpackage `.gitignore` files.
+2. **Map findings to rules**: for each deleted or recurring artifact class, check whether a pattern already exists; note gaps.
+3. **Propose a patch**: list only **concrete** changes — `+` add / `-` remove / `~` reword — with one-line why.
+4. **User must approve** the exact diff before editing the file.
+5. **Verify**: run `git check-ignore -v <path>` on 2–3 representative paths.
+
+See [REFERENCE.md](REFERENCE.md) for shell patterns, `.gitignore` mechanics, and safety checks.
+
+---
+
+# clean-my-room — reference patterns
+
+Optional commands for the agent. Adapt paths; **dry-run** before bulk delete.
+
+## Discover large top-level entries
+
+```sh
+du -sh ./* .[!.]* 2>/dev/null | sort -hr | head -30
+```
+
+## Find common logs (respect `.gitignore` when using fd)
+
+```sh
+fd -t f '\.log$' . 2>/dev/null
+fd 'npm-debug' . 2>/dev/null
+```
+
+## Find build-like dirs (review list before `rm -rf`)
+
+```sh
+fd -t d '^(dist|build|out|target|\.next|coverage)$' . --max-depth 3 2>/dev/null
+```
+
+## Stray markdown at repo root (heuristic)
+
+```sh
+ls -1 ./*.md 2>/dev/null
+fd -t f '^(draft|scratch|untitled|TODO|notes)' . --max-depth 1 2>/dev/null
+```
+
+## Git-safe moves
+
+```sh
+git status -sb
+git check-ignore -v <path>   # was ignored?
+# Tracked: git mv old new
+# Untracked: mkdir -p … && mv old new
+```
+
+## `.gitignore` revision (after cleanup)
+
+**Goal:** stop regenerated junk from polluting `git status`, without hiding real source.
+
+1. **Read** root `.gitignore` and, in monorepos, `apps/*/.gitignore` / `packages/*/.gitignore` as needed. Check **`.git/info/exclude`** for machine-only rules that should *not* be committed (keep personal noise there; don’t copy into shared `.gitignore` unless the team agrees).
+2. **Per-path checks** (last match wins; shows which file defined the rule):
+
+   ```sh
+   git check-ignore -v path/to/artifact
+   git status -u --ignored    # optional: see ignored names (noisy)
+   ```
+
+3. **Pattern style**
+   - Leading `/` = relative to the `.gitignore`’s directory (e.g. `/dist/` = only that folder at that level, not all nested `dist` unless intended).
+   - `**` for deep trees, e.g. `**/*.log`, when noise appears at many depths.
+   - **Negation** (`!`) is tricky: later rules, parent dirs, and `git add -f` interact—prefer narrow positive ignores over `!` unless you already use negation in that file.
+4. **Do not** add rules that would ignore: application source, small JSON/YAML config the repo tracks, or `!important` assets. When unsure, run `git check-ignore -v` on a *known good* file that must stay tracked.
+5. **Tracked but should be ignored** (user already committed `build/` once): this skill does not silently fix history; flag `git rm -r --cached <path>` + `.gitignore` as a **separate** explicit step the user must approve.
+6. **Global excludes** (optional heads-up for “why is this still ignored?”):
+
+   ```sh
+   git config --get core.excludesfile
+   ```
+
+## Safety: never pass through these in automated deletes
+
+- `.git/`, `.svn/`, `.hg/`
+- `node_modules/`, `vendor/`, `venv/`, `.venv/`, `__pypackages__/`
+- Files matching `.env`, `.env.*` (except `.env.example` if intentional)
+- `~/.ssh`, `id_rsa*`, `*.pem` inside project trees
+
+## Post-deploy / server-ish extras (name buckets to stack)
+
+- Docker: dangling images/volumes (only if user asked for Docker cleanup; requires `docker` context).
+- CI: `*.log` under `build/`, artifact dirs from previous runs.
+- K8s: local `*.kube`, tmp kubeconfigs—list only; do not delete without confirmation.
+
+## Inspiration
+
+- Same **inventory → plan → confirm → act** flow as [post-deploy environment cleanup](https://mcpmarket.com/tools/skills/post-deploy-environment-cleanup) style workflows.
+- [Agent template public](https://github.com/matsuni-kk/agent_template_public): honor **Flow** (draft) vs **Stock** (stable); do not “clean” user drafts from Flow without explicit approval.

package/.pi/skills/plan-refactor/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: plan-refactor
+description: "Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps."
+---
+
+
+# Plan Refactor
+> **HARD GATE** — **HARD GATE** — Before refactoring, document the current behavior and why it is wrong. Extract one invariant that must be preserved. If you skip this, you will break things you don't expect.
+
+
+Create a detailed refactor plan through a user interview. Save output to `specs/REFACTOR.md`.
+
+## Steps
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Ask whether they have considered other options, and present other options to them.
+
+4. Interview the user about the implementation. Be extremely detailed and thorough.
+
+5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
+
+6. Look in the codebase to check for test coverage of this area. If there is insufficient test coverage, ask the user what their plans for testing are.
+
+7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice: "make each refactoring step as small as possible, so that you can always see the program working."
+
+8. Save the refactor plan to `specs/REFACTOR.md`. Create the `specs/` directory if it doesn't exist.
+
+<refactor-plan-template>
+
+## Problem Statement
+
+The problem that the developer is facing, from the developer's perspective.
+
+## Solution
+
+The solution to the problem, from the developer's perspective.
+
+## Commits
+
+A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
+
+Each commit entry follows this format:
+```
+N. <commit description> → verify: <runnable command>
+```
+
+## Decision Document
+
+A list of implementation decisions that were made:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes, API contracts, specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this refactor.
+
+## Further Notes (optional)
+
+Any further notes about the refactor.
+
+</refactor-plan-template>
+
+After writing `specs/REFACTOR.md`, suggest running `kickoff-branch` next to create a refactor branch.