@minhduydev/mdpi 0.3.0

package/dist/template/.pi/workflows/deep-research.md

@@ -0,0 +1,89 @@
+---
+description: Fan out web searches across multiple angles, cross-check sources for contradictions, produce a cited report with confidence levels
+---
+
+# deep-research
+
+Fan out web searches across multiple angles on a question, cross-check sources for contradictions, and produce a cited report with confidence levels. Use when you need multi-source verification or current-events coverage.
+
+## Args
+
+- `question` (required) — The research question or topic
+
+## Phases
+
+### Phase 1: research
+
+- **Agent:** scout
+- **Concurrency:** Dynamic (1 agent per distinct angle, min 3, max 10)
+- **Depends on:** —
+- **Tool:** `subagent` (parallel mode)
+
+**Prompt:**
+
+```
+Search for different perspectives on the question: {question}. Cover opposing viewpoints, authoritative sources, and recent developments. For each finding, include the URL and publication date. Return findings grouped by angle in this format:
+
+## Angle: [angle name]
+- **Finding:** [summary]
+- **Source:** [URL]
+- **Date:** [publication date]
+- **Confidence:** [high/medium/low]
+
+Keep each finding under 200 words.
+```
+
+### Phase 2: cross-check
+
+- **Depends on:** Phase 1
+- **Agent:** review
+- **Concurrency:** Dynamic (estimate ~5 findings per agent, min 2, max 10)
+- **Tool:** `subagent` (parallel mode)
+
+**Prompt:**
+
+```
+Cross-check these findings: {phase_1_output}. Flag contradictions between sources, identify confirmable facts with supporting citations, and note where sources disagree or lack evidence. Return a verified fact set in this format:
+
+## Verified Facts
+- **Fact:** [statement]
+- **Confidence:** [high/medium/low]
+- **Supporting sources:** [list of URLs]
+
+## Contradictions
+- **Claim A:** [statement]
+- **Claim B:** [contradicting statement]
+- **Resolution:** [which is more credible and why]
+
+Keep each item under 150 words.
+```
+
+## Final Synthesis (Main Agent)
+
+After Phase 2 completes, synthesize the final report directly from {phase_2_output}.
+
+Write a final cited report using markdown with sections:
+1. **Executive Summary** — Brief overview of key findings
+2. **Key Findings** — Detailed findings with inline citations
+3. **Contradictions & Uncertainties** — Areas of disagreement or low confidence
+4. **Sources** — Complete list of all sources consulted
+
+Annotate each claim with confidence level (high/medium/low). Keep the report under 2000 words.
+
+## Invocation Example
+
+```
+/research <topic>  # When complexity is detected as complex
+```
+
+Or directly:
+
+```
+subagent({
+  chain: [
+    { agent: "scout", task: "Phase 1 prompt per angle for: {question}" },
+    { agent: "review", task: "Phase 2 prompt cross-checking findings" },
+    // Main agent synthesizes
+  ]
+});
+```

package/dist/template/.pi/workflows/development-lifecycle-workflow.md

