mdpi — Pi Coding-Agent Kit CLI

Scaffold a curated .pi/ kit — agents, prompts, skills, templates, workflows, context docs, extensions, and an in-house memory layer — into any repo with one command. Turn any repository into a structured pi-coding-agent workspace.

One kit. Six subagent personas. Eighty-seven skills. Twelve slash commands. Seven DAG workflows. Six in-house extensions. Zero required config.

What is mdpi?

mdpi is a CLI that drops a battle-tested .pi/ directory into your repo. Pi auto-discovers .pi/ on startup, so after mdpi init you immediately get:

• 6 subagent personas (explore / general / plan / review / scout / vision) wired into the routing table
• 87 procedural skills (4 always-loaded Tier-1 + 83 on-demand Tier-2), from test-driven-development to swiftui-expert-skill
• 12 slash commands covering the full feature lifecycle (/init → /clarify → /create → /plan → /ship → /verify → /close)
• 7 DAG workflows (parallel multi-agent execution via a real child-process executor)
• 13 project context templates + 9 reference docs (architecture, security/performance/accessibility/observability checklists, orchestration patterns)
• 6 in-house TypeScript extensions — a markdown long-term memory layer (no SQLite, no LLM subprocess by default), a context-optimization stack, a workflow runner, and a templates injector
• 6 core external packages pre-wired (pi-subagents, pi-srcwalk, pi-vcc, pi-rtk-optimizer, pi-dcp, pi-ask)

Optimized for the "copy and use" workflow: project-local only, no global setup, idempotent re-runs.

Install

⚠️ The npm page auto-shows npm i @minhduydev/mdpi — that installs locally and does not put mdpi on your PATH. Use one of the commands below instead.

One-off (no install, recommended for first try):

npx @minhduydev/mdpi init

Global (gives you the mdpi command everywhere):

npm install -g @minhduydev/mdpi
mdpi init

You installed it locally. Either install it globally with npm install -g @minhduydev/mdpi, or run it without installing:

npx @minhduydev/mdpi init      # no install needed
# or, using the local copy you just installed:
npx mdpi init
./node_modules/.bin/mdpi init

Quick Start

# 1. Scaffold the kit into your repo
npx @minhduydev/mdpi init

# 2. Install the wired npm packages (subagents, srcwalk, vcc, rtk, dcp, pi-ask)
mdpi install

# 3. Edit the project-level AGENTS.md (repo root, NOT .pi/AGENTS.md)
#    Set project name, vision, conventions. Then in pi:
pi
/init --all          # bootstrap live context (.pi/{project,tech-stack,state,user}.md)

Then just talk to pi. The primary agent routes to the right subagent / skill / workflow automatically.

Commands

| Command | What it does | |---------|--------------| | mdpi init | Scaffold the curated .pi/ kit into the current repo + write .version + .template-manifest.json (SHA-256 file map). Idempotent; --force overwrites template files (preserves user files), --quiet for CI. --only <cats> installs only the listed category dirs (agents,prompts,skills,templates,workflows,context,extensions) and trims settings.json to match; the chosen subset is recorded in the manifest so mdpi upgrade won't re-add excluded categories. | | mdpi install | Install the kit's declared npm packages — core (.pi/settings.json:packages) + optional (.pi/packages.json). Shells out to pi install npm:<pkg> (idempotent, safe to re-run). --core / --optional scope; --check dry-runs and reports installed/missing; --yes skips the confirm prompt. | | mdpi upgrade | Bring .pi/ up to the bundled template version. Manifest-based: overwrites only user-unmodified files, preserves user edits, lists orphans. Respects a remembered --only subset (won't re-add excluded categories). --check dry-run, --force overwrite modified, --prune-all delete orphans, --merge-settings union-merge settings.json:packages (upstream + user, other keys preserved). | | mdpi new <kind> [name] | Scaffold a new kit component (skill\|prompt\|agent\|workflow\|template) from a lint-passing skeleton. -d <text> sets the description; --force overwrites. The skill skeleton comes with frontmatter + When to Use/NOT so it passes mdpi lint immediately. | | mdpi lint [skills\|docs\|all] | Governance: SKILL.md frontmatter (pi name+description), H1, When to Use/NOT, line limits, references/ depth, dead cross-ref detection (skills referencing non-existent skills), + README count/slash-command drift. --json for machine output. | | mdpi doctor | .pi/ health: version match, manifest valid, settings.json valid, kit dir counts, orphan detection, lint summary. | | mdpi --version / mdpi --help | — |

What's in the kit

.pi/
├── AGENTS.md                  # Scoped rules (auto-loads when editing .pi/)
├── README.md                  # Kit reference (deep docs)
├── VERSION                    # Kit version
├── settings.json              # 6 extensions + 88 skills + 12 prompts + 6 core packages
├── packages.json              # Optional add-on packages
├── mcp.json                   # MCP server config
├── agents/                    # 6 subagent personas + INDEX
├── prompts/                   # 12 slash commands + INDEX
├── skills/                    # 88 skills + INDEX (task → skill routing)
├── workflows/                 # 7 DAG workflows + INDEX
├── templates/                 # 13 project context templates
├── context/                   # 9 reference docs (architecture + 7 checklists)
├── extensions/                # 6 in-house TypeScript extensions
├── scripts/                   # gc-check.sh (structural invariants for /gc)
├── artifacts/example/         # 4 template examples (plan/progress/research/spec)
├── state/  tasks/  memory/     # Runtime state (gitignored, generated as you work)
└── .env.example, guard.example.json, subagents.json, dcp.json

Agents (6 subagent personas)

| Persona | Role | Tools | |---------|------|-------| | explore | Fast read-only codebase cartographer — files, symbols, usage with file:line evidence | read, grep, find, ls, bash, semantic_* | | general | Surgical implementation for small, well-defined tasks (1–3 files) | read, grep, find, ls, bash, edit, write, semantic_* | | plan | Architecture, decomposition, executable implementation plans | read, grep, find, ls, bash, semantic_*, websearch, codesearch, context7 | | review | Five-axis review (correctness, readability, architecture, security, performance) + artifact/wiring verification + stub detection | read-only + semantic_* (incl. semantic_review); loads code-review-and-quality / security-and-hardening / performance-optimization for axis depth | | scout | External research — library docs, API references, real-world code patterns | read, bash, find, ls, websearch, codesearch, context7, web_fetch | | vision | Visual UI/UX review, accessibility audit, design-system evaluation | read, bash, find, ls |

The four former specialist personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor) were folded into review + on-demand skills (10 → 6 consolidation).

Slash Commands (12)

Canonical lifecycle (/init → /clarify|/create → /plan → /ship ⇄ /verify → /close); utilities attach at any phase.

| Command | Phase | Purpose | |---------|-------|---------| | /init | bootstrap | Bootstrap project context (AGENTS.md + templates + user profile) | | /clarify | define | Discuss + clarify + stress-test a vague idea into a hardened spec (interview → brainstorm → grill → doubt) | | /create | define | Fast path: clear ask → spec (PRD) + workspace + task outline | | /plan | plan | Detailed implementation plan + tasks.json | | /ship | execute | Execute tasks, verify, review, close (composes batch-implement + quality-loop) | | /verify | verify | Check completeness/correctness against PRD (canonical gate owner) | | /fix | utility | Debug + fix a bug or failing test (reproduce → isolate → fix → verify) | | /research | utility | Gather info before implementation | | /audit | utility | Find all occurrences of a pattern, review, remediate | | /gc | utility | Fallow analysis + quality grades + cleanup | | /status | status | Show active feature, progress, blockers | | /close | finalize | Finalize active feature, clear .active |

Artifact chain: /init → templates · /clarify|/create → spec.md (feature.json) · /plan → plan.md + tasks.json · /ship → implementation + progress.md · /verify → verify.log · /close → terminal feature.json state.

Workflows (7 DAG workflows)

Invoked via the run_workflow tool (never by manually reading the workflow file). The workflows-runner extension parses each .pi/workflows/*.md and dispatches real child pi processes per phase.

| Workflow | Phases | Trigger | Purpose | |----------|--------|---------|---------| | audit-pattern | 2 + synthesis | >5 pattern occurrences (/audit) | Find pattern occurrences, review each, prioritize remediation | | batch-implement | 3 + merge | ≥5 independent tasks, no file conflicts | One subagent per task in parallel, review, merge | | deep-research | 2 + synthesis | Complex/multi-angle topic (/research) | Fan out web searches per angle, cross-check, cited report | | development-lifecycle-workflow | 5 | Explicit full-lifecycle multi-agent run | research → validate → plan → implement → verify (composes batch-implement) | | frontend-feature-workflow | 7 | Frontend feature build (mockup or spec) | design analysis → deslop → architecture → craft → implement → harden → audit | | garbage-collection | 5 | Manual /gc or scheduled cadence | Fallow scan → grade → prioritize → optional cleanup PRs | | quality-loop | 7 (looped) | High-risk feature, explicit quality gating | Score-gated review loop until 5/5 or escalation |

Workflows may compose recursively (e.g., development-lifecycle-workflow Phase 4 calls run_workflow('batch-implement'); /ship Phase 5 calls quality-loop).

Skills (88)

Tier 1 (4, always loaded): behavioral-kernel, defense-in-depth, incremental-implementation, verification-before-completion.

Tier 2 (84, loaded on-demand) — grouped by domain. See .pi/skills/INDEX.md for the full task → skill routing table.

| Category | Skills | |----------|--------| | Tier 1 (auto-load) | behavioral-kernel, defense-in-depth, incremental-implementation, verification-before-completion | | Process & method | brainstorming, idea-refine, interview-me, grill-me, doubt-driven-development, spec-driven-development, planning-and-task-breakdown, subagent-driven-development, development-lifecycle, documentation-and-adrs, deprecation-and-migration, source-driven-development, writing-skills, workflow-authoring, using-agent-skills, service-scoping, code-cleanup, code-simplification, context-engineering, dcp-hygiene | | Code quality & review | code-review-and-quality, agent-code-quality-gate, deep-module-design, api-and-interface-design, test-driven-development, testing-anti-patterns | | Debugging & recovery | debugging-and-error-recovery, root-cause-tracing | | Git & shipping | git-workflow-and-versioning, using-git-worktrees, shipping-and-launch | | Frontend design & UI | frontend-design, frontend-ui-engineering, design-taste-frontend, high-end-visual-design, minimalist-ui, industrial-brutalist-ui, baseline-ui, redesign-existing-projects, mockup-to-code, ui-craft-principles, ui-quality-audit, design-system-audit, production-hardening, oklch-color-workflow, v0, shadcn-ui | | React / Next.js | react-best-practices, react-compiler, react-hook-form, react-server-actions, nextjs-app-router, nextjs-cache, tanstack-query, zustand | | Accessibility | accessibility-audit, fixing-accessibility | | Performance & observability | performance-optimization, observability-and-instrumentation | | Security | security-and-hardening | | Platform & deploy | cloudflare, vercel-deploy-claimable, supabase, supabase-postgres-best-practices, ci-cd-and-automation, polar, resend | | Mobile (Apple) | swift-concurrency, swiftui-expert-skill, core-data-expert | | Tools & integrations | figma, jira, playwright, chrome-devtools, browser-testing-with-devtools, srcwalk, opensrc, pdf-extract, webclaw, gemini-large-context, use-codex, fallow | | Memory & context | memory-system, context-optimization |

All skills live in .pi/skills/<name>/SKILL.md. Pi auto-discovers them on startup — no manual installation.

Templates (13)

Project context templates (seeds in .pi/templates/, copied live by /init):

prd.md · project.md · state.md · tech-stack.md · tasks.md · roadmap.md · user.md · DESIGN.md · feature-design.md · proposal.md · adr.md · progress.md · review-state.json (runtime artifact schema).

The runtime reads .pi/{name} (live), not .pi/templates/{name} (pristine seed). /init creates live copies; /context-check reports which files are live vs seed.

Context Docs (9)

Standing reference docs in .pi/context/ (manual-reference, not auto-injected):

| Doc | Covers | |------|--------| | architecture.md | Pi 5-layer architecture + dependency rules | | definition-of-done.md | Standing done-bar (addyosmani-adapted) | | testing-patterns.md | Testing patterns quick reference | | security-checklist.md | Web security checklist | | performance-checklist.md | Web performance checklist | | accessibility-checklist.md | WCAG 2.1 AA checklist | | observability-checklist.md | Production instrumentation checklist | | orchestration-patterns.md | Agent orchestration pattern catalog |

Extensions (6 in-house)

| Extension | Purpose | Status | |-----------|---------|--------| | workflows-runner | Parses DAG workflows from .pi/workflows/*.md, dispatches real child pi processes per phase, returns execution plan with subagent() calls | Production | | templates-injector | Auto-injects project.md, tech-stack.md, state.md into the system prompt every turn | Production | | memory | memory / memory_search (markdown .pi/memory/*.md, in-process TF-IDF) + before_agent_start auto-inject brief + deterministic correction detection + secret-scan + /memory-insights /memory-consolidate /memory-import-hermes /memory-trace /memory-llm-consolidate commands | Production | | skill-manage | skill_manage CRUD for procedural skills (project → .pi/skills/, global → ~/.pi/agent/skills/) | Production | | session-search | session_search over pi's JSONL session store (no SQLite, recent ~40 sessions, current project by default) | Production | | context-optimizer | Coordinator: patches vcc auto-compaction + verifies rtk + injects <context-optimization> policy every turn + /context-check (rtk/dcp/vcc stack) | Production |

Key rule: Extensions never import from each other — they communicate via pi lifecycle events.

External Packages (6 core + 1 optional)

| Package | Set | Purpose | |---------|-----|---------| | @tintinweb/pi-subagents | core | Subagent dispatch (subagent() tool) | | @sting8k/pi-srcwalk | core | semantic_* code navigation (trigram-indexed) | | @sting8k/pi-vcc | core | Deterministic no-LLM compaction + vcc_recall lineage recall | | pi-rtk-optimizer | core | Tool-output compaction (bash/read/grep) + rtk command rewriting | | @davecodes/pi-dcp | core | Dynamic context pruning (dedup, error purge, compress) | | @eko24ive/pi-ask | core | Interactive ask_user clarification gate | | pi-guard | optional | Tool permission system (bash AST parser, path globs) |

mdpi install            # core + optional (idempotent, safe to re-run)
mdpi install --core     # only settings.json:packages
mdpi install --check    # dry-run: report installed/missing

Memory System

The kit's memory layer is in-house — .pi/extensions/memory.ts (+ skill-manage.ts, session-search.ts), backed by markdown files in .pi/memory/. Default runtime: no mandatory external memory dep, no native SQLite, no embeddings, no LLM subprocess — zero-dep in-process TF-IDF.

| Memory type | Duration | Kit component | |-------------|----------|---------------| | Short-term | one session | context window + pi-vcc compaction | | Episodic | across sessions (searchable) | session-search.ts → grep over pi's JSONL session store | | Long-term | across sessions (retrieved on demand) | memory.ts → .pi/memory/*.md (markdown) + in-process TF-IDF | | Procedural | permanent | Agent Skills .pi/skills/* (87 curated, shipped) + skill-manage.ts | | Declarative | varies (RAG) | templates/ + context/ + semantic_* / websearch / context7 |

The layer provides: capture (memory tool + deterministic correction detection, 0 LLM) · retrieval (memory_search with sort/before/after/min_score operators + session_search) · auto-injection (compact brief of pinned hot USER/PROJECT entries on before_agent_start, not policy-only) · security (secret-scan before every write; per-file locks; atomic writes) · consolidation (/memory-consolidate, /memory-llm-consolidate, /memory-trace) · progressive disclosure tiers (hot = root files / warm = warm/*.md / cold = archive/*.md).

Opt-in capabilities (all default OFF)

| Flag | Effect | |------|--------| | PI_MEMORY_EMBEDDINGS=1 | memory_search fuses lexical TF-IDF + semantic cosine similarity (lazy-imports fastembed) | | PI_MEMORY_SQLITE_INDEX=1 | memory_search uses FTS5 bm25() ranking (lazy-imports better-sqlite3; self-heals) | | PI_MEMORY_GIT_VERSIONING=1 | Snapshot .pi/memory/*.md to orphan branch pi-memory-snapshots at shutdown (never touches working tree) | | PI_MEMORY_SUBAGENTS=1 | Deterministic review/defrag once at shutdown + persist report | | PI_MEMORY_NO_CORRECTION=1 | Disable deterministic correction detection |

All flags compose and are OFF by default — default runtime is byte-identical to the zero-dep lexical path.

Context Optimization

A 3-layer stack (all required core packages) that auto-activates in any .pi/ kit usage — not just workflow prompts:

| Layer | Package | Pi event | Role | |-------|---------|----------|------| | Inflow | pi-rtk-optimizer | tool_call/tool_result | Auto-rewrite bash→rtk + compact tool output (ANSI/test/build/git/linter) | | In-flight | @davecodes/pi-dcp | context (every LLM call) | Auto dedup + purge stale errors + apply compressions + nudge compress | | Compaction | @sting8k/pi-vcc | session_before_compact | Deterministic no-LLM structured summary (35–99% reduction) + vcc_recall |

Pipeline: rtk shrinks inflow → dcp prunes in-flight + nudges compress → vcc handles compaction deterministically + recall. The context-optimizer extension auto-patches vcc config + verifies rtk + injects the policy every turn. /context-check reports stack status.

Architecture (5 layers)

┌────────────────────────────────────────────┐
│  1. Core       — pi-coding-agent (jiti + API)  │
├────────────────────────────────────────────┤
│  2. Settings    — settings.json              │
├────────────────────────────────────────────┤
│  3. Skills + Prompts — declarative          │
├────────────────────────────────────────────┤
│  4. Agents      — subagent personas         │
├────────────────────────────────────────────┤
│  5. Extensions  — programmatic              │
└────────────────────────────────────────────┘

Key rule: Extensions must NOT import from other extensions. They communicate via lifecycle events.

Subagent Routing

The primary agent routes based on user intent:

| User says | Routes to | |-----------|-----------| | "find X" / "where is X" | explore + pi-srcwalk | | "research X" / "best practice" | scout + web tools (websearch, codesearch, context7, web_fetch) | | "review this code" | review (loads code-review-and-quality / security-and-hardening / performance-optimization) | | "implement X" (small, 1–3 files) | general | | "implement X" (large, unclear) | plan first, then general per task | | "design X" / "UI review" / "accessibility" | vision |

Customization

Add a subagent persona

cat > .pi/agents/my-agent.md << 'EOF'
---
name: my-agent
description: What this agent does
tools: read, bash, grep, find, ls
model: claude-sonnet-4-5
---

# My Agent

System prompt here.
EOF

Add a slash command

cat > .pi/prompts/my-cmd.md << 'EOF'
---
description: What this command does
argument-hint: "<args>"
---

Prompt body here. Use $1, $@, $ARGUMENTS for arg substitution.
EOF

Add a skill

mkdir -p .pi/skills/my-skill
cat > .pi/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Use when... (be specific)
---

# My Skill

Body here.
EOF

Add a workflow

cat > .pi/workflows/my-workflow.md << 'EOF'
---
description: One-line purpose (for run_workflow discovery)
---

# my-workflow

Brief description.

## Args
- `arg1` (required) — description

## Phases

### Phase 1: discover
- **Agent:** explore
- **Concurrency:** 1

**Prompt:**
\`\`\`
The prompt for this phase.
\`\`\`

## Final Synthesis (Main Agent)

Synthesize outputs from {phase_1_output}.
EOF

Then /reload in pi. Or use mdpi new skill|prompt|agent|workflow|template <name> to scaffold a lint-passing skeleton.

How it works

• .pi/ in this repo is the curated kit (the template payload). pnpm run build = tsdown (bundles src/index.ts → dist/index.js, inlines the package version) + scripts/bundle-template.mjs (copies an explicit INCLUDE list .pi/ → dist/template/.pi/, stripping runtime dirs npm/memory/state/tasks).
• The published package ships only dist/ (CLI + bundled template) + this README — files: [dist, README.md].
• mdpi init copies dist/template/.pi/ → ./.pi/, writes .version + .template-manifest.json (SHA-256 map) so mdpi upgrade can later detect user modifications.
• No license gate, no --global (the pi global dir ~/.pi/agent/ is pi's own config — installing the full kit there is a footgun). Project-local only.

Troubleshooting

pi --list-extensions    # check for syntax errors
pi --version           # check pi-coding-agent version

ls .pi/skills/<name>/SKILL.md   # verify file exists, then restart pi

Each phase must follow the canonical format — ### Phase <num>: <name> with **Agent:**, **Concurrency:**, optional **Depends on:** / **Tool:**, then a **Prompt:** code block. Run mdpi lint workflows (via the workflow-authoring skill) to validate.

License

MIT © MinhDuyDEV. See LICENSE.