@minhduydev/mdpi 0.3.0

package/dist/template/.pi/templates/loop-state.json

@@ -0,0 +1,24 @@
+{
+  "loop_name": "<loop-name>",
+  "owner": "[Owner]",
+  "cadence": "[cron expression or manual]",
+  "last_run": null,
+  "in_progress": [],
+  "completed": [],
+  "escalated": [],
+  "failures": [],
+  "lessons": [],
+  "processed": [],
+  "stop_conditions_met": [],
+  "metrics": {
+    "runs": 0,
+    "killed": false,
+    "kill_reason": null,
+    "tokens_used": 0,
+    "token_cap": null,
+    "pr_opened": 0,
+    "items_fixed": 0,
+    "items_skipped": 0,
+    "items_escalated": 0
+  }
+}

package/dist/template/.pi/templates/loop-state.md

@@ -0,0 +1,98 @@
+---
+purpose: Human-readable working memory + dedup ledger mirror for one loop
+updated: <auto — last modified>
+---
+
+# Loop State
+
+<!--
+  Human-readable mirror of STATE.json. The machine ledger (STATE.json) is
+  authoritative for dedup; this file is for humans reading the loop's history.
+  Keep them in sync — the orchestrator writes STATE.json; update this file when
+  you review.
+-->
+
+**Loop name:** `<loop-name>`
+**Owner:** `[Owner]`
+**Cadence:** `[cron expression or "manual"]`
+
+---
+
+## Last run
+
+<!-- When did the loop last execute, and what happened. -->
+
+| Field     | Value                          |
+| --------- | ------------------------------ |
+| Timestamp | `[ISO-8601 or null]`           |
+| Status    | `[pass / fail / killed / no-op]` |
+| Duration  | `[seconds]`                    |
+| Items     | `[count processed this run]`  |
+| Tokens    | `[tokens used this run]`      |
+
+## In progress
+
+<!-- Items the loop is currently working on. Empty if idle. -->
+
+| Item ID | Type | Started | Note |
+| ------- | ---- | ------- | ---- |
+| `<id>` | `[ci-run / pr / package@version / commit-sha]` | `[ISO-8601]` | `[note]` |
+
+## Completed
+
+<!-- Items the loop finished this cycle (subset of Processed items below). -->
+
+| Item ID | Type | Completed | Outcome |
+| ------- | ---- | --------- | ------- |
+| `<id>` | `[type]` | `[ISO-8601]` | `[fixed / skipped / escalated / rejected]` |
+
+## Escalated
+
+<!-- Items the loop could not handle autonomously and escalated to a human. -->
+
+| Item ID | Type | Escalated | Reason |
+| ------- | ---- | --------- | ------ |
+| `<id>` | `[type]` | `[ISO-8601]` | `[why the loop could not act]` |
+
+## Lessons learned
+
+<!-- Durable lessons from prior runs. One line each; link to STATE.json.lessons[]. -->
+
+- `[Date]` — `[Lesson text]`
+- `[Date]` — `[Lesson text]`
+
+## Processed items
+
+<!--
+  Dedup ledger. Keyed by STABLE item IDs so re-running the orchestrator on an
+  already-processed item skips it (idempotent). Stable ID forms:
+    - CI run ID           e.g. `ci:12345678901`
+    - PR number           e.g. `pr:42`
+    - package@version     e.g. `pkg:lodash@4.17.21`
+    - commit SHA          e.g. `sha:abc1234`
+  Deleting STATE.json reprocesses everything.
+-->
+
+| Item ID | Type | First seen | Last status | Retries |
+| ------- | ---- | ---------- | ----------- | ------- |
+| `<stable-id>` | `[ci-run / pr / package / commit]` | `[ISO-8601]` | `[fixed / skipped / failed / escalated]` | `[n]` |
+
+## Stop conditions met
+
+<!-- Boolean flags from the VISION.md "Hard stops" list. All false = safe to run. -->
+
+| Stop condition | Met? |
+| -------------- | ---- |
+| Token budget exceeded | `[yes / no]` |
+| Protected path modified | `[yes / no]` |
+| Item already processed | `[yes / no]` |
+| `gh` not authenticated | `[yes / no]` |
+| Gate command missing/unparseable | `[yes / no]` |
+
+---
+
+<!--
+  This file is a mirror. The machine ledger (STATE.json) is the source of
+  truth for dedup and idempotence. Update this file when reviewing run history;
+  the orchestrator does not need to write here.
+-->

package/dist/template/.pi/templates/loop-vision.md

