@minhduydev/mdpi 0.3.0

package/dist/template/.pi/prompts/close.md

@@ -0,0 +1,88 @@
+---
+description: Close the active feature — finalize, clear .active, record outcome
+argument-hint: "[--done | --blocked | --abandoned] [--note <text>] [--help]"
+---
+
+# Close
+
+Finalize the active feature: record its outcome, update `state.md`, and clear `.pi/artifacts/.active`. Use to recover from a dangling `.active` left by a failed/abandoned `/ship`, or to mark a completed feature done without running the full `/ship` review.
+
+## Parse Arguments
+
+| Argument       | Default | Description                                          |
+| -------------- | ------- | --------------------------------------------------- |
+| `--done`       | false   | Mark feature complete (success). Append completion summary to progress.md. |
+| `--blocked`    | false   | Mark feature blocked. Record blocker in state.md.  |
+| `--abandoned`  | false   | Mark feature abandoned. Note reason.               |
+| `--note`       | —       | Free-text reason/note appended to progress.md      |
+| `--help`       | false   | Show this usage                                     |
+
+If no outcome flag is given, ask the user: done / blocked / abandoned?
+
+## Guard Phase
+
+- Read `.pi/artifacts/.active`. If missing → report "No active feature to close." and stop.
+- If `--done` and uncommitted changes exist → warn user, ask: commit first or close anyway?
+- Never delete artifact directories — closing only updates markers and `state.md`.
+
+## Load Skills
+
+| Skill | When | Why |
+|-------|------|-----|
+| `git-workflow-and-versioning` | If uncommitted changes present | Decide commit/stash before closing |
+| `documentation-and-adrs` | If `--done` | Capture a one-line outcome for handoff |
+
+## Phase 1: Capture Outcome
+
+1. Read active slug from `.pi/artifacts/.active`
+2. Append to `.pi/artifacts/$SLUG/progress.md`:
+   ```
+   ## Close — <date>
+   **Outcome:** <done|blocked|abandoned>
+   **Note:** <user note or "" >
+   ```
+3. If `--done`: update `tasks.json` → mark all tasks `completed: true`.
+
+## Phase 2: Update state.md
+
+Update `.pi/templates/state.md` "Recent Completed Work" (or "Blockers" if `--blocked`):
+- Add row: `<slug> | <title> | <date> | <one-line summary>`
+
+## Phase 3: Clear .active
+
+```bash
+: > .pi/artifacts/.active   # truncate to empty (preserves the file)
+```
+
+Do **not** `rm` the file (other tooling may expect it to exist).
+
+## Phase 4: Optional Memory
+
+If `--done` and the outcome is non-trivial, persist a memory entry via the `memory` tool (pi-hermes-memory, action: `add`, target: `failure`, category: `insight`):
+- content: "Feature <slug> closed — <outcome> — <key learning>"
+- (target `failure` holds ALL categorized memories — failure/correction/insight/preference/convention/tool-quirk — not just failures; `insight` = durable learning from completing the feature)
+
+## Stop Conditions
+
+- No active feature → report and stop (not an error)
+- `--done` with uncommitted changes and user declines to commit → stop, don't close
+
+## Phase 5: Report
+
+1. Outcome recorded
+2. state.md updated (which section)
+3. `.active` cleared
+4. Next suggestion: `/status` to confirm, `/create` to start next feature
+
+## Related Commands
+
+| Need              | Command   |
+| ----------------- | --------- |
+| Check state       | `/status` |
+| Start next        | `/create` |
+| Resume (if wrong) | `/ship`   |
+
+## Related Skills
+
+- `git-workflow-and-versioning` — commit/stash discipline before closing
+- `documentation-and-adrs` — outcome capture for handoff

package/dist/template/.pi/prompts/create.md

