@minhduydev/mdpi 0.5.0 → 0.7.0

package/README.md

@@ -54,4 +54,4 @@ npx mdpi init
 
 ## What's in the kit
 
-`agents/` (7) · `prompts/` (11) · `skills/` (67 + INDEX) · `templates/` (11) · `workflows/` (6) · `context/` (2) · `extensions/` (2 TS) · `settings.json` · `packages.json` · `AGENTS.md` · `README.md` · `QUALITY.md` · `.env.example` · `guard.example.json` · `subagents.json` · `artifacts/example/` (template examples).
+`agents/` (7) · `prompts/` (12) · `skills/` (67 + INDEX) · `templates/` (11) · `workflows/` (6) · `context/` (2) · `extensions/` (2 TS) · `settings.json` · `packages.json` · `AGENTS.md` · `README.md` · `QUALITY.md` · `.env.example` · `guard.example.json` · `subagents.json` · `artifacts/example/` (template examples).

package/dist/index.js

@@ -10,7 +10,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { mkdir, readdir } from "node:fs/promises";
 //#region package.json
-var version = "0.5.0";
+var version = "0.7.0";
 //#endregion
 //#region src/utils/manifest.ts
 /**
@@ -950,12 +950,14 @@ async function initCommand(options = {}) {
 	if (only) adaptSettingsJson(piDir, only);
 	const manifest = generateManifest(piDir, version);
 	const fileCount = Object.keys(manifest.files).length;
+	const hasSkills = !only || only.has("skills");
 	if (quiet) {
 		const subset = only ? ` subset=[${[...only].join(",")}]` : "";
 		console.log(`mdpi: installed ${fileCount} files to ${piDir} (v${version})${subset}`);
 	} else {
 		const subsetNote = only ? `Subset: ${[...only].join(", ")} (+ always-on config).\n\nsettings.json trimmed to drop references to excluded\nskills/prompts/extensions dirs.\n\nNote: mdpi upgrade compares against the FULL template —\nrun \`mdpi upgrade --check\` before applying.\n\n` : "";
-		p.note(`Pi kit installed at:\n${piDir}\n\n${fileCount} template files tracked via manifest.\n\n` + subsetNote + `Next: run ${color.cyan("mdpi install")} to install the kit's npm packages,\nthen open pi in this repo to use the kit.`, "Installation complete");
+		const fallowHint = hasSkills ? "Fallow skill included (codebase intelligence: dead code,\nduplication, complexity). For JS/TS projects, run `/init`\nin a pi session to generate `.fallowrc.json`; other stacks skip it.\n\n" : "";
+		p.note(`Pi kit installed at:\n${piDir}\n\n${fileCount} template files tracked via manifest.\n\n` + subsetNote + fallowHint + `Next: run ${color.cyan("mdpi install")} to install the kit's npm packages,\nthen open pi in this repo to use the kit.`, "Installation complete");
 		p.outro(color.green("Ready!"));
 	}
 }

package/dist/template/.pi/AGENTS.md

@@ -21,7 +21,7 @@ For project-wide rules (kernel, drift signals, hard constraints, output style),
 | `prompts/` | slash commands | Dispatched by primary agent |
 | `workflows/` | DAG workflows | Executed via subagent tool |
 | `templates/` | project context templates | Referenced via auto-inject |
-| `context/` | reference docs (architecture, fallow) | Manual reference only, never auto-injected |
+| `context/` | reference docs (architecture) | Manual reference only, never auto-injected |
 | `extensions/` | TypeScript extensions | Compiled JS code, gated by pi extension SDK |
 
 ---

package/dist/template/.pi/README.md

@@ -39,7 +39,7 @@ pi
 ├── VERSION                         # Kit version (0.2.0)
 ├── .env.example                    # Environment variables (none required)
 ├── guard.example.json              # pi-guard ruleset example
-├── settings.json                   # 4 extensions + 67 skills + 11 prompts
+├── settings.json                   # 4 extensions + 67 skills + 12 prompts
 │
 ├── agents/                         # 7 subagent personas
 │   ├── INDEX.md                    # Agent index + routing table
@@ -55,7 +55,7 @@ pi
 │   ├── workflows-runner.ts         # DAG workflow executor
 │   └── templates-injector.ts       # Auto-inject project templates
 │
-├── prompts/                        # 11 slash commands (pi-native)
+├── prompts/                        # 12 slash commands (pi-native)
 │   ├── INDEX.md                    # Command index + lifecycle diagram
 │   ├── init.md                     # Bootstrap project context
 │   ├── create.md                   # Create spec + task outline
@@ -95,9 +95,8 @@ pi
 ├── scripts/                        # 1 utility script
 │   └── gc-check.sh                 # Structural invariants for /gc
 │
-├── context/                        # 2 reference docs
-│   ├── architecture.md             # Pi 5-layer architecture
-│   └── fallow.md                   # Fallow CLI reference
+├── context/                        # 1 reference doc
+│   └── architecture.md             # Pi 5-layer architecture
 │
 ├── state/                          # Runtime state (gitignored)
 │   └── session-summary.{json,md}
@@ -115,11 +114,12 @@ pi
 
 ## Slash commands
 
-11 pi-native slash commands (full detail + lifecycle in [`prompts/INDEX.md`](./prompts/INDEX.md)):
+12 pi-native slash commands (full detail + lifecycle in [`prompts/INDEX.md`](./prompts/INDEX.md)):
 
 | Command | Purpose |
 |---------|---------|
 | `/init` | Bootstrap project context (AGENTS.md + templates + user profile) |
+| `/clarify` | Discuss + clarify + stress-test a vague idea into a hardened spec |
 | `/create` | Create spec (PRD) + workspace + task outline |
 | `/plan` | Detailed implementation plan + tasks.json |
 | `/ship` | Execute tasks, verify, review, close |

package/dist/template/.pi/agents/explore.md

@@ -2,7 +2,7 @@
 name: explore
 description: "Fast read-only codebase cartographer — locate files, symbols, and usage patterns with file:line evidence"
 tools: read, grep, find, ls, bash, semantic_query, semantic_inspect, semantic_grep, semantic_show
-model: commandcode/deepseek/deepseek-v4-flash
+model: opencode-go/deepseek-v4-flash
 ---
 
 You are Pi — a read-only codebase explorer.

package/dist/template/.pi/agents/scout.md

@@ -2,7 +2,7 @@
 name: scout
 description: External research specialist for library docs, API references, and real-world code patterns
 tools: read, bash, find, ls, websearch, codesearch, context7, grepsearch, web_fetch
-model: commandcode/deepseek/deepseek-v4-flash
+model: opencode-go/deepseek-v4-flash
 ---
 
 You are Pi — an external research specialist.

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

@@ -4,32 +4,34 @@ purpose: Index of slash commands with purpose, when-to-use, and lifecycle positi
 
 # Prompts Index
 
-11 slash commands. Lifecycle is canonical; utilities attach at any phase.
+12 slash commands. Lifecycle is canonical; utilities attach at any phase.
 
 ## Canonical Lifecycle
 
 ```
-   ┌──── /init ────┐
-   │               ▼
-/init → /create → /plan? → /ship ⇄ /verify
-   │                  │           │
-   │                  ▼           │
-   │            (tasks.json)      │
-   │                              │
-   └──── /close ←─────────────────┘
-   
+   ┌──── /init ──────────────────────┐
+   │                                 ▼
+/init → /clarify (vague) ┐   /plan? → /ship ⇄ /verify
+       \                 │      │           │
+        → /create (clear) ┘      ▼           │
+                           (tasks.json)      │
+   ┌──── /close ←────────────────────────────┘
+   │
 Utilities (any phase):  /research  /audit  /fix  /gc
 Status:                 /status
 ```
 
-**Artifact chain:** `/init` → templates · `/create` → `spec.md` · `/plan` → `plan.md` + `tasks.json` · `/ship` → implementation + `progress.md` · `/verify` → `verify.log` · `/close` → clears `.active`.
+**Two Define-phase entries:** `/clarify` (vague/complex ask — discussion pipeline: interview → brainstorm/refine → grill → doubt → spec) · `/create` (clear ask — fast path to spec + workspace + branch).
+
+**Artifact chain:** `/init` → templates · `/clarify`|`/create` → `spec.md` · `/plan` → `plan.md` + `tasks.json` · `/ship` → implementation + `progress.md` · `/verify` → `verify.log` · `/close` → clears `.active`.
 
 ## Commands
 
 | Command | Purpose | When to use | Arg-hint | Lifecycle |
 |---------|---------|-------------|----------|-----------|
 | `/init` | Bootstrap project: AGENTS.md + planning context + user profile | Once per project (or after stack change) | `[--deep] [--context\|--user\|--all] [--dry-run]` | Setup |
-| `/create` | Create spec (PRD) + workspace + task outline | Starting a feature/fix with a description | `<desc> [--lite] [--dry-run]` | Define |
+| `/clarify` | Discuss + clarify + stress-test a vague idea into a hardened spec | Vague/underspecified/high-stakes ask needing structured discussion | `[<topic>] [--grill] [--spec <path>] [--dry-run]` | Define (deep) |
+| `/create` | Create spec (PRD) + workspace + task outline | Starting a feature/fix with a clear description | `<desc> [--lite] [--dry-run]` | Define (fast) |
 | `/plan` | Detailed implementation plan + tasks.json (optional, between create and ship) | Complex tasks needing TDD-step guidance | `[--level 0-3] [--dry-run]` | Plan |
 | `/ship` | Execute tasks, verify, review, close | Ready to implement the spec | `[--skip-review] [--dry-run]` | Build/Ship |
 | `/verify` | Check completeness/correctness/coherence against PRD | Before shipping, or anytime mid-implementation | `[path\|all] [--quick] [--full] [--fix] [--no-cache]` | Verify |
@@ -46,6 +48,9 @@ Status:                 /status
 |-----------|---------|
 | Fresh repo, first session | `/init --all` |
 | Existing repo, want codebase map | `/init --deep` then `/research` |
+| "Build X" but I'm not sure what X really is | `/clarify "X"` → `/plan` |
+| Vague idea needs discussion before spec | `/clarify` (interactive) |
+| Stress-test an existing idea/ADR/PRD | `/clarify --grill` or `/clarify --spec path/to/adr.md` |
 | "Build X" with a clear description | `/create "X"` → `/ship` |
 | "Build X" but complex/multi-step | `/create "X"` → `/plan` → `/ship` |
 | "Fix this bug / failing test" | `/fix "..."` |

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

@@ -0,0 +1,238 @@
+---
+description: Discuss, clarify, and stress-test a vague idea into a hardened spec
+argument-hint: "[<topic>] [--grill] [--spec <path>] [--dry-run] [--help]"
+---
+
+# Clarify: $ARGUMENTS
+
+Orchestrate the full Define-phase discussion pipeline — extract intent, explore options, adversarially stress-test, and write a hardened spec. One command, five sequenced skills, one artifact.
+
+> **Workflow:** `/init` → **`/clarify`** (vague/complex ask) **or** `/create` (clear ask) → `/plan` → `/ship`
+>
+> **When to use:** The ask is vague, underspecified, high-stakes, or you need to discuss and clarify many things before a spec exists. Skip for clear/mechanical asks — use `/create` instead.
+
+## Parse Arguments
+
+| Argument      | Default  | Description                                                  |
+| ------------- | -------- | ------------------------------------------------------------ |
+| `<topic>`     | optional | What to discuss/clarify (quoted string)                      |
+| `--grill`     | false    | Skip exploration; enter adversarial phase on an existing idea |
+| `--spec <path>` | false  | Stress-test an existing spec/ADR/PRD document at `<path>`    |
+| `--dry-run`   | false    | Preview the discussion plan and entry routing without writing |
+| `--help`      | false    | Show this usage                                              |
+
+If `<topic>` is omitted, open with: *"What would you like to clarify?"* and run Phase 2 from a blank slate.
+
+## Guard Phase
+
+Before discussing:
+- Check `.pi/artifacts/.active` — if an active slug exists with `spec.md`, ask: **continue/refine** the existing spec, or **start new**?
+- Check `git status --porcelain` — if uncommitted changes, ask: stash, commit, or continue?
+- `vcc_recall` for prior session decisions on this topic — avoid re-exploring rejected approaches
+- `memory_search({ project: "<active slug or empty>" })` for durable prior decisions across sessions
+
+## Load Skills (Sequenced Orchestration)
+
+This command **sequences** skills — each hands off to the next at an explicit gate. Do **not** load all at once; load a skill only when its phase opens.
+
+| Skill                       | Phase  | Trigger                                   | Role                                                       |
+| --------------------------- | ------ | ----------------------------------------- | ---------------------------------------------------------- |
+| `interview-me`              | 2      | Ask missing who/why/success/constraint    | Extract real intent, one question at a time, w/ guesses   |
+| `brainstorming`             | 3a     | Intent clear, need options/trade-offs     | Collaborative exploration, 2-3 approaches                  |
+| `idea-refine`               | 3b     | Need structured divergent→convergent      | One-pager: direction + assumptions + Not Doing list        |
+| `grill-me`                  | 4      | Refined direction exists                  | Adversarial interrogation — destroy weak options           |
+| `doubt-driven-development`  | 5      | High-stakes / unfamiliar / irreversible   | Optional fresh-context adversarial review                  |
+| `spec-driven-development`   | 6      | Idea hardened, blockers resolved          | Write `spec.md` via locked SPECIFY gate                    |
+| `source-driven-development` | 3-4    | Touching unfamiliar tech/API               | Ground decisions in official docs/source                   |
+| `dcp-hygiene`               | Report | Compress closed exploration work-stream   | Keep context bounded when `compress` is available          |
+
+## Entry Routing
+
+Detect where the user is starting and enter at the right phase. Do not force everyone through Phase 2.
+
+| Signal in the ask                                 | Entry phase                  |
+| ------------------------------------------------- | ---------------------------- |
+| "build me X" with no who / why / success / constraint | **Phase 2** (interview-me)   |
+| Rough idea, but missing options and trade-offs    | **Phase 3** (brainstorming)  |
+| Existing idea/ADR/PRD to stress-test              | **Phase 4** (grill-me)       |
+| `--grill` flag                                    | **Phase 4** directly         |
+| `--spec <path>` flag                              | **Phase 4** grill-with-docs on that file |
+| Clear, bounded ask                                | **Exit**: tell user to run `/create` instead |
+
+If routing is ambiguous, ask the user one question: *"Do you want to explore what to build, or stress-test an idea you already have?"*
+
+## Phase 1: Entry Assessment
+
+1. Read the topic + any referenced docs + relevant repo context (`semantic_query` for related patterns, `vcc_recall` for prior decisions).
+2. Write a one-line **HYPOTHESIS** with a confidence number (per `interview-me` Step 1), even if entering at Phase 3+. This surfaces your starting assumption visibly.
+3. Determine entry phase from the table above. Announce: *"Entering at Phase N because [signal]."*
+4. If `--dry-run`: report the entry phase + planned skill sequence + estimated turns, then stop.
+
+## Phase 2: Intent Extraction (`interview-me`)
+
+Load `interview-me`. Run its 5-step process:
+
+1. **HYPOTHESIS + CONFIDENCE** (already drafted in Phase 1; refine if needed)
+2. **Ask one question at a time, each with a GUESS attached** — never batch
+3. **Listen for want-vs-should-want** — probe sophistication-signaling answers ("scalable", "modern", "clean") with: *"If you didn't have to justify this to anyone, what would you actually want?"*
+4. **Restate intent** in the user's words: Outcome / User / Why now / Success / Constraint / **Out of scope**
+5. **Confirm with an explicit yes** — "whatever you think" / "sounds good" / silence are NOT yes
+
+**Stop when** you can predict the user's reaction to the next three questions (the 95% confidence test). Then hand off to Phase 3.
+
+**Blocker rule:** if the user cannot answer a foundational question, flag it as a blocker — do not proceed to spec.
+
+## Phase 3: Exploration & Refinement (`brainstorming` → `idea-refine`)
+
+### 3a: Collaborative Exploration (`brainstorming`)
+
+Load `brainstorming`. One question at a time (multiple choice preferred). Generate **2-3 distinct approaches** with explicit trade-offs. Lead with your recommendation + reasoning. YAGNI ruthlessly.
+
+If running inside a codebase, ground options in real patterns — cite `file:line` for existing architecture that constrains the design.
+
+### 3b: Structured Converge (`idea-refine`)
+
+If the idea needs a structured artifact (most non-trivial cases), load `idea-refine` and run its 3 phases:
+
+- **Divergent:** restate as a "How Might We", 5-8 idea variations via lenses (inversion, constraint removal, audience shift, simplification, 10x, expert lens)
+- **Converge:** cluster into 2-3 directions, stress-test on user value / feasibility / differentiation, **surface hidden assumptions** (what you're betting is true, what could kill it, what you're ignoring)
+- **Sharpen:** produce a one-pager: Problem Statement · Recommended Direction · Key Assumptions · MVP Scope · **Not Doing** (the most valuable part)
+
+Be honest, not supportive. A good ideation partner is not a yes-machine — push back on weak ideas with specificity.
+
+**Gate:** user confirms the chosen direction before Phase 4.
+
+## Phase 4: Adversarial Stress-Test (`grill-me`)
+
+Load `grill-me`. This is adversarial, not collaborative. Do not be polite. Interrogate the refined direction across all five categories:
+
+| Category               | Push on                                                      |
+| ---------------------- | ------------------------------------------------------------ |
+| **Ambiguity**          | Terms that could mean different things; concrete behavior examples |
+| **Hidden assumptions** | What this assumes about the system, users, data, failure modes, team capacity |
+| **Missing constraints** | Implicit perf/security/compat/observability constraints; codebase patterns that bind |
+| **Hand-waving**        | "We'll figure that out later"; "obviously" / "simply" / "just" statements; the hardest part |
+| **Integration & blast radius** | Existing code touched; what breaks on deploy; tests/docs that change |
+
+For each question: present with a concrete example → let the user answer → record the resolution. Unanswerable questions become **blockers**, not "we'll fix it later."
+
+**If `--spec <path>`:** apply the same interrogation to the document content and propose concrete edits for each gap.
+
+**Stop when** questions start repeating or precision stops changing the plan. Then assess:
+- Ready to proceed? → Phase 5 (optional) then Phase 6
+- Fundamentally flawed? → say so directly, suggest alternatives, stop
+- Too many unresolved? → recommend another Phase 3 round or `/research`, stop
+
+## Phase 5: Fresh-Context Doubt (`doubt-driven-development`, optional)
+
+**Triggered only when** the decision is non-trivial per `doubt-driven-development`'s definition: crosses module boundaries, asserts unverifiable properties, or has irreversible blast radius. Skip for ordinary decisions — doubting every keystroke ships nothing.
+
+1. **CLAIM** — name the decision in 2-3 lines + why it matters
+2. **EXTRACT** — smallest reviewable unit (artifact + contract, stripped of your reasoning)
+3. **DOUBT** — spawn `review` subagent with an **adversarial** prompt ("find issues", not "is it good"). Pass ARTIFACT + CONTRACT only, **never the CLAIM**
+4. **RECONCILE** — classify each finding: contract misread → valid+actionable → valid trade-off → noise. Re-read the artifact before classifying; don't rubber-stamp
+5. **STOP** — trivial findings, 3 cycles, or user override
+
+**Cross-model:** in interactive mode, always **offer** a second opinion (Gemini CLI / Codex CLI / manual / skip). Never silently skip. Each external CLI invocation needs explicit user authorization.
+
+> **Note:** do not run `doubt-driven-development` from inside a subagent (no nested doubt). The main session orchestrates.
+
+## Phase 6: Write Spec (`spec-driven-development`)
+
+Load `spec-driven-development`. Run its **SPECIFY** gate using everything hardened in Phases 2-5:
+
+1. State the goal as an **outcome**, not a task
+2. **Establish vocabulary** — every concept has one name, mapped to exactly one code symbol (ubiquitous language)
+3. Derive **3-7 observable truths** from the user's perspective
+4. Identify **constraints**: technical, UX, security, performance, compatibility
+5. Define **non-goals** explicitly (pull from `idea-refine`'s "Not Doing" list)
+6. List **affected surfaces**: files, APIs, commands, UI, data models
+7. **Check vocabulary consistency** — no overloaded terms, no synonyms
+8. Reframe instructions as **success criteria** ("X is true when…", with a `Verify:` command)
+9. Define the **three-tier boundaries**: always do / ask first / never do
+
+**Gate:** spec approved by the user, or assumptions explicitly accepted.
+
+Choose PRD rigor from the same signals `/create` uses:
+
+| Signal                          | Lite PRD | Full PRD |
+| ------------------------------- | -------- | -------- |
+| Scope                           | Single-concern | Cross-cutting |
+| Files affected                  | 1-3      | 4+       |
+| Logic complexity                | Low      | High (multi-step, stateful) |
+| Discussion depth (this session) | Phase 2-3 only | Phase 4-5 ran |
+
+Use `.pi/templates/prd.md` for Full; the Lite format from `/create` for simple cases.
+
+**Validate before saving** (per `/create` Phase 5):
+- No placeholder text remaining
+- Success criteria include `Verify:` commands
+- Technical context references real `src/` paths
+- No implementation code in the spec
+- No unresolved `[NEEDS CLARIFICATION]` markers — if any, return to Phase 2 or 4
+
+## Phase 7: Workspace & Report
+
+### Workspace (minimal)
+
+`/clarify` does **not** create a branch or install deps — that's `/create`'s territory. It only sets up what downstream commands need:
+
+```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"
+```
+
+Write the spec to `.pi/artifacts/$SLUG/spec.md`. Optionally save the `idea-refine` one-pager to `.pi/artifacts/$SLUG/design.md` if the user wants the discussion trail preserved.
+
+> **DCP hygiene:** if `compress` is available, compress the closed Phase 2-5 exploration work-stream per the `dcp-hygiene` skill — the hardened decisions are captured in `spec.md`. Skip if unavailable.
+
+### Report
+
+1. **Entry phase** + rationale (where the discussion started)
+2. **Skills run** — which phases executed, which were skipped
+3. **Key decisions** — direction chosen, assumptions hardened, ideas killed
+4. **Blockers** — unresolved questions, if any (with flags)
+5. **Spec:** Lite or Full, success criteria count, affected files count
+6. **Doubt cycle** — ran/skipped, findings classification summary (if ran)
+7. **Artifact location:** `.pi/artifacts/$SLUG/spec.md`
+8. **Next step:** `/plan` (complex → produces `plan.md` + `tasks.json`) or `/ship` (simple Lite → derives `tasks.json` on the fly). If the user wants full workspace setup (branch + deps), suggest `/create` with the now-hardened topic.
+
+## Stop Conditions
+
+- User confirms spec at the SPECIFY gate → write spec, report, stop
+- `interview-me` blocker unresolved → stop, flag blocker, do not write spec
+- `grill-me` assesses idea as fundamentally flawed → say so, stop, do not write spec
+- Verification/validation fails 2x on same approach → stop, escalate
+- `--dry-run` → report plan, stop before any writing
+
+## Failure Handling
+
+| Scenario                              | Action                                                              |
+| ------------------------------------- | ------------------------------------------------------------------- |
+| Active spec already exists            | Ask: continue/refine existing, or start new?                        |
+| `interview-me` can't reach 95% conf.  | Stop after several rounds, tell user something foundational is missing |
+| `grill-me` produces a kill verdict    | Report why, suggest alternatives, do not write spec                 |
+| `doubt-driven-development` 3 unresolved cycles | Surface to user — artifact may not be ready              |
+| Spec validation fails                 | Fix inline, re-validate, max 2 retries; then return to Phase 2/4    |
+| External CLI missing/errors (Phase 5) | Surface failure, let user redirect; never silently fall back        |
+
+## Related Commands
+
+| Need                                  | Command     |
+| ------------------------------------- | ----------- |
+| Fast path for a clear ask (+ branch)  | `/create`   |
+| Detail tasks from the spec            | `/plan`     |
+| Execute the spec                      | `/ship`     |
+| Need external info mid-discussion      | `/research` |
+
+## Related Skills
+
+- `interview-me` — Phase 2 intent extraction (one question + guess at a time)
+- `brainstorming` — Phase 3a collaborative exploration (2-3 approaches)
+- `idea-refine` — Phase 3b structured divergent/convergent (one-pager + Not Doing)
+- `grill-me` — Phase 4 adversarial interrogation (destroy weak options)
+- `doubt-driven-development` — Phase 5 fresh-context review (high-stakes only)
+- `spec-driven-development` — Phase 6 spec writing (SPECIFY gate + vocabulary)
+- `source-driven-development` — ground decisions in official docs (Phases 3-4)
+- `dcp-hygiene` — compress closed exploration work-stream at report

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

@@ -41,8 +41,9 @@ This command delegates to the `garbage-collection` workflow via the `run_workflo
 
 1. **Run Fallow scan:**
    ```bash
-   npx fallow --format json --quiet
+   npx fallow --format json --quiet || true
    ```
+   > Append `|| true`: exit 1 means "issues found" (normal for GC), not a runtime error. Only exit 2 (invalid config/parse) is a real failure — see `fallow` skill Agent Rule 2.
 2. Extract findings: dead code, duplication, complexity hotspots, unused exports
 
 ### Phase 2: Quality Grade Update

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

@@ -41,6 +41,7 @@ Check implementation against PRD before shipping.
 | `verification-before-completion` | Always | Evidence-before-claims; phantom detection; verification cache protocol; Worker Distrust Protocol |
 | `code-review-and-quality` | Phase 4 coherence check | Cross-reference artifacts for correctness |
 | `testing-anti-patterns` | Phase 3 after tests pass | Detect mock-only tests, production pollution, and fragile assertions |
+| `fallow` | Phase 2b (advisory) | Changed-file structural risk — dead code, complexity, duplication introduced by this change. Non-blocking. |
 | `dcp-hygiene` | Phase 5 Report | Compress the closed gate output (typecheck/lint/test) when `compress` is available |
 
 ## Phase 0: Verification Cache
@@ -84,6 +85,7 @@ Report results with mode column:
 | Lint      | PASS   | incremental | 0.3s   |
 | Test      | PASS   | incremental | 1.2s   |
 | Build     | SKIP   | —           | —      |
+| Fallow    | ADVISORY | new-only  | 0.8s   |
 ```
 
 After all gates pass, load `testing-anti-patterns` skill and audit tests for mock-only coverage, fragile assertions, and production code pollution.
@@ -92,6 +94,27 @@ If `--fix` flag provided, run the project's auto-fix command (e.g., `npm run lin
 
 **After all gates pass**, record to verification cache per `verification-before-completion` skill's cache protocol.
 
+### Phase 2b: Structural Risk Advisory (fallow)
+
+After the hard gates pass, run a **non-blocking** structural-risk scan over the change set. This surfaces dead code, complexity, and duplication **introduced by this change** — it never blocks `/verify` or `/ship`.
+
+Load the `fallow` skill. Determine the PR base, then run the changed-file audit:
+
+```bash
+BASE=$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null || echo "HEAD~1")
+npx fallow audit --base "$BASE" --gate new-only --format json --quiet 2>/dev/null || true
+```
+
+> `--gate new-only` restricts to issues introduced since `$BASE` so pre-existing findings don't noise the report. `|| true` + `2>/dev/null`: exit 1 = issues found (normal), exit 2 = real error. If fallow is not installed, the project is not JS/TS, or there is no git base, this step is a **silent no-op** — never block on it.
+
+Parse the JSON `verdict` (`pass` | `warn` | `fail`) and `issues[]`. Report as the **ADVISORY** row in the Phase 2 table above.
+
+**Blocking policy — never blocks:**
+- Fallow findings are logged to `.pi/artifacts/$SLUG/progress.md` as advisory and surfaced in the Phase 5 Report under "Structural risk (advisory)".
+- They are candidates for a follow-up `/gc --scope <path>` or `/fix` — NOT a ship blocker.
+
+**Escalate (agent judgment, still no auto-block):** if verdict is `fail` with >5 NEW issues or any NEW circular dependency / architecture boundary violation, surface it prominently to the user and suggest running `/gc --scope <path>` before shipping.
+
 ## Phase 3: Coherence (skip with --quick)
 
 Cross-reference artifacts for contradictions:
@@ -155,3 +178,4 @@ Append to `.pi/artifacts/$SLUG/progress.md`: `Verification: [PASS|PARTIAL|FAIL]
 - `verification-before-completion` — evidence gate, cache protocol, phantom detection, Worker Distrust Protocol (all phases)
 - `code-review-and-quality` — coherence cross-reference (Phase 3)
 - `testing-anti-patterns` — mock-only test detection (Phase 2 post-gate)
+- `fallow` — changed-file structural risk advisory, non-blocking (Phase 2b)

package/dist/template/.pi/skills/INDEX.md

@@ -47,6 +47,7 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 | performance, slow, latency, optimize, profile, bundle size | `performance-optimization` |
 | bug, fix, error, crash, broken, debug, trace | `debugging-and-error-recovery`, `root-cause-tracing` |
 | refactor, cleanup, simplify, clean code, complex | `code-cleanup`, `code-simplification`, `deep-module-design` |
+| dead code, duplication, circular dependency, unused exports, unused dependencies, complexity hotspot, codebase health, fallow | `fallow` |
 | test, spec, verify, assert, coverage, TDD | `test-driven-development`, `testing-anti-patterns` |
 | review, audit, quality, check, PR | `code-review-and-quality`, `agent-code-quality-gate` |
 | design, UI, component, style, layout, CSS, tailwind, DESIGN.md, design identity, design token, brand identity | `frontend-design`, `design-taste-frontend` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhduydev/mdpi",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "CLI to scaffold and manage a Pi coding-agent kit (.pi/) in any repo",
   "keywords": [
     "pi",

package/dist/template/.pi/context/fallow.md

@@ -1,137 +0,0 @@
----
-purpose: Fallow codebase intelligence commands for AI agents — dead code, duplication, complexity, and audit gating
-updated: 2026-06-04
----
-
-# Fallow — Codebase Intelligence Reference
-
-## Overview
-
-Fallow is a Rust-native, deterministic static analysis tool for TypeScript/JavaScript codebases.
-**No AI inside the analyzer** — same input always produces the same output.
-It builds a complete module graph to find issues no linter or type checker can see.
-
----
-
-## Commands
-
-### Full Analysis (single pass)
-
-```bash
-npx fallow                      # All analyses: dead code + duplication + health
-npx fallow --format json        # Structured output for agent parsing
-```
-
-### Dead Code
-
-```bash
-npx fallow dead-code                                   # Full dead code report
-npx fallow dead-code --format json --quiet              # JSON for agents
-npx fallow dead-code --unused-exports                   # Only unused exports
-npx fallow dead-code --unused-dependencies              # Only unused deps
-npx fallow dead-code --circular                         # Only circular deps
-npx fallow fix --dry-run                                # Preview safe auto-fixes
-npx fallow fix --yes                                    # Apply auto-fixes
-```
-
-### Trace (investigate before deleting)
-
-```bash
-npx fallow dead-code --trace FILE:EXPORT_NAME           # Why is this export flagged?
-npx fallow dead-code --trace-dependency PACKAGE_NAME    # Where is this dep imported?
-```
-
-### Duplication
-
-```bash
-npx fallow dupes                     # Find code clones
-npx fallow dupes --mode strict       # Exact matches only
-npx fallow dupes --mode weak         # Structural matches
-npx fallow dupes --trace FILE:LINE   # Deep-dive a specific clone group
-```
-
-### Health (complexity)
-
-```bash
-npx fallow health                    # Complexity hotspots + refactoring targets
-npx fallow health --format json      # Structured output
-```
-
-### Audit Gate (for CI / pre-commit)
-
-```bash
-npx fallow audit                     # Check changed files (verdict: pass/warn/fail)
-npx fallow audit --format json       # Structured verdict for agents
-npx fallow audit --gate new-only     # Only flag new issues, not pre-existing
-```
-
----
-
-## Workflow Patterns
-
-### Post-Edit Verification Loop
-
-```bash
-# 1. Make changes
-# 2. Run audit
-npx fallow audit --format json --quiet
-# 3. If verdict is "fail", inspect findings
-# 4. Fix or investigate with --trace
-# 5. Re-run audit until pass
-```
-
-### Codebase Cleanup
-
-```bash
-npx fallow                           # Full picture
-npx fallow dead-code --format json   # Find unused code
-npx fallow fix --dry-run             # Preview auto-removals
-npx fallow fix --yes                 # Apply auto-fixes
-npx fallow dupes                     # Find duplication
-npx fallow health                    # Find complexity hotspots
-```
-
-### Monorepo / Workspace
-
-```bash
-npx fallow --workspace               # Analyze all workspaces
-npx fallow --workspace packages/pkg  # Analyze specific workspace
-```
-
----
-
-## Understanding Output
-
-Every finding in `--format json` includes:
-
-```json
-{
-  "path": "src/utils/example.ts:42",
-  "issue_type": "unused-exports",
-  "actions": [
-    {
-      "type": "delete-export",
-      "auto_fixable": true,
-      "description": "Remove unused export"
-    }
-  ]
-}
-```
-
-The `actions[]` array is machine-actionable. Agents can inspect `auto_fixable` flags and apply safe fixes programmatically.
-
----
-
-## Config
-
-Fallow auto-detects your project. For custom config, run:
-
-```bash
-npx fallow init    # Generates .fallow/config.yaml with auto-detected settings
-```
-
-Common config patterns:
-- `ignorePatterns` — exclude directories from analysis (e.g., `.pi/`)
-- `entry` — declare additional entry points
-- `publicPackages` — packages with public API surface
-- `rules` — custom issue severity rules