@@ -0,0 +1,110 @@
+---
+purpose: Anti goal-drift contract for a loop — reread at the start of every run; the loop must not act outside this file
+updated: <auto — last modified>
+---
+
+# Loop Vision
+
+<!--
+  This file is the immutable contract for one loop. The orchestrator (and any
+  interactive run) MUST reread this file at the start of every cycle and treat
+  its boundaries as authoritative. If context summarization drops a constraint
+  mid-run, this file restores it (boundaries are re-derived from disk, not
+  from context).
+
+  Fill the bracketed placeholders via `/loop-init <name>`, then edit by hand.
+  Never let a run edit this file during a cycle (protected path — see
+  loop-guard.ts).
+-->
+
+**Loop name:** `<loop-name>`
+**Owner:** `[Owner]`
+**Cadence:** `[cron expression or "manual"]`
+**Created:** `[Date]`
+**Last revised:** `[Date]`
+
+---
+
+## Goal
+
+<!-- One sentence: the outcome this loop produces, outcome-shaped not task-shaped. -->
+
+[What does this loop achieve? e.g. "Triage failing CI runs nightly and open fix PRs for deterministic failures."]
+
+## Scope
+
+<!-- What the loop is allowed to touch. Be concrete: file paths, package names, commands. -->
+
+- [Allowed action 1: e.g. edit source under `src/`]
+- [Allowed action 2: e.g. run `npm test` / `npm run lint`]
+- [Allowed action 3: e.g. open a PR on branch `loop/<name>/<ts>` — never `main`]
+
+## Out-of-scope
+
+<!-- What the loop must NEVER do, even if asked. Hard refuses. -->
+
+- [Refuse 1: e.g. auth / payments / architecture changes]
+- [Refuse 2: e.g. editing `package.json`, lockfiles, or this VISION.md / the gate script]
+- [Refuse 3: e.g. merging or deploying — human approval required]
+
+## Definition-of-done
+
+<!-- Observable, verifiable end state. Must be checkable by the Gate command (exit 0). -->
+
+- [ ] [Criterion 1: e.g. `npm test` exits 0]
+- [ ] [Criterion 2: e.g. diff is limited to in-scope paths]
+- [ ] [Criterion 3: e.g. a PR is open on `loop/<name>/<ts>` with a body citing this file]
+
+## Gate
+
+<!--
+  PARSE CONTRACT (machine-readable — do NOT edit this comment):
+    The orchestrator extracts the gate command from the SINGLE fenced
+    ```bash block located directly under the "## Gate" heading in this file.
+    Extraction rule: require EXACTLY ONE ```bash block in this section
+    (bounded by the next "## " heading). Zero or more-than-one -> refuse
+    (gate not parseable; orchestrator records failure and does NOT ship).
+    Take that single block's content, strip trailing whitespace, run it via
+    `bash -c "<command>"`, read the exit code.
+      exit 0   -> PASS  -> ship (push branch `loop/<name>/<ts>` + open PR)
+      non-zero -> FAIL  -> no ship; record failure in STATE.json; cleanup worktree
+    The gate decision is computational (exit code), never an LLM's opinion.
+    Keep EXACTLY ONE ```bash block directly under ## Gate.
+-->
+
+Command (exit 0 = pass):
+
+```bash
+<GATE_COMMAND>
+```
+
+**Pass:** exit 0 → ship (push `loop/<name>/<ts>` branch + open PR via `gh`).
+**Fail:** non-zero → no ship; record failure in `STATE.json.failures[]`; cleanup worktree.
+
+## Hard stops
+
+<!-- Conditions that abort the run immediately, no matter the gate result. -->
+
+- [Hard stop 1: e.g. token budget exceeded (`STATE.json.metrics.tokens_used > cap`)]
+- [Hard stop 2: e.g. gate file / VISION.md / `package.json` modified during the run]
+- [Hard stop 3: e.g. item already in `STATE.json.processed` → idempotent skip]
+- [Hard stop 4: e.g. `gh` not authenticated → fall back to commit-only/log, do not ship]
+
+## Human-approval-required
+
+<!-- Actions the loop may stage but never execute on its own. -->
+
+- [ ] Merging a PR
+- [ ] Deploying to production
+- [ ] Changing dependencies (`package.json`, lockfiles, version bumps)
+- [ ] Modifying this VISION.md or the Gate command mid-run
+- [ ] Touching auth, payments, or architectural decisions
+
+---
+
+<!--
+  Reread this file at the start of every run. The loop must not act outside
+  this file. If a proposed action is not clearly inside Scope, treat it as
+  Out-of-scope and escalate (record in STATE.json.escalated[]) instead of
+  acting.
+-->

package/dist/template/.pi/templates/prd.md

@@ -0,0 +1,204 @@
+# PRD Template
+
+> **Template Instructions:**
+>
+> - Replace ALL bracketed placeholders with real content
+> - If you cannot fill a section with confidence, use `[NEEDS CLARIFICATION: reason]` instead of guessing
+> - Any `[NEEDS CLARIFICATION]` markers MUST be resolved before planning can proceed
+> - Delete this instruction block after filling the template
+
+**Slug:** <feature-slug>   
+**Created:** [date]   
+**Status:** Draft | In Review | Approved
+
+## Feature Metadata
+
+```yaml
+slug: <feature-slug>          # kebab-case, written to .pi/artifacts/.active
+depends_on: [] # Feature slugs that must complete before this one
+parallel: true # Can run concurrently with other parallel features
+conflicts_with: [] # Feature slugs that modify same files (cannot parallelize)
+blocks: [] # Feature slugs waiting on this one
+estimated_hours: 2 # Time estimate for planning
+```
+
+---
+
+## Problem Statement
+
+### What problem are we solving?
+
+[Clear description of the problem. Include user impact and business impact. If unclear, use [NEEDS CLARIFICATION: what specifically is unknown]]
+
+### Why now?
+
+[What triggered this work? Cost of inaction? Use [NEEDS CLARIFICATION] if motivation is unclear]
+
+### Who is affected?
+
+- **Primary users:** [Description]
+- **Secondary users:** [Description]
+
+---
+
+## Scope
+
+### In-Scope
+
+- [List what's in scope. Use [NEEDS CLARIFICATION] for ambiguous boundaries]
+
+### Out-of-Scope
+
+- [List what's explicitly off-limits. Use [NEEDS CLARIFICATION] for unresolved scope questions]
+- [Deferred to future iterations]
+
+---
+
+## Proposed Solution
+
+### Overview
+
+[One paragraph describing what this feature does when complete. Use [NEEDS CLARIFICATION] for uncertain design decisions]
+
+### User Flow (if user-facing)
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+---
+
+## Requirements
+
+### Functional Requirements
+
+#### [Requirement Name]
+
+Brief description of what must be true.
+
+**Scenarios:**
+
+- **WHEN** [precondition or trigger] **THEN** [expected outcome]
+- **WHEN** [edge case condition] **THEN** [expected behavior]
+
+### Non-Functional Requirements
+
+- **Performance:** [constraint if applicable]
+- **Security:** [constraint if applicable]
+- **Accessibility:** [WCAG level if applicable]
+- **Compatibility:** [constraint if applicable]
+
+> If any requirement is unknown or unresearched, mark it `[NEEDS CLARIFICATION: what needs investigation]` rather than omitting it.
+
+---
+
+## Success Criteria
+
+- [ ] [Specific, measurable criterion 1]
+  - Verify: `[command or manual check]`
+- [ ] [Specific, measurable criterion 2]
+  - Verify: `[command or manual check]`
+
+---
+
+## Technical Context
+
+### Existing Patterns
+
+- Pattern 1: `src/path/to/example.ts` - Why relevant
+
+### Key Files
+
+- `src/relevant/file.ts` - Why relevant
+
+### Affected Files
+
+Files this feature will modify (for conflict detection):
+
+```yaml
+files:
+  - src/path/to/file.ts # Why
+  - src/path/to/other.ts # Why
+```
+
+---
+
+## Risks & Mitigations
+
+| Risk   | Likelihood   | Impact       | Mitigation      |
+| ------ | ------------ | ------------ | --------------- |
+| Risk 1 | High/Med/Low | High/Med/Low | How to mitigate |
+
+---
+
+## Open Questions
+
+| Question   | Owner | Due Date | Status        |
+| ---------- | ----- | -------- | ------------- |
+| Question 1 | Name  | Date     | Open/Resolved |
+
+> **All `[NEEDS CLARIFICATION]` markers should be converted to entries in this table for tracking.**
+
+---
+
+## Tasks
+
+High-level task outline only. Authoritative decomposition is `/plan`'s job (writes `plan.md` + `tasks.json`). Use `.pi/templates/tasks.md` for the detailed task body format.
+
+**Rules:**
+
+- Each task is a `### <Title> [category]` heading
+- Provide one sentence describing the end state
+- Include `**Metadata:**` with dependency info
+- Include `**Verification:**` with bullet steps proving it works
+
+### <Task Title> [category]
+
+<One sentence describing the end state>
+
+**Metadata:**
+
+```yaml
+depends_on: [] # Task titles that must complete first
+parallel: true # Can run with other parallel tasks
+conflicts_with: [] # Task titles modifying same files
+files: [] # Files this task will modify
+```
+
+**Verification:**
+
+- [Command or check]
+- [Command or check]
+
+### <Task Title> [category]
+
+<One sentence describing the end state>
+
+**Metadata:**
+
+```yaml
+depends_on: ["<Previous Task Title>"]
+parallel: false
+files: []
+```
+
+**Verification:**
+
+- [Command or check]
+
+---
+
+## Dependency Legend
+
+| Field            | Purpose                                           | Example                                    |
+| ---------------- | ------------------------------------------------- | ------------------------------------------ |
+| `depends_on`     | Must complete before this task starts             | `["Setup database", "Create schema"]`      |
+| `parallel`       | Can run concurrently with other parallel tasks    | `true` / `false`                           |
+| `conflicts_with` | Cannot run in parallel (same files)               | `["Update config"]`                        |
+| `files`          | Files this task modifies (for conflict detection) | `["src/db/schema.ts", "src/db/client.ts"]` |
+
+---
+
+## Notes
+
+[Additional context, constraints, or decisions]