@@ -0,0 +1,197 @@
+---
+description: Create a specification with PRD, tasks, and workspace setup
+argument-hint: "<description> [--lite] [--dry-run] [--help]"
+---
+
+# Create: $ARGUMENTS
+
+Create a specification (PRD), set up workspace, and define executable tasks — ready for `/plan` or `/ship`.
+
+> **Workflow:** `/init` → **`/create`** → `/plan` (optional) → `/ship`
+
+## Parse Arguments
+
+| Argument        | Default  | Description                               |
+| --------------- | -------- | ----------------------------------------- |
+| `<description>` | required | What to build/fix (quoted string)         |
+| `--lite`        | false    | Force Lite PRD (skip auto-detection)      |
+| `--dry-run`     | false    | Preview research depth and PRD format without writing |
+| `--help`        | false    | Show this usage                           |
+
+## Guard Phase
+
+Before creating, verify:
+- Check `.pi/artifacts/.active` for existing work in progress
+- If active slug exists with a `spec.md`, ask user: continue with `/ship` or start new?
+- Check `git status --porcelain` — if uncommitted changes, ask user to stash, commit, or continue
+- Use `vcc_recall` to search session history for prior decisions on this topic — avoid repeating explored/rejected approaches
+
+## Load Skills
+
+| Skill | When | Why |
+|-------|------|-----|
+| `brainstorming` | Description is vague | Refine into concrete designs before spec |
+| `spec-driven-development` | Always | Convert clarified idea into well-structured PRD |
+| `context-engineering` | Deep or Standard research | Context budget management, selective loading for subagent handoffs |
+| `doubt-driven-development` | Before saving PRD | Adversarial validation — challenge assumptions before committing |
+| `grill-me` | Complex or cross-cutting | Adversarial interrogation of spec decisions |
+
+## Phase 1: Choose Research Depth
+
+Use the same Level 0-3 taxonomy as `/plan` so depth is consistent across commands.
+
+Ask user before spawning agents:
+
+| Level | Name | Description |
+|-------|------|-------------|
+| **0** | Skip | I know the codebase, use existing knowledge (no agents) |
+| **1** | Quick | 1 agent: quick file scan (~30 sec) — single known library |
+| **2** | Standard | 2-3 agents: patterns + tests (~1 min) — choosing between options |
+| **3** | Deep | 3-5 agents: patterns, tests, deps, best practices (~2 min) — complex/cross-cutting |
+
+Default: **Level 2** for new features, **Level 1** for bugfixes, **Level 0** when user says "I know the codebase".
+
+## Phase 2: Gather Context
+
+Based on the Level chosen in Phase 1, spawn agents using `subagent` tool:
+
+**Level 3 (Deep):**
+- 3x subagent with `explore` agent (patterns, tests, deps)
+- 1x subagent with `scout` agent (external best practices)
+- 1x subagent with `review` agent (epic review)
+
+**Level 2 (Standard):**
+- 2x subagent with `explore` agent (patterns, tests)
+- 1x subagent with `scout` agent (external research)
+
+**Level 1 (Quick):**
+- 1x subagent with `explore` agent (patterns)
+
+**Level 0 (Skip):** No agents — use existing knowledge.
+
+## Phase 3: Initialize Workspace
+
+Extract title from `$ARGUMENTS`. Derive a kebab-case slug:
+
+```bash
+SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 ]//g' | tr ' ' '-' | sed 's/--*/-/g; s/^-//; s/-$//')
+mkdir -p ".pi/artifacts/$SLUG"
+echo "$SLUG" > ".pi/artifacts/.active"
+```
+
+> **`.active` convention:** The active slug is written to `.pi/artifacts/.active`. All downstream commands (`/plan`, `/ship`, `/verify`) read this file to know which feature is current.
+
+## Phase 4: Determine PRD Rigor
+
+| Signal | Lite PRD | Full PRD |
+|--------|----------|----------|
+| Scope | Simple, single-concern | Cross-cutting, multi-system |
+| Files affected | 1-3 | 4+ |
+| Research depth | Level 0-1 | Level 2-3 |
+| Logic complexity | Low (single behavior) | High (multi-step, stateful) |
+| `--lite` flag | ✓ | — |
+
+**Auto-detect:** If research was Level 0-1 AND description is a single sentence AND logic complexity is low → default to Lite. `--lite` flag overrides to Lite regardless. File count alone is not enough — a 3-file change with complex stateful logic is Full.
+
+### Lite PRD Format
+
+```markdown
+# [Title]
+
+## Problem
+[1-2 sentences: what's wrong or what's needed]
+
+## Solution
+[1-2 sentences: what to do]
+
+## Affected Files
+- `src/path/to/file.ts`
+
+## Tasks
+- [ ] [Task description] → Verify: `[command]`
+
+## Success Criteria
+- Verify: `npm run typecheck && npm run lint`
+- Verify: `[specific test or check]`
+```
+
+### Full PRD Format
+
+Use the full template from `.pi/templates/prd.md`.
+
+## Phase 5: Write & Validate PRD
+
+Copy and fill the PRD template (lite or full) using context from Phase 2.
+
+**Before saving, verify:**
+- No placeholder text remains
+- Success criteria include `Verify:` commands
+- Technical context references actual `src/` paths
+- Affected files list real paths
+- Each task has verification
+- No implementation code in the PRD
+- No unresolved `[NEEDS CLARIFICATION]` markers
+
+## Phase 6: Create Workspace Branch
+
+```bash
+git status --porcelain
+git branch --show-current
+```
+
+Create feature branch and install deps if needed.
+
+## Phase 7: Leave Task Decomposition to `/plan`
+
+The PRD (Phase 5) contains a high-level **Tasks** outline ( Lite: checklist; Full: the template's Tasks section). Do **not** generate `tasks.json` here — task decomposition into the runtime `tasks.json` format is `/plan`'s job.
+
+**Artifact chain (authoritative):**
+
+```
+/create  → .pi/artifacts/$SLUG/spec.md   (the PRD; high-level task outline only)
+/plan    → .pi/artifacts/$SLUG/plan.md   (authoritative task decomposition)
+         → .pi/artifacts/$SLUG/tasks.json (runtime, derived from plan.md)
+/ship    → reads tasks.json (primary) or plan.md (fallback)
+```
+
+If the user skips `/plan` and goes straight to `/ship` for a Lite PRD, `/ship` derives `tasks.json` from the PRD's task outline on the fly.
+
+## Failure Handling
+
+| Scenario | Action |
+|----------|--------|
+| Active work already exists | Ask user: continue with `/ship` or start new? |
+| Subagent research fails | Retry once with adjusted prompt, then proceed with existing knowledge |
+| PRD validation fails | Fix issues inline, re-validate, max 2 retries |
+| Missing template file | Report exact missing path, suggest running `/init` first |
+| Uncommitted changes in workspace | Ask: stash, commit, or continue? |
+
+## Stop Conditions
+
+- Active slug exists with valid spec → ask: continue existing or start new?
+- PRD has unresolved `[NEEDS CLARIFICATION]` markers → block, resolve first
+- Verification fails 2x on same approach → stop, escalate
+
+## Phase 8: Report
+
+1. Summary: PRD type (Lite/Full), success criteria count, affected files count, task outline count
+2. Branch name and workspace
+3. Artifact location: `.pi/artifacts/$SLUG/spec.md`
+4. Next step: `/plan` (complex — produces `plan.md` + `tasks.json`) or `/ship` (simple Lite — derives `tasks.json` on the fly)
+
+## Related Commands
+
+| Need           | Command      |
+| -------------- | ------------ |
+| Research first | `/research`  |
+| Plan execution | `/plan`      |
+| Ship feature   | `/ship`      |
+| Verify gates   | `/verify`    |
+
+## Related Skills
+
+- `spec-driven-development` — PRD structure and vocabulary concepts used in Phase 5
+- `brainstorming` — idea refinement before spec writing
+- `context-engineering` — subagent context budgets for Phase 2
+- `doubt-driven-development` — adversarial validation in Phase 5
+- `planning-and-task-breakdown` — task decomposition patterns (next step)

package/dist/template/.pi/prompts/fix.md

@@ -0,0 +1,117 @@
+---
+description: Debug and fix a bug or failing test
+argument-hint: "<description of bug or error> [--attach <file>] [--dry-run] [--help]"
+---
+
+# Fix: $ARGUMENTS
+
+Systematically debug and fix the reported issue.
+
+## Parse Arguments
+
+| Argument        | Default  | Description                               |
+| --------------- | -------- | ----------------------------------------- |
+| `<description>` | required | What to fix (bug description, error message, or failing test) |
+| `--attach`      | —        | Path to log file, crash report, or screenshot |
+| `--artifact`   | —        | Write the fix report into the active feature's artifact dir (`.pi/artifacts/$SLUG/fix.md`) if `.active` exists |
+| `--dry-run`     | false    | Diagnose and report root cause without applying fix |
+| `--help`        | false    | Show this usage                           |
+
+## Guard Phase
+
+Before fixing:
+- Use `vcc_recall` to search for prior fix attempts on the same issue — avoid repeating failed approaches
+- Check that the codebase builds/tests pass at baseline (confirm the bug is not a pre-existing state)
+
+## Load Skills
+
+| Skill | When | Why |
+|-------|------|-----|
+| `root-cause-tracing` | Always | Trace bug backward through call stack to source |
+| `debugging-and-error-recovery` | Always | Systematic 5-step triage: reproduce → localize → reduce → fix → guard |
+| `verification-before-completion` | Always | Evidence-before-claims; verify fix actually resolves the bug |
+| `defense-in-depth` | After fix is verified | Harden the layer so the bug becomes structurally impossible |
+| `testing-anti-patterns` | If writing tests | Ensure regression test isn't a mock-only test |
+
+## Phase 1: Reproduce
+
+Reproduce the issue with the exact steps or command. Use the project's test command:
+
+```bash
+npm test -- -t "<test name pattern>"   # or equivalent
+```
+
+If `--attach` provided, read the attached log/error file for context.
+
+## Phase 2: Isolate
+
+1. Search for the error message or symptom using `semantic_grep`
+2. Trace the execution path to find the root cause using `semantic_inspect`
+3. Read the 2-4 most relevant files
+4. Distinguish symptom from root cause — follow `root-cause-tracing` skill methodology
+
+## Phase 3: Fix
+
+1. Apply the **minimal** fix for the root cause
+2. Do not add speculative guards, tolerant readers, or defensive copies
+3. Prefer making the bad state impossible over handling all bad states (`defense-in-depth`:
+   validate at the layer where invalid data enters)
+
+## Phase 4: Verify
+
+Run verification gates:
+
+```bash
+npm run typecheck
+npm run lint
+npm test            # or vitest relevant test
+```
+
+**Regression check:** If writing a regression test, verify the red-green cycle:
+1. Write test → run → MUST fail (confirm it catches the bug)
+2. Apply fix → run → MUST pass
+3. Revert fix → run → MUST fail again → restore fix
+
+Then, load `defense-in-depth` skill and add validation at the data entry layer.
+
+## Failure Handling
+
+| Scenario | Action |
+|----------|--------|
+| Cannot reproduce issue | Report reproduction steps attempted, ask for clarification |
+| Root cause ambiguous | Trace backward through call stack, add instrumentation |
+| Verification fails 2x | Stop, report blocker with learnings from both attempts |
+| Fix causes regression | Revert fix, report regression with evidence |
+
+## Stop Conditions
+
+- Cannot reproduce after 3 attempts → stop, ask for clarification
+- Fix causes regression → revert, report
+- Verification fails 2x on same approach → stop, escalate with learnings
+- Root cause is in third-party dependency → stop, report with upstream reference
+
+## Phase 5: Report
+
+1. Root cause (with file:line)
+2. Fix applied
+3. Verification results (typecheck, lint, test)
+4. Defense-in-depth layer added (if applicable)
+5. What else was considered and rejected
+
+If `--artifact` was passed (or `.pi/artifacts/.active` exists and the fix belongs to that feature), write the report to `.pi/artifacts/$SLUG/fix.md` and append a one-line summary to `progress.md`. Otherwise report inline.
+
+## Related Commands
+
+| Need           | Command      |
+| -------------- | ------------ |
+| Create feature | `/create`    |
+| Verify gates   | `/verify`    |
+| Ship fix       | `/ship`      |
+
+## Related Skills
+
+- `root-cause-tracing` — backward call-stack tracing in Phase 2
+- `debugging-and-error-recovery` — full 5-step triage methodology
+- `verification-before-completion` — evidence gate in Phase 4
+- `defense-in-depth` — structural hardening after fix
+- `testing-anti-patterns` — regression test quality

package/dist/template/.pi/prompts/gc.md

@@ -0,0 +1,112 @@
+---
+description: Run garbage collection — Fallow analysis, quality grading, and cleanup PRs
+argument-hint: "[--dry-run] [--scope <dir>] [--help]"
+---
+
+# Garbage Collection
+
+Run structural analysis, update quality grades, and open cleanup PRs.
+
+## Parse Arguments
+
+| Argument    | Default | Description                               |
+| ----------- | ------- | ----------------------------------------- |
+| `--dry-run` | false   | Run analysis and report without creating cleanup PRs (default behavior for cleanup) |
+| `--apply`   | false   | Actually open cleanup PRs for P0/P1 findings. Without this, Phase 4 reports only. |
+| `--scope`   | `.`     | Limit GC to specific directory            |
+| `--help`    | false   | Show this usage                           |
+
+**Safety:** Cleanup PRs require `--apply` **and** explicit user confirmation. Default is dry-run.
+
+## Guard Phase
+
+- GC is maintenance — don't run during active feature work
+- If `.pi/artifacts/.active` exists, warn user: "Active feature in progress. GC changes may conflict."
+
+## Load Skills
+
+| Skill | When | Why |
+|-------|------|-----|
+| `fallow` | Always (Phase 1) | Structural analysis for dead code, duplication, complexity |
+| `code-cleanup` | Phase 4 (cleanup PRs) | Safe code removal patterns |
+| `verification-before-completion` | After cleanup PRs | Verify typecheck + lint pass before merging |
+| `observability-and-instrumentation` | If removing instrumented code | Check that cleanup doesn't break monitoring/logging |
+
+## Execution
+
+This command delegates to the `garbage-collection` workflow via the `run_workflow` tool for multi-phase execution.
+
+### Phase 1: Structural Analysis
+
+1. **Run Fallow scan:**
+   ```bash
+   npx fallow --format json --quiet
+   ```
+2. Extract findings: dead code, duplication, complexity hotspots, unused exports
+
+### Phase 2: Quality Grade Update
+
+1. Read `.pi/QUALITY.md`
+2. Compare with Fallow results
+3. Update quality grades per domain
+4. No change is a valid result — report as-is
+
+### Phase 3: Prioritize Findings
+
+| Severity | Definition | Action |
+|----------|-----------|--------|
+| P0 | Security, crash, data loss | Fix immediately |
+| P1 | Dead code >100 lines, complexity >15 | Fix this cycle |
+| P2 | Dead code <100 lines, minor duplication | Log for next cycle |
+| P3 | Style, naming, formatting | Skip (not GC concern) |
+
+### Phase 4: Cleanup (P0/P1 only)
+
+For each P0/P1 finding:
+1. Invoke cleanup via the workflow (the workflow's Phase 4 defaults to dry-run; pass `--apply` through args to actually open PRs):
+   ```
+   run_workflow({ name: "garbage-collection", args: { scope: "<--scope value or '.'>", apply: <true only if --apply flag set> } })
+   ```
+2. After any fix subagent returns, follow Worker Distrust Protocol (read diff, run verification)
+3. Load `verification-before-completion` skill — verify typecheck + lint pass
+4. Load `observability-and-instrumentation` skill check if removing instrumented code
+
+If `--dry-run` (default), skip actual cleanup and report what would be cleaned. PRs are **never** opened without `--apply` and without explicit user confirmation (AGENTS.md: never push without confirmation).
+
+### Phase 5: Report
+
+1. **Quality Grades:** Per-domain status (before → after)
+2. **Issues Found:** Count by severity
+3. **Cleanup PRs:** Opened / not needed / skipped (dry-run)
+4. **Recommendations:** Suggested improvements for next cycle
+
+## Failure Handling
+
+| Scenario | Action |
+|----------|--------|
+| Fallow scan fails | Check if fallow is installed: `npx fallow --version`. Install if missing. |
+| Quality grades unchanged | Report as-is — no change is a valid result |
+| Cleanup PR creation fails | Log issue, continue with remaining PRs |
+| Verification fails 2x | Stop, report blocker with file:line evidence |
+
+## Stop Conditions
+
+- Fallow not installed → report install command, stop
+- No findings returned → report clean state, skip Phase 4
+- Cleanup PR fails review → log issue, don't block report
+- Verification fails 2x on same approach → stop, escalate
+
+## Related Commands
+
+| Need              | Command       |
+| ----------------- | ------------- |
+| Full verification | `/verify all --full` |
+| Pattern audit     | `/audit`      |
+| Fix a bug         | `/fix`        |
+
+## Related Skills
+
+- `fallow` — structural analysis engine (Phase 1)
+- `code-cleanup` — safe code removal patterns (Phase 4)
+- `verification-before-completion` — evidence gate after cleanup (Phase 4)
+- `observability-and-instrumentation` — telemetry integrity check (Phase 4)