@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: spec-driven-development
+description: Guides agents from vague request to concrete specification before implementation. Use when starting a new feature, significant change, product idea, or when requirements are ambiguous.
+---
+
+# Spec-Driven Development
+
+## Overview
+
+A spec converts intent into testable truth. Code written before the target is clear becomes rework.
+
+Core principle: define observable outcomes, constraints, non-goals, and verification before planning implementation.
+
+**Define the vocabulary first.** Every concept in the spec should have one name — that name must match what the code will call it. This is Evans' "ubiquitous language": a shared vocabulary between developers, domain experts, code, and AI context files. Ambiguous language in the spec causes the "AI does the wrong thing" failure mode: the LLM implements what the words say, not what you meant.
+
+After writing the spec, extract a glossary of terms. Every capitalized concept in the spec should correspond to exactly one code symbol (type, class, module, function, file). If two terms mean the same thing, pick one. If one term means two things, split it.
+
+## When to Use
+
+- User asks for a new feature or significant behavior change.
+- Requirements are vague, conflicting, or missing edge cases.
+- Multiple files/systems will be affected.
+- The work needs acceptance criteria or user-visible behavior.
+
+## When NOT to Use
+
+- Tiny mechanical edits with obvious expected behavior.
+- Emergency bug fixes where reproduction is already clear; use `debugging-and-error-recovery`.
+- Pure research with no implementation decision; use `source-driven-development`.
+
+## Gated Workflow
+
+Every change passes through four locked gates. Do not open the next gate until the current one is approved.
+
+1. **SPECIFY** — lock intent.
+   1. State the goal as an outcome, not a task.
+   2. **Establish vocabulary**: define the key terms and map them to code concepts.
+   3. Derive 3-7 observable truths from the user's perspective.
+   4. Identify constraints: technical, UX, security, performance, compatibility.
+   5. Define non-goals to prevent scope creep.
+   6. List affected surfaces: files, APIs, commands, UI screens, data models.
+   7. **Check vocabulary consistency**: does every spec term map to exactly one code symbol? Are any terms overloaded?
+   8. Reframe instructions as success criteria (see pattern below).
+   - **Gate**: spec approved or assumptions explicitly accepted.
+2. **PLAN** — lock approach. Hand off to `planning-and-task-breakdown`.
+   - **Gate**: plan approved.
+3. **TASKS** — lock units. Break plan into verifiable beads/tasks with owners.
+   - **Gate**: task list approved.
+4. **IMPLEMENT** — lock behavior. Code against the spec; update spec when reality diverges.
+   - **Gate**: verification checklist passes.
+
+Human gates are binary: approve, change, or cancel. Do not sneak work through an unapproved gate.
+
+## Reframe Instructions as Success Criteria
+
+Turn every "do X" request into a verifiable "X is true when..." statement. If the user says "make it faster", write "Page load time is under 1.0 s on 3G for the dashboard route". If the user says "support CSV import", write "A CSV with 10,000 rows is imported without OOM and produces a row-level error report".
+
+Use this pattern inside the Spec Template under Acceptance Criteria.
+
+## Spec Template
+
+```markdown
+# Spec: [Name]
+
+## Goal
+[Outcome in one sentence]
+
+## Vocabulary
+| Term | Definition | Code symbol |
+|------|------------|-------------|
+| ...  | ...        | ...         |
+
+Every concept should have one name. If two terms mean the same thing, consolidate. If one term means two things, split it.
+
+## Observable Truths
+- [User/system can observe X]
+
+## Constraints
+- [Hard constraint]
+
+## Non-Goals
+- [Explicitly out of scope]
+
+## Affected Surfaces
+- [File/API/UI/data area]
+
+## Acceptance Criteria
+- [Criterion] -> verify with [command/check/manual observation]
+
+## Open Questions
+- [Question or none]
+```
+
+## Six Core Areas
+
+A complete spec covers these six areas. Use them as a final completeness check before the SPECIFY gate closes.
+
+| Area | Question to answer |
+| --- | --- |
+| **Objective** | What user/system outcome must be true after this change? |
+| **Commands** | What CLI/API/user commands are added, changed, or removed? |
+| **Project Structure** | What files, modules, or packages move or appear? |
+| **Code Style** | What patterns, naming, or formatting rules apply? |
+| **Testing Strategy** | How will correctness be proven? Unit, integration, manual? |
+| **Boundaries** | What is always in scope, ask-first, and never allowed? |
+
+## Three-Tier Boundary System
+
+Define boundaries before coding. Use the tiers to resolve "should I do this?" questions during implementation.
+
+| Tier | Rule | Examples |
+| --- | --- | --- |
+| **Always do** | Required by the spec; no extra approval. | Input validation, error handling for listed edge cases, update affected tests. |
+| **Ask first** | Changes design, scope, or risk; get user approval. | New dependency, schema change, new public API, removing a feature. |
+| **Never do** | Explicitly out of scope. | Rewrite unrelated modules, change secrets, ship without verification. |
+
+## Keeping the Spec Alive
+
+A spec is not a tombstone. Update it when:
+
+- Implementation reveals an edge case not in the original spec.
+- The user changes a requirement mid-flight.
+- A constraint turns out to be wrong or unnecessary.
+- The glossary term-to-symbol mapping changes.
+
+If the spec changes, re-validate the acceptance criteria and re-approve the SPECIFY gate before continuing.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+| --- | --- |
+| "The user already explained it" | Explanation is not acceptance criteria. Write the target down. |
+| "I'll discover requirements while coding" | Discovery during coding causes churn and hidden scope expansion. |
+| "This is obvious" | Obvious to you is not a contract for the next agent or reviewer. |
+| "The AI will figure out what I mean" | The AI will implement exactly what the spec says. Ambiguous language = wrong implementation. |
+| "Questions slow us down" | One precise question is cheaper than implementing the wrong behavior. |
+| "The spec is good enough, I'll add gates later" | Later rarely comes. Unapproved gates let scope and risk leak through. |
+
+## Red Flags
+
+- No explicit non-goals for a broad feature.
+- Acceptance criteria are phrased as implementation tasks.
+- Edge cases are deferred without user agreement.
+- The plan starts before observable truths are defined.
+- User-visible behavior has no verification method.
+- **No vocabulary section** — missing ubiquitous language means AI will guess term meanings.
+- **Same term used for different concepts** — e.g. "Order" means creation flow in one place and fulfillment in another.
+- **Different terms for the same concept** — e.g. "User" vs "Account" vs "Profile" used interchangeably.
+- Skipping a human gate because "the change is small".
+- Boundaries are missing, so the agent must decide scope on the fly.
+
+## Verification Checklist
+
+- [ ] Goal is outcome-shaped, not task-shaped.
+- [ ] Vocabulary table exists and every term maps to exactly one code symbol.
+- [ ] No overloaded terms or synonyms in the glossary.
+- [ ] Observable truths are human-verifiable.
+- [ ] Constraints are explicit (technical, UX, security, performance, compatibility).
+- [ ] Non-goals are listed and realistic.
+- [ ] Affected surfaces are named with file/API/UI/data area paths.
+- [ ] Acceptance criteria are reframed as success criteria with verification methods.
+- [ ] Three-tier boundaries are defined.
+- [ ] Open questions are resolved or recorded as assumptions with risk.
+- [ ] At most 1-4 focused questions are pending.
+- [ ] Human gate approval is recorded before moving to PLAN.
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>spec-driven-development</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Spec sections completed and questions/assumptions recorded</evidence>
+  <artifacts>Spec path or inline spec summary</artifacts>
+  <risks>Unresolved assumptions or none</risks>
+</skill_result>
+```

package/dist/template/.pi/skills/srcwalk/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: srcwalk
+description: Use when navigating code with srcwalk — repo maps, large-file reads, symbol search, callers/callees, flow slices, impact checks, and precise drill-ins.
+---
+
+# Srcwalk — Code Navigation
+
+Srcwalk is the project's code navigation engine (v1.0.0+). All Pi tools are backed by the installed `srcwalk` binary.
+
+Run the embedded guide before non-trivial use — it is the version-matched source of truth:
+
+```bash
+srcwalk guide
+```
+
+Do not pipe, truncate, or summarize `srcwalk guide`.
+
+## When to Use
+
+- Any code navigation task: symbol search, large-file reading, repo maps
+- Tracing call graphs (callers, callees, transitive chains)
+- Checking blast radius before breaking changes
+- Understanding repo shape and token budgets
+- Quick function orientation (flow slice)
+- Heuristic impact triage
+
+## When NOT to Use
+
+- Non-code files where tree-sitter has no grammar → use `read` directly
+- Simple one-off reads of small known files → use built-in `read`
+
+## Pi Tool Surface
+
+### Core navigation tools
+
+| Tool | Srcwalk command | Purpose |
+|---|---|---|
+| `srcwalk_read` | `srcwalk <path>` | Smart file reading: outline or full with sections |
+| `srcwalk_deps` | `srcwalk deps` + exact import scan | Blast-radius: importers + dep-aware dependents (v1.0.0) |
+
+### Extended analysis tools
+
+| Tool | Srcwalk command | Purpose |
+|---|---|---|
+| `srcwalk_map` | `srcwalk overview` | Token-annotated directory skeleton + dep groups (v1.0.0) |
+| `srcwalk_callers` | `srcwalk trace callers` | Reverse call graph with BFS depth + filters |
+| `srcwalk_callees` | `srcwalk trace callees` | Forward call graph with `--detailed` ordered call sites |
+| `srcwalk_flow` | `srcwalk context` | Compact orientation slice |
+| `srcwalk_impact` | `srcwalk assess` | Heuristic blast-radius triage |
+
+## Command Routing
+
+| Intent | Use first |
+|---|---|
+| Understand repo shape | `srcwalk_map` |
+| Read or inspect a large file | `srcwalk_read` |
+| Jump to exact line | `srcwalk_read({ path: "file:42" })` |
+| Read a line range | `srcwalk_read({ path: "file:44-89" })` — v1.0.0 shortcut |
+| Read by symbol name | `srcwalk_read({ section: "symbolName" })` |
+| Find patterns and symbols | `grep` (exact), `csearch` (multi-keyword) |
+| Find files by glob | `glob` |
+| Multi-symbol search | `grep({ pattern: "A|B|C" })` |
+| Who directly calls this? | `srcwalk_callers` |
+| Who reaches this transitively? | `srcwalk_callers({ depth: 2 })` |
+| What does this call? | `srcwalk_callees` |
+| Ordered calls + arg slots | `srcwalk_callees({ detailed: true })` |
+| Quick orientation slice | `srcwalk_flow` |
+| File imports and dependents | `srcwalk_deps` |
+| Heuristic blast-radius | `srcwalk_impact` (verify with callers) |
+
+## Default Workflows
+
+### Explore unfamiliar code
+
+```
+srcwalk_map({ scope: "." })
+grep({ pattern: "likely_symbol", path: "src/" })
+srcwalk_read({ path: "src/file.ts:42" })         // jump to line
+srcwalk_read({ path: "src/file.ts:44-89" })      // range shortcut (v1.0.0)
+```
+
+### Read a large file
+
+```
+srcwalk_read({ path: "src/file.ts" })                        // structural outline
+srcwalk_read({ path: "src/file.ts", section: "handleAuth" }) // drill into symbol
+srcwalk_read({ path: "src/file.ts", section: "44-89" })      // exact range
+```
+
+Prefer outline/section reads before `full: true`.
+
+### Find and drill into symbols
+
+```
+grep({ pattern: "handleAuth", path: "src/" })
+grep({ pattern: "A|B|C", path: "src/" })                     // multi-symbol
+csearch({ query: "auth token login middleware" })          // multi-keyword chunk search
+```
+
+### Trace call graph
+
+```
+// upstream
+srcwalk_callers({ symbol: "handleAuth", scope: "src" })
+srcwalk_callers({ symbol: "handleAuth", depth: 2, scope: "src" })      // transitive
+srcwalk_callers({ symbol: "handleAuth", filter: "args:3", scope: "src" })
+srcwalk_callers({ symbol: "handleAuth", countBy: "file", scope: "src" })
+
+// downstream
+srcwalk_callees({ symbol: "handleAuth", scope: "src" })
+srcwalk_callees({ symbol: "handleAuth", detailed: true, scope: "src" }) // ordered sites
+srcwalk_callees({ symbol: "handleAuth", depth: 2, scope: "src" })       // transitive
+
+// quick orientation
+srcwalk_flow({ symbol: "handleAuth", scope: "src" })
+```
+
+Use `grep` for quick single-hop searches. Use `srcwalk_callers` when you need depth, filters, or aggregation.
+
+> Note: `--count-by` and `--depth` are mutually exclusive in `srcwalk_callers` — use one or the other, not both.
+
+### Check file blast radius
+
+```
+srcwalk_deps({ path: "src/auth.ts" })
+srcwalk_impact({ symbol: "handleAuth", scope: "src" })  // heuristic; follow up with callers
+```
+
+## v1.0.0 Features
+
+- **Path range shortcut**: `srcwalk_read({ path: "file:start-end" })` reads a line range directly — no need to pass `section` separately
+- **Dependency-aware map**: `srcwalk_map` now shows local relation groups and outbound dependency previews for narrowed scopes
+- **JS/TS artifact navigation**: bundle anchors, artifact reads, artifact search snippets, and artifact caller/callee support
+- **Improved UX**: more compact semantic rows, directory grouping, footer tips, and clearer scope/depth wording across all commands
+
+## Critical Rules
+
+- **Do NOT** use built-in `read`/`find` when srcwalk_* tools can answer; `grep` is preferred for text searches
+- `srcwalk_impact` is heuristic, not proof — verify with `srcwalk_callers` or exact reads
+- `srcwalk_flow` may collapse nested/fluent chains — drill with `srcwalk_callees({ detailed: true })` when inner calls matter
+- Follow `> Next:` footers in output — they suggest the best next command
+- Scope paths are **relative to Pi's CWD** (`.pi/` in this project). Use `scope: "extensions"` not `scope: ".pi/extensions"`
+
+## Supported Languages
+
+Rust, TypeScript, TSX, JavaScript, Python, Go, Java, Scala, C, C++, Ruby, PHP, C#, Swift, Elixir, Kotlin. Unsupported files still get smart text/outline reads.
+
+## Setup
+
+The srcwalk plugin is auto-discovered via `pi-srcwalk` (installed as `npm:@sting8k/pi-srcwalk`). See `## Pi Note` below for equivalent tools.
+
+All scope paths are relative to the **project root directory**. The default scope resolves from the project root.
+
+## Pi Note
+
+In Pi, srcwalk is superseded by `pi-srcwalk` (auto-installed via `npm:@sting8k/pi-srcwalk` in `settings.json`). Use the equivalent semantic tools: `semantic_query`, `semantic_inspect`, `semantic_grep`, `semantic_show`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I know the codebase well enough" | Codebases change faster than memory. Verify assumptions with actual code reads. |
+| "Grep is faster than srcwalk" | Grep finds text. Srcwalk finds symbols, callers, impact — richer context for decisions. |
+| "I'll just read the file directly" | Direct reads miss callers and impact. Srcwalk shows the blast radius. |
+
+## Red Flags
+
+- Code changes made without checking callers
+- Symbol search skipped — relying on filename-based assumptions
+- Impact analysis not run before breaking changes
+- File reads without srcwalk context (missing caller/callee relationships)
+- Large-scale refactors started without dependency graph check
+
+## Verification
+
+After navigating code with srcwalk:
+
+- [ ] Callers of modified functions are identified and reviewed
+- [ ] Impact analysis run for any breaking changes
+- [ ] Symbol definitions verified (not assumed from filename)
+- [ ] Dependency graph checked before large-scale restructuring
+- [ ] File reads include surrounding context (callers + callees)

package/dist/template/.pi/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: subagent-driven-development
+description: Use when executing implementation plans with independent tasks in the current session - dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates
+---
+
+# Subagent-Driven Development
+
+> **Replaces** monolithic single-agent implementation sessions that grow stale — dispatches fresh subagents per task with code review gates between them
+
+## When to Use
+
+- Executing a plan with mostly independent tasks in the same session
+- You want a fresh subagent per task plus review checkpoints
+
+## When NOT to Use
+
+- The plan requires review or revisions first (use `incremental-implementation`)
+- Tasks are tightly coupled and need manual sequencing
+
+## Overview
+
+**vs. Executing Plans (parallel session):**
+
+- Same session (no context switch)
+- Fresh subagent per task (no context pollution)
+- Code review after each task (catch issues early)
+- Faster iteration (no human-in-loop between tasks)
+
+## The Process
+
+### 1. Load Plan
+
+Read plan file, create TodoWrite with all tasks.
+
+**Context file pattern:** If the plan exceeds ~500 tokens, write it to `.pi/artifacts/plan-context.md` and reference by path in subagent prompts instead of inlining. This saves tokens when dispatching multiple subagents from the same plan.
+
+### 2. Execute Task with Subagent
+
+For each task:
+
+**Dispatch fresh subagent:**
+
+```
+Task tool (general-purpose):
+  description: "Implement Task N: [task name]"
+  prompt: |
+    You are implementing Task N from [plan-file].
+
+    Read that task carefully. Your job is to:
+    1. Implement exactly what the task specifies
+    2. Write tests (following TDD if task says to)
+    3. Verify implementation works
+    4. Commit your work
+    5. Report back
+
+    Work from: [directory]
+
+    [Include Structured Termination Contract from AGENTS.md]
+```
+
+**After subagent reports back** — follow the **Worker Distrust Protocol** from AGENTS.md:
+
+1. Read changed files directly (don't trust the report)
+2. Run verification on modified files (typecheck + lint minimum)
+3. Check acceptance criteria against original task spec
+4. Only then mark the task as complete
+
+### 3. Review Subagent's Work
+
+**Dispatch review subagent:**
+
+Use the review format from the `code-review-and-quality` skill (severity-ranked findings: P0/P1/P2/P3 with file:line + suggestion). Pass to the review subagent:
+
+WHAT_WAS_IMPLEMENTED: [from subagent's report]
+PLAN_OR_REQUIREMENTS: Task N from [plan-file]
+BASE_SHA: [commit before task]
+HEAD_SHA: [current commit]
+DESCRIPTION: [task summary]
+
+```
+
+**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
+
+### 4. Apply Review Feedback
+
+**If issues found:**
+
+- Fix Critical issues immediately
+- Fix Important issues before next task
+- Note Minor issues
+
+**Dispatch follow-up subagent if needed:**
+
+```
+
+"Fix issues from code review: [list issues]"
+
+```
+
+### 5. Mark Complete, Next Task
+
+- Mark task as completed in TodoWrite
+- Move to next task
+- Repeat steps 2-5
+
+### 6. Final Review
+
+After all tasks complete, dispatch final review:
+
+- Reviews entire implementation
+- Checks all plan requirements met
+- Validates overall architecture
+
+### 7. Complete Development
+
+After final review passes:
+
+- Announce: "I'm using `shipping-and-launch` skill to complete this work."
+- **REQUIRED SUB-SKILL:** Load `shipping-and-launch` skill (auto-discovered from `.pi/skills/`)
+- Follow that skill to verify tests, present options, execute choice
+
+## Example Workflow
+
+```
+
+You: I'm using Subagent-Driven Development to execute this plan.
+
+[Load plan, create TodoWrite]
+
+Task 1: Hook installation script
+
+[Dispatch implementation subagent]
+Subagent: Implemented install-hook with tests, 5/5 passing
+
+[Get git SHAs, dispatch review]
+Reviewer: Strengths: Good test coverage. Issues: None. Ready.
+
+[Mark Task 1 complete]
+
+Task 2: Recovery modes
+
+[Dispatch implementation subagent]
+Subagent: Added verify/repair, 8/8 tests passing
+
+[Dispatch review]
+Reviewer: Strengths: Solid. Issues (Important): Missing progress reporting
+
+[Dispatch fix subagent]
+Fix subagent: Added progress every 100 conversations
+
+[Verify fix, mark Task 2 complete]
+
+...
+
+[After all tasks]
+[Dispatch final review]
+Final reviewer: All requirements met, ready to merge
+
+Done!
+
+```
+
+## Advantages
+
+**vs. Manual execution:**
+
+- Subagents follow TDD naturally
+- Fresh context per task (no confusion)
+- Parallel-safe (subagents don't interfere)
+
+**vs. Executing Plans:**
+
+- Same session (no handoff)
+- Continuous progress (no waiting)
+- Review checkpoints automatic
+
+**Cost:**
+
+- More subagent invocations
+- But catches issues early (cheaper than debugging later)
+
+## Red Flags
+
+**Never:**
+
+- Skip code review between tasks
+- Proceed with unfixed Critical issues
+- Dispatch multiple implementation subagents in parallel (conflicts)
+- Implement without reading plan task
+
+**If subagent fails task:**
+
+- Dispatch fix subagent with specific instructions
+- Don't try to fix manually (context pollution)
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Dispatching subagents for tasks with shared state/files | Creates edit conflicts, race conditions, and unclear ownership | Keep shared-state work sequential under one subagent at a time |
+| Skipping code review between subagent tasks | Lets defects accumulate and compounds later fixes | Run a review gate after each task before moving on |
+| Giving subagents vague prompts without file paths or acceptance criteria | Produces off-target changes and repeated back-and-forth | Provide exact file paths, task scope, and acceptance criteria |
+| Not verifying subagent output before moving to next task | Carries regressions forward into later tasks | Validate output immediately before starting the next task |
+
+## Verification
+
+- After each subagent completes: review its changes, run typecheck + lint on modified files
+- After all tasks: run full test suite to catch integration issues
+- Check: no conflicting edits between subagent outputs
+
+## Integration
+
+**Required workflow skills:**
+
+- **planning-and-task-breakdown** - REQUIRED: Creates the plan that this skill executes
+- **code-review-and-quality** - REQUIRED: Review after each task (see Step 3)
+- **shipping-and-launch** - REQUIRED: Complete development after all tasks (see Step 7)
+
+**Subagents must use:**
+
+- **test-driven-development** - Subagents follow TDD for each task
+
+**Alternative workflow:**
+
+- **incremental-implementation** - Use for same-session slice-by-slice execution instead of parallel subagent dispatch
+
+See review format in the `code-review-and-quality` skill.
+```
+
+## See Also
+
+- **subagent-driven-development** — for parallel investigation (this skill)
+- **incremental-implementation** — for batch execution with checkpoints
+- **code-review-and-quality** — for review between subagent tasks
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll just do it myself, faster than delegating" | Serial work hits context limits. Parallel subagents finish multi-file tasks faster. |
+| "The subagent will figure out the details" | Subagents need explicit contracts. Vague prompts produce wrong implementations. |
+| "I don't need to review subagent output" | Subagents hallucinate and drift. Every output needs verification. |
+| "One subagent can handle the whole feature" | Large scope in one agent compounds errors. Split into independent tasks. |
+
+## Verification
+
+After completing subagent-driven implementation:
+
+- [ ] Each task had explicit acceptance criteria before dispatch
+- [ ] Subagent outputs were independently verified (diff reviewed, tests run)
+- [ ] No file conflicts between parallel subagents
+- [ ] Each subagent commit is atomic and reviewable
+- [ ] The full feature passes integration testing