package/dist/template/.pi/templates/progress.md

@@ -0,0 +1,55 @@
+# Progress — <feature-slug>
+
+> **Purpose:** Append-only log for `/ship`, `/verify`, `/fix`, and `/close`. Each entry is a short, dated line. Lives at `.pi/artifacts/$SLUG/progress.md`. Not a fill-in template — created empty per feature and appended to during execution.
+
+**Spec:** `.pi/artifacts/$SLUG/spec.md`
+**Started:** [YYYY-MM-DD]
+
+---
+
+## Entries
+
+<!-- Append one block per significant event. Keep entries under 3 lines each. -->
+
+### [YYYY-MM-DD HH:MM] — <command>
+- **Action:** <what was done>
+- **Result:** <PASS|FAIL|PARTIAL|BLOCKED> — <one-line summary>
+- **Files:** <list or "none">
+
+### [YYYY-MM-DD HH:MM] — /verify
+- **Result:** PASS — typecheck ✓, lint ✓, test 42/42
+- **Mode:** full
+- **Phantom:** CLEAN
+
+### [YYYY-MM-DD HH:MM] — /ship
+- **Task:** task-3 — <title>
+- **Commit:** <hash> <subject>
+- **Verification:** PASS
+
+### [YYYY-MM-DD HH:MM] — /close
+- **Outcome:** done
+- **Note:** <user note or empty>
+
+---
+
+## Entry Format
+
+```
+### [ISO timestamp] — <command>
+- **Action|Result|Task|Commit|Verification|Mode|Phantom|Outcome|Note:** <value>
+```
+
+**Rules:**
+- One top-level `###` block per event.
+- Never delete past entries — append only.
+- If a gate fails, record the failure with file:line evidence in the summary.
+- `/close` appends a final outcome block and stops.
+
+## Linked Artifacts
+
+- `spec.md` — the PRD
+- `plan.md` — authoritative task decomposition (from `/plan`)
+- `tasks.json` — runtime task status (from `/plan`, updated by `/ship`)
+- `verify.log` — verification cache stamp (from `/verify`)
+- `review-state.json` — quality-loop state (if high-risk mode ran)
+- `audit.md` / `research.md` — optional command outputs

package/dist/template/.pi/templates/project.md

@@ -0,0 +1,58 @@
+---
+purpose: Project vision, goals, and success criteria (loaded into all AI contexts)
+updated: <auto — last modified>
+---
+
+# Project Vision
+
+## The Goal
+
+<!-- One sentence: What does this project achieve? Outcome-shaped, not task-shaped. -->
+<!-- Good: "A real-time chat application with persistent message history" -->
+<!-- Bad: "Build chat components and API endpoints" -->
+
+## Success Criteria
+
+<!-- How do we know the project is successful? List 3-7 observable outcomes. -->
+<!-- Each should be verifiable by using the application, not by checking code. -->
+
+1. **[Criterion 1]** - [Specific, measurable outcome]
+2. **[Criterion 2]** - [Specific, measurable outcome]
+3. **[Criterion 3]** - [Specific, measurable outcome]
+
+## Target Users
+
+<!-- Who will use this? What do they need? -->
+
+- **Primary:** [User type and their core need]
+- **Secondary:** [User type and their core need]
+
+## Core Principles
+
+<!-- Non-negotiable principles that guide all decisions -->
+
+1. **[Principle 1]** - [Explanation]
+2. **[Principle 2]** - [Explanation]
+3. **[Principle 3]** - [Explanation]
+
+## Current Phase
+
+<!-- Where are we in the project lifecycle? -->
+
+- **Status:** [Discovery / Planning / Implementation / Polish / Maintenance]
+- **Milestone:** [Current milestone name]
+- **Next Milestone:** [Next milestone name]
+
+## Key Links
+
+<!-- Important references -->
+
+- **Repository:** [URL]
+- **Documentation:** [URL]
+- **Staging:** [URL]
+- **Production:** [URL]
+
+---
+
+_Update this file when project direction or phase changes._
+_AI uses this to maintain context across sessions and make decisions aligned with project goals._

package/dist/template/.pi/templates/proposal.md

@@ -0,0 +1,40 @@
+# Proposal
+
+> **Purpose:** Lightweight change proposal used manually for small/routine changes that don't warrant a full PRD. Pair with `.pi/templates/adr.md` when the proposal locks in a decision. Not wired into a command by default.
+
+**Feature:** [feature-slug]   
+**Author:** [author]
+**Date:** [YYYY-MM-DD]
+
+## Why
+
+<!-- What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- High-level description of the proposed changes -->
+
+## Capabilities
+
+### New Capabilities
+
+- `capability-name`: Brief description of what it enables
+
+### Modified Capabilities
+
+- `capability-name`: How existing behavior changes
+
+## Impact
+
+### Users Affected
+
+- [User type or system]
+
+### Migration Required
+
+- [ ] Yes / No
+- If yes: [brief migration notes]
+
+## Open Questions
+
+- [ ] [Question that needs answering before proceeding]

package/dist/template/.pi/templates/review-state.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft-2020-12/schema",
+  "$comment": "Runtime state for the quality-loop workflow. Created/updated at .pi/artifacts/$SLUG/review-state.json by quality-loop Phase 1. Not a context template — a runtime artifact schema.",
+  "slug": "<feature-slug>",
+  "rounds": 0,
+  "maxRounds": 5,
+  "lastScore": 0,
+  "sameScoreCount": 0,
+  "findingsResolved": 0,
+  "findingsRemaining": 0,
+  "status": "active",
+  "history": [
+    {
+      "round": 1,
+      "score": 0,
+      "findings": 0,
+      "timestamp": "<ISO 8601>"
+    }
+  ]
+}

package/dist/template/.pi/templates/roadmap.md

@@ -0,0 +1,93 @@
+---
+purpose: Project roadmap with phases, milestones, and feature organization
+updated: <auto — last modified>
+---
+
+# Roadmap
+
+## Overview
+
+<!-- High-level project breakdown -->
+
+| Phase     | Goal                | Status        | Features |
+| --------- | ------------------- | ------------- | ----- |
+| [Phase 1] | [One-sentence goal] | [Not Started] | [#]   |
+| [Phase 2] | [One-sentence goal] | [Not Started] | [#]   |
+| [Phase 3] | [One-sentence goal] | [Not Started] | [#]   |
+
+## Phase 1: [Name]
+
+**Goal:** [Outcome-shaped description]
+
+**Success Criteria:**
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+**Features:**
+| ID | Title | Type | Status | Depends On |
+|----|-------|------|--------|------------|
+| <slug> | [Title] | task | open | - |
+| <slug> | [Title] | task | open | <slug> |
+
+**Out of Scope:**
+
+- [What's explicitly deferred to later phases]
+
+---
+
+## Phase 2: [Name]
+
+**Goal:** [Outcome-shaped description]
+
+**Success Criteria:**
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+**Features:**
+| ID | Title | Type | Status | Depends On |
+|----|-------|------|--------|------------|
+| <slug> | [Title] | feature | open | Phase 1 |
+
+**Dependencies:**
+
+- Requires Phase 1 completion
+
+---
+
+## Phase 3: [Name]
+
+**Goal:** [Outcome-shaped description]
+
+**Success Criteria:**
+
+- [ ] [Criterion 1]
+
+**Features:**
+| ID | Title | Type | Status | Depends On |
+|----|-------|------|--------|------------|
+| <slug> | [Title] | epic | open | Phase 2 |
+
+---
+
+## Legend
+
+**Status:**
+
+- `Not Started` - No work begun
+- `In Progress` - Active development
+- `Complete` - All tasks closed
+
+**Type:**
+
+- `task` - Tactical, single-session work
+- `feature` - New capability, multi-session
+- `epic` - Cross-domain, significant scope
+- `bug` - Fix for broken behavior
+
+---
+
+_Update this file when phases complete or roadmap changes._
+_Use `/plan` command to create detailed plans for active phases._