@@ -0,0 +1,175 @@
+---
+description: Multi-agent development lifecycle — research → validate → plan → implement → verify (with sub-workflow composition)
+---
+
+# development-lifecycle-workflow
+
+Multi-agent workflow that chains the development lifecycle phases with parallelism. Uses specialized agents (scouts, reviewers, planners) and composes with the batch-implement workflow for parallel implementation.
+
+## Args
+
+- `feature` (required) — The feature or change to implement
+
+## Phases
+
+### Phase 1: Research Approaches
+
+- **Agent:** scout
+- **Concurrency:** Dynamic (1 agent per approach, min 2, max 5)
+- **Tool:** `subagent` (parallel mode)
+
+**Prompt:**
+
+```
+Research different approaches to implementing: {feature}. For each approach, analyze:
+1. Technical feasibility
+2. Trade-offs and risks
+3. Implementation complexity
+4. Dependencies and constraints
+
+Return findings in this format:
+
+## Approach 1: [name]
+- **Description:** [summary]
+- **Pros:** [list]
+- **Cons:** [list]
+- **Complexity:** [low/medium/high]
+- **Risks:** [list]
+
+Keep each approach under 300 words.
+```
+
+### Phase 2: Validate Requirements
+
+- **Depends on:** Phase 1
+- **Agent:** review
+- **Concurrency:** Dynamic (1 agent per approach, min 1, max 5)
+- **Tool:** `subagent` (parallel mode)
+
+**Prompt:**
+
+```
+Review these approaches: {phase_1_output}. Validate the requirements and constraints for each approach. Check for:
+1. Technical accuracy
+2. Feasibility given project constraints
+3. Alignment with existing patterns
+4. Missing considerations
+
+Return validated requirements in this format:
+
+## Validated Requirements
+- **Approach 1:** [validated requirements]
+- **Approach 2:** [validated requirements]
+- **Approach 3:** [validated requirements]
+
+## Recommendations
+- **Recommended approach:** [which approach and why]
+- **Critical constraints:** [list]
+
+Keep each section under 200 words.
+```
+
+### Phase 3: Create Implementation Plan
+
+- **Depends on:** Phase 2
+- **Agent:** plan
+- **Concurrency:** 1
+- **Tool:** `subagent` (single mode)
+
+**Prompt:**
+
+```
+Based on the validated requirements: {phase_2_output}, create a detailed implementation plan for the recommended approach. Break down into independent tasks that can be implemented in parallel.
+
+If the recommended approach has structural implications (new components, data flow changes, boundary shifts), also produce a design doc using `.pi/templates/design.md` written to `.pi/artifacts/$SLUG/design.md`.
+
+Return the plan in this format:
+
+## Implementation Plan
+
+### Overview
+[Brief description of the approach]
+
+### Tasks
+- **Task 1:** [description]
+  - Files: [list]
+  - Dependencies: [none or task names]
+- **Task 2:** [description]
+  - Files: [list]
+  - Dependencies: [none or task names]
+
+Keep each task description under 100 words.
+```
+
+### Phase 4: Parallel Implementation
+
+- **Depends on:** Phase 3
+- **Workflow:** batch-implement
+- **Args:** plan from Phase 3
+
+Execute the `batch-implement` workflow via recursive composition:
+
+```
+run_workflow({ name: "batch-implement", args: { plan: phase_3_output } })
+```
+
+This will: 1) review the plan for task independence, 2) implement tasks in parallel, 3) verify each implementation, 4) merge the results.
+
+**Implementation note**: This composes with the batch-implement workflow by passing the plan output from Phase 3 as input.
+
+### Phase 5: Verify Different Aspects
+
+- **Depends on:** Phase 4
+- **Agent:** review
+- **Concurrency:** 3 (one per aspect: correctness, code-quality, performance-security)
+- **Tool:** `subagent` (parallel mode)
+
+**Prompt:**
+
+```
+Verify the implementation from different aspects: {phase_4_output}. Each reviewer should focus on a different aspect:
+
+**Reviewer 1: Correctness**
+- Verify all requirements are met
+- Check for logic errors
+- Validate edge cases
+
+**Reviewer 2: Code Quality**
+- Check for code style and patterns
+- Identify code smells
+- Verify test coverage
+
+**Reviewer 3: Performance & Security**
+- Check for performance bottlenecks
+- Identify security vulnerabilities
+- Validate error handling
+
+Return findings in this format:
+
+## Aspect: [correctness/code-quality/performance-security]
+- **Status:** [pass/fail]
+- **Issues:** [list with file:line refs]
+- **Recommendations:** [list]
+
+Keep each finding under 150 words.
+```
+
+## Invocation
+
+```
+run_workflow({ name: "development-lifecycle-workflow", args: { feature: "<feature>" } })
+```
+
+Or compose manually:
+
+```
+subagent({
+  chain: [
+    { agent: "scout", task: "Phase 1 prompt per approach for: {feature}" },
+    { agent: "review", task: "Phase 2 prompt validating approaches" },
+    { agent: "plan", task: "Phase 3 prompt creating implementation plan" },
+    // Phase 4 composes batch-implement via run_workflow({ name: "batch-implement", ... })
+    { agent: "review", task: "Phase 5 verifying implementation" },
+  ]
+});
+```

package/dist/template/.pi/workflows/garbage-collection.md

@@ -0,0 +1,144 @@
+---
+description: Fallow structural analysis, quality grade update, prioritized findings, and optional cleanup PRs
+---
+
+# garbage-collection
+
+**Pattern:** Fallow analysis → review findings → file issues → optional auto-fix PRs
+**Trigger:** Manual via `/gc` command or scheduled cadence
+
+## Phases
+
+### Phase 1: Fallow Scan
+
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** —
+
+**Prompt:**
+
+Run full structural analysis:
+
+```bash
+npx fallow --format json --quiet > .pi/artifacts/gc-fallow.json
+```
+
+Extract key findings:
+- Dead code (unused exports, files, dependencies)
+- Code duplication (clone groups)
+- Complexity hotspots (high cyclomatic complexity)
+- Architecture boundary violations
+
+Report findings as structured JSON to {phase_1_output}.
+
+### Phase 2: Quality Grade Update
+
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** Phase 1
+
+**Prompt:**
+
+Grade each domain by scanning findings from {phase_1_output}:
+
+| Domain | Definition | Source |
+|--------|------------|--------|
+| Plugin layer | `.pi/extensions/*.ts` | Fallow + structural check |
+| Command layer | `.pi/prompts/*.md` | Manual assessment |
+| Skills layer | `.pi/skills/*/SKILL.md` | Fallow |
+| Documentation | `.pi/context/*.md` | Manual + link checker |
+| Agent layer | `.pi/agents/*.md` | Manual assessment |
+| Templates | `.pi/templates/*.md` | Manual assessment |
+
+For each domain, assign grade:
+- **A** — No issues, well-maintained
+- **B** — Minor issues, no blockers
+- **C** — Notable decay, needs cleanup
+- **D** — Significant decay, priority cleanup
+
+Update `.pi/QUALITY.md` with current grades.
+
+Report grade table to {phase_2_output}.
+
+### Phase 3: Prioritize Findings
+
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** Phase 2
+
+**Prompt:**
+
+Using {phase_2_output} grades and {phase_1_output} findings, classify each finding by severity:
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| P0 | Dead code in critical path, security hazard | Immediate fix PR |
+| P1 | Duplication >5 instances, complexity >20 | File issue / schedule PR |
+| P2 | Minor style drift, stale docs | Log for next GC cycle |
+| P3 | Informational | Note only |
+
+Report prioritized findings to {phase_3_output}.
+
+### Phase 4: Open Cleanup PRs (Optional)
+
+- **Agent:** general
+- **Concurrency:** Dynamic (estimate 1-2 per P0/P1, min 1, max 5)
+- **Depends on:** Phase 3
+- **Gate:** Defaults to dry-run. Only opens PRs when invoked with `--apply`. Without `--apply`, report what would be cleaned and stop.
+
+**Prompt:**
+
+For each P0 and P1 finding from {phase_3_output}, spawn a `general` agent per finding using subagent (parallel mode). **Only run this phase when invoked with `apply: true`; otherwise report what would be cleaned and skip.**
+
+```
+subagent({
+  agent: "general",
+  prompt: `
+    Understand this Fallow finding: [detail]
+    Create a fix branch
+    Apply the fix
+    Verify with: npm run typecheck && npm run lint
+    Open PR with conventional commit message (requires user confirmation before push)
+  `
+});
+```
+
+Report list of opened PRs to {phase_4_output}. When `apply` is false/absent, emit the planned cleanup list only.
+
+### Phase 5: Report
+
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** Phase 4
+
+**Prompt:**
+
+Generate final GC report by aggregating {phase_1_output}, {phase_2_output}, {phase_3_output}, {phase_4_output}:
+
+```text
+## GC Report — $(date -u +%Y-%m-%d)
+
+| Domain | Grade | Issues | Trend |
+|--------|-------|--------|-------|
+| Plugins | A | 0 | → |
+| Commands | B | 2 | ↓ |
+| Skills | A | 0 | → |
+| Docs | B | 1 | ↓ |
+| Agents | A | 0 | → |
+| Templates | A | 0 | → |
+
+**P0:** 0 | **P1:** 2 | **P2:** 1 | **P3:** 3
+**PRs opened:** 1
+```
+
+## Final Synthesis (Main Agent)
+
+Aggregate all phase outputs into a single cleanup report. Highlight any P0/P1 issues that did not get auto-fixed and need human review.
+
+## Invocation
+
+```
+/gc
+```
+
+Or as part of CI/scheduled task.

package/dist/template/.pi/workflows/quality-loop.md

@@ -0,0 +1,211 @@
+---
+description: Score-gated review-driven feedback loop for high-risk features; iterates review cycles until quality threshold (5/5) or escalation
+---
+
+# Quality Loop Workflow
+
+Score-gated, review-driven feedback loop for high-risk features. Runs iterative review cycles until the implementation reaches quality threshold (5/5) or escalation is triggered.
+
+> **When to use:** High-risk features, explicit user quality gating requests, complex cross-cutting changes.
+> **Invoked by:** `/ship` Phase 5 (Iterative Quality Loop mode)
+
+## Phases
+
+### Phase 1: Setup
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** —
+- **Prompt:**
+  Initialize the review loop state. Create or update `.pi/artifacts/$SLUG/review-state.json`:
+
+  ```json
+  {
+    "slug": "$SLUG",
+    "rounds": 0,
+    "maxRounds": 5,
+    "lastScore": 0,
+    "sameScoreCount": 0,
+    "findingsResolved": 0,
+    "findingsRemaining": 0,
+    "status": "active"
+  }
+  ```
+
+  Confirm: review-state.json initialized for slug `$SLUG`.
+
+---
+
+### Phase 2: Review
+- **Agent:** review
+- **Concurrency:** 1
+- **Depends on:** Phase 1
+- **Prompt:**
+  You are a quality-gate reviewer. Your job is to produce a confidence score and categorized findings.
+
+  **Context:**
+  - Read the spec from `.pi/artifacts/$SLUG/spec.md`
+  - Read the current diff: `git diff origin/main...HEAD`
+  - Read the review state from `.pi/artifacts/$SLUG/review-state.json`
+
+  **Score (X/5):**
+  | Score | Criteria |
+  |-------|----------|
+  | 5/5 | Perfect — all acceptance criteria met, no issues |
+  | 4/5 | Good — minor issues only, safe to ship |
+  | 3/5 | Needs work — important issues remain |
+  | 2/5 | Significant gaps — critical issues or missing features |
+  | 1/5 | Fundamentally wrong — does not address the spec |
+
+  **Findings:** Return an array of findings, each with:
+  - `severity`: "critical" | "important" | "minor"
+  - `file`: path with line number
+  - `finding`: description of the issue
+  - `suggestion`: concrete fix suggestion
+
+  **Return format:**
+  ```json
+  {
+    "score": 3,
+    "findings": [
+      { "severity": "critical", "file": "src/auth.ts:42", "finding": "...", "suggestion": "..." }
+    ],
+    "suggested_action": "fix" | "ask_user" | "proceed"
+  }
+  ```
+
+---
+
+### Phase 3: Gate
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** Phase 2
+- **Prompt:**
+  Evaluate the review score from Phase 2:
+
+  | Score | Action |
+  |-------|--------|
+  | 5/5 | Update review-state.json: `status: "passed"`. Exit loop. Mark as DONE. |
+  | 4/5 | Present findings to user. Ask: "Minor issues only. Ship as-is or fix?" |
+  | <4/5 | Continue to Phase 4 (Stall Check) |
+
+  Update review-state.json:
+  - Increment `rounds` by 1
+  - Set `lastScore` to current score
+  - If score unchanged from previous round, increment `sameScoreCount`
+
+---
+
+### Phase 4: Stall Check
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** Phase 3
+- **Prompt:**
+  Read `.pi/artifacts/$SLUG/review-state.json`.
+
+  **Stall detection:**
+  - If `sameScoreCount ≥ 2`: ESCALATE — fixes are not improving quality. Surface accumulated findings to user with the message:
+    > "Quality loop stalled — same score ({score}/5) for 2 consecutive rounds. Accumulated findings may indicate a design issue. Options:
+    > 1. Accept current state and proceed
+    > 2. Revisit the spec/plan
+    > 3. Manual intervention"
+
+  **Max rounds:**
+  - If `rounds ≥ maxRounds (5)`: ESCALATE — maximum iterations reached. Report all unresolved findings.
+    > "Quality loop reached maximum rounds (5). Current score: {score}/5. Unresolved findings: [list]."
+
+  If no stall and not maxed, continue to Phase 5 (Filter).
+
+---
+
+### Phase 5: Filter
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** Phase 4
+- **Prompt:**
+  Split Phase 2 findings into three categories:
+
+  | Category | Criteria | Action |
+  |----------|----------|--------|
+  | **Actionable** | Concrete fix with clear file:line and suggestion | Route to Phase 6 fixer |
+  | **Informational** | Observation, convention note, style preference | Log to progress.md, no fix needed |
+  | **Architecture** | Structural or design concern | Stop — escalate to user with options |
+
+  If any architecture findings exist, stop and present to user:
+  > "Architecture finding: [description] at [file:line]. This may require plan/spec revision. Options:
+  > 1. Proceed despite concern
+  > 2. Revise spec/plan
+  > 3. Manual review"
+
+  Update review-state.json: `findingsRemaining` = count of actionable findings.
+
+---
+
+### Phase 6: Fix
+- **Agent:** general
+- **Concurrency:** Dynamic (1 per actionable finding, max 3 parallel)
+- **Depends on:** Phase 5
+- **Prompt:**
+  You are fixing review finding: **{finding.severity}: {finding.finding}**
+
+  **Context:**
+  - File: `{finding.file}`
+  - Suggestion: `{finding.suggestion}`
+
+  **Instructions:**
+  1. Read the file at `{finding.file}`
+  2. Apply the fix
+  3. Run typecheck + lint on the changed file
+  4. Report: status (fixed/unable), what was changed, verification result
+
+  **Guard:** Stay within the file scope. Do not touch unrelated code.
+
+  After all fixers complete, the orchestrator:
+  - Updates review-state.json: `findingsResolved` += count of successful fixes
+  - Re-runs full verification gates (typecheck + lint + test)
+
+---
+
+### Phase 7: Re-Review
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** Phase 6
+- **Prompt:**
+  Loop back to Phase 2. The implementation has been updated based on review findings. Spawn a fresh review agent with the updated diff and spec.
+
+  ```typescript
+  subagent({
+    agent: "review",
+    prompt: "[Phase 2 prompt, with updated diff]"
+  });
+  ```
+
+  Continue the loop until exit condition (score ≥ 5, stall, or max rounds).
+
+---
+
+## Exit Conditions
+
+| Condition | Trigger | Action |
+|-----------|---------|--------|
+| **PASS** | Score 5/5 | Mark review-state.json status "passed". Report completion. |
+| **USER ACCEPT** | Score 4/5, user accepts | Mark review-state.json status "accepted". Proceed. |
+| **STALL** | sameScoreCount ≥ 2 | Escalate with accumulated findings. |
+| **MAX ROUNDS** | rounds ≥ 5 | Escalate with unresolved findings. |
+| **ARCHITECTURE** | Architecture-level finding | Escalate to user for design decision. |
+
+## Output
+
+After loop exit, report:
+1. Final score (X/5)
+2. Rounds completed
+3. Findings resolved / remaining
+4. Exit reason
+5. Recommendation: proceed, revise, or manual review
+
+## Invocation
+
+```
+run_workflow({ name: "quality-loop", args: { slug: "<slug>" } })
+```
+
+Typically invoked by `/ship` Phase 5 when high-risk mode is selected.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@minhduydev/mdpi",
+  "version": "0.3.0",
+  "description": "CLI to scaffold and manage a Pi coding-agent kit (.pi/) in any repo",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "cli",
+    "scaffold",
+    "template",
+    "agent-kit"
+  ],
+  "homepage": "https://github.com/MinhDuyDEV/ockit-mapping#readme",
+  "bugs": {
+    "url": "https://github.com/MinhDuyDEV/ockit-mapping/issues"
+  },
+  "license": "MIT",
+  "author": "MinhDuyDEV <buub1309120@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MinhDuyDEV/ockit-mapping.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "mdpi": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown && node scripts/bundle-template.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "cac": "^6.7.14",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "tsdown": "latest",
+    "tsx": "latest",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}