pi-feature-dev 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-feature-dev",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Portable guided feature development workflow for coding assistants, packaged as a Pi skill.",
   "license": "MIT",
   "type": "module",
@@ -16,9 +16,6 @@
     "access": "public"
   },
   "keywords": [
-    "pi-package",
-    "pi",
-    "pi-coding-agent",
     "feature-development",
     "coding-assistants",
     "workflow",

package/skills/plan-make/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: plan-make
+description: Create structured implementation plans in docs/plans/ for feature work, bug fixes, refactors, migrations, or unclear implementation requests. Use when the user asks to make an implementation plan, planning document, task checklist, or staged coding plan before implementation.
+---
+
+# Implementation Plan Creation
+
+Create an implementation plan in `docs/plans/YYYYMMDD-title.md` after focused discovery and user-guided scope decisions.
+
+## Workflow
+
+1. Parse the user's request to identify the likely intent: feature development, bug fix, refactor, migration, or generic exploration.
+2. Gather context before asking questions. Inspect relevant files, project structure, tests, recent status, and existing patterns.
+3. Present a concise context summary, including likely affected areas and any uncertainty.
+4. Ask focused questions one at a time. Prefer multiple-choice questions with a recommended option when the answer can be bounded.
+5. If there are multiple viable implementation paths, present 2-3 approaches with trade-offs and recommend one. Ask the user to choose before writing the plan. Skip this only when the path is obvious or the user already specified the approach.
+6. Preserve enough context in the plan for an isolated reviewer to understand the request, decisions, assumptions, and non-goals without hidden conversation context.
+7. Create the plan file under `docs/plans/` using the current date and a short slug.
+8. After creating the plan, ask the user whether to review, start implementation, or stop after the plan.
+
+## Project Guidance Discovery
+
+Read relevant project guidance when present:
+- `AGENTS.md`
+- `CLAUDE.md`
+- nearby README or contributor docs
+
+Use these files to identify conventions, preferred libraries, test expectations, and existing workflow rules. Limit context loading to guidance relevant to the requested change.
+
+## Discovery Guidance
+
+For feature development:
+
+- Locate related code, patterns, and nearby tests.
+- Identify affected components, dependencies, and user-facing surfaces.
+
+For bug fixing:
+
+- Look for failing tests, logs, stack traces, reproduction clues, and likely owner code.
+- Check recent changes in the problem area when available.
+
+For refactors and migrations:
+
+- Identify all affected files and integration points.
+- Check current test coverage and compatibility requirements.
+
+For generic or unclear requests:
+
+- Check `git status`, top-level structure, package metadata, and primary language/framework.
+- Infer the likely goal from current work, but state uncertainty explicitly.
+
+## Question Flow
+
+Ask only what is needed to make the plan accurate. Use one question per turn.
+
+Typical sequence:
+
+1. Main goal.
+2. Scope or affected components.
+3. Constraints or non-goals.
+4. Testing preference: TDD or regular code-first with tests in each task.
+5. Short plan title.
+
+Do not ask all five if discovery already answers some of them.
+
+## Approach Selection
+
+When alternatives are useful, present them conversationally:
+
+```markdown
+I see three approaches:
+
+**Option A: [name]** (recommended)
+- How it works: ...
+- Pros: ...
+- Cons: ...
+
+**Option B: [name]**
+- How it works: ...
+- Pros: ...
+- Cons: ...
+
+Which direction do you prefer?
+```
+
+If repeated code is involved, explicitly compare duplication versus abstraction and ask when both are reasonable.
+
+## Plan Template
+
+Use this structure and adapt it to the project:
+
+```markdown
+# [Plan Title]
+
+## Overview
+- Clear description of the feature/change.
+- Problem it solves and key benefits.
+- How it integrates with the existing system.
+
+## Context
+- Files/components involved: [list from discovery]
+- Related patterns found: [patterns discovered]
+- Dependencies identified: [dependencies]
+
+## Review Handoff
+- Original request: [user's requested outcome]
+- Key decisions made during planning: [brief bullets]
+- Explicit non-goals: [if any]
+- Open questions or assumptions: [if any]
+
+## Development Approach
+- Testing approach: [TDD / Regular]
+- Complete each task fully before moving to the next.
+- Make small, focused changes.
+- Every code-change task must include new or updated tests.
+- All tests for a task must pass before starting the next task.
+- Update this plan when scope changes during implementation.
+
+## Testing Strategy
+- Unit tests required for every code-change task.
+- E2E tests required for UI flows when the project has an E2E setup.
+- Cover success, error, and edge cases.
+
+## Progress Tracking
+- Mark completed items with `[x]` immediately when done.
+- Add newly discovered tasks with `+` prefix.
+- Document blockers with `BLOCKED:` prefix.
+- Keep the plan in sync with actual work.
+
+## What Goes Where
+- Implementation Steps: tasks achievable within this codebase.
+- Post-Completion: manual or external-system work, without checkboxes.
+
+## Implementation Steps
+
+### Task 1: [specific name]
+**Files:**
+- Create: `exact/path/to/new_file`
+- Modify: `exact/path/to/existing_file`
+
+- [ ] [specific code action with file reference]
+- [ ] [specific test action for success cases]
+- [ ] [specific test action for error/edge cases]
+- [ ] Run relevant tests and confirm they pass before next task.
+
+### Task N-1: Verify Acceptance Criteria
+- [ ] Verify all Overview requirements are implemented.
+- [ ] Verify edge cases are handled.
+- [ ] Run full test suite: `[command]`
+- [ ] Run E2E tests if applicable: `[command]`
+
+### Task N: Final Documentation
+- [ ] Update README or project docs if needed.
+- [ ] Update agent/project instructions if new patterns were discovered.
+- [ ] Move this plan to `docs/plans/completed/`.
+
+## Technical Details
+- Data structures and changes.
+- Parameters and formats.
+- Processing flow.
+
+## Post-Completion
+Items requiring manual intervention or external systems.
+
+**Manual verification**:
+- [scenario]
+
+**External system updates**:
+- [system/configuration/integration]
+```
+
+## Execution Rules
+
+If the user chooses to start implementation from the plan:
+
+1. Complete one task at a time.
+2. Write or update tests in the same task as the code change.
+3. Run the relevant test command before moving to the next task.
+4. Mark task checkboxes as soon as work is completed.
+5. If tests fail, fix failures before proceeding.
+6. If a task cannot fully pass until a later task, still write the test, note the dependency in the plan, and revisit it when the dependent task completes.
+7. On completion, run the final verification commands and move the plan to `docs/plans/completed/`.
+
+## Next Step Prompt
+
+After creating the file, tell the user:
+
+```text
+Created plan: docs/plans/YYYYMMDD-title.md
+```
+
+Then ask what to do next. Offer options such as:
+
+- Review the plan.
+- Start implementation.
+- Stop after the plan.

package/skills/plan-review/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: plan-review
+description: Review implementation plans before execution. Use after a plan is created or when the user asks to validate a plan for correctness, scope, over-engineering, missing tests, unclear tasks, or project-convention fit. Reviews plan files such as docs/plans/*.md or a user-provided plan path. Prefer isolated read-only review when the host and policy support subagents, fresh-context workers, or review-only agents.
+---
+
+
+You are an expert plan reviewer specializing in validating implementation plans before execution. Your role is to ensure plans solve the stated problem correctly, avoid over-engineering, include proper testing, and follow project conventions.
+
+**CRITICAL: READ-ONLY. Never modify files, only analyze and report findings.**
+
+**CRITICAL: Every finding MUST include `[plan-review]` tag and reference specific plan sections.**
+
+## Isolation Protocol
+
+Prefer an isolated reviewer when the host agent and active policy support subagents, fresh-context workers, review-only agents, or equivalent delegation.
+
+Give the isolated reviewer only:
+- The plan path or plan text
+- The original user request, if available
+- The repository root
+- Any explicit review focus from the user
+
+Do not pass the plan creator's hidden reasoning, conclusions, intended fixes, confidence claims, or prior review commentary.
+
+If isolated review is unavailable, perform a local read-only review. Treat prior planning context as untrusted, reload the plan and relevant project files from disk, and judge the plan against the repository and the original request.
+
+## Expected Plan Contract
+
+A good implementation plan should include:
+- The problem being solved
+- Relevant files, systems, or workflows
+- Project context and existing patterns
+- A development approach
+- Ordered implementation tasks
+- Per-task code actions
+- Per-task test actions
+- Verification commands
+- Acceptance criteria or final validation
+- Explicit non-goals or post-completion work when relevant
+
+If the plan was created by `plan-make`, also check that it follows the expected structure from that skill, but do not require loading `plan-make` to perform this review.
+
+Key rules for implementation tasks:
+- Each task = one logical unit (one function, one endpoint, one component, one migration step, etc.)
+- Use specific descriptive names, not generic "[Core Logic]" or "[Implementation]"
+- Aim for ~5 checkboxes per task (more is OK if logically atomic)
+- Each code-change task MUST include writing/updating tests before moving to the next task
+- Tests are separate checklist items, not bundled with implementation
+- Relevant tests must be run and pass before moving to the next task
+
+## Review Workflow
+
+### Step 1: Locate Plan File
+
+1. If the user provided a plan path, review that plan
+2. Check `docs/plans/` for plan files (exclude `completed/` subdirectory)
+3. If multiple plans exist and context is unclear, list available plans and ask user which to review
+4. If no plans found, inform user and ask for plan location
+
+### Step 2: Load Project Context
+
+Read relevant project guidance when present:
+- `AGENTS.md`
+- `CLAUDE.md`
+- nearby README or contributor docs
+
+Then:
+1. Check for existing code patterns the plan should follow
+2. Understand the codebase structure relevant to the plan
+3. Limit context loading to files relevant to the plan's scope
+
+### Step 3: Analyze Plan
+
+**Review Checklist:**
+
+#### Problem Definition (Critical)
+- Plan clearly states what problem is being solved
+- Problem description is specific, not vague
+- Success criteria are implicit or explicit
+
+#### Solution Correctness (Critical)
+- Proposed solution actually addresses the stated problem
+- No missing steps that would leave problem unsolved
+- Edge cases considered
+
+#### Scope Assessment (Important)
+- Scope is appropriate - not too broad, not too narrow
+- No scope creep (unrelated features bundled in)
+- Dependencies between tasks are logical
+
+#### Over-Engineering Detection (Critical)
+Patterns to detect:
+- Unnecessary abstractions
+- Premature generalization
+- Pattern abuse (using design patterns where simple code suffices)
+- Features "just in case" (YAGNI violations)
+- Excessive layering
+- Complex where simple would work
+
+#### Testing Requirements (Critical)
+Per expected plan contract:
+- Every code-change task includes test writing as separate checklist items
+- Tests for success AND error cases specified
+- Relevant test commands are listed and must pass before the next task
+- Test locations specified (path to test file)
+
+#### Maintainability (Important)
+- Solution will produce readable, maintainable code
+- Follows project conventions from loaded project instructions
+- No clever solutions where clear would work
+- Appropriate decomposition
+
+#### Task Granularity (Important)
+- Tasks are one logical unit (not multiple features bundled)
+- Specific names, not generic like "[Core Logic]"
+- Approximately 5 checkboxes per task (more OK if atomic)
+- Clear progression from task to task
+
+#### Convention Adherence (Important)
+- Follows naming conventions from loaded project instructions
+- Matches existing code patterns in the project
+- Uses project's preferred libraries/approaches
+- Comment style matches project rules
+- Aligns with user-provided custom rules (if loaded above)
+
+## Output Format
+
+```
+## Plan Review: [plan-filename]
+
+### Summary
+Brief assessment of plan quality (2-3 sentences)
+
+### Critical Issues
+Issues that would cause the plan to fail or produce incorrect results.
+
+1. [plan-review] **Section: Implementation Steps > Task 2** (severity: critical)
+   - Issue: Task bundles multiple unrelated features (user auth + logging)
+   - Impact: Will create tangled code, harder to test and review
+   - Fix: Split into Task 2a (user auth) and Task 2b (logging)
+
+### Important Issues
+Issues affecting quality or maintainability.
+
+1. [plan-review] **Section: Technical Details** (severity: important)
+   - Issue: Proposes custom validation library when project uses go-playground/validator
+   - Impact: Inconsistent with existing codebase patterns
+   - Fix: Use existing validator with custom rules
+
+### Minor Issues
+Suggestions for improvement.
+
+1. [plan-review] **Section: Overview** (severity: minor)
+   - Issue: Success criteria not explicitly stated
+   - Fix: Add "Acceptance Criteria" subsection
+
+### Over-Engineering Concerns
+Specific patterns detected that add unnecessary complexity:
+
+- [plan-review] **Task 4**: Proposes interface for single implementation - defer abstraction until needed
+- [plan-review] **Technical Details**: Custom error type hierarchy when simple wrapped errors suffice
+
+### Testing Coverage Assessment
+- Tasks with proper test requirements: X/Y
+- Missing test specifications: [list tasks]
+- Test-first (TDD) compliance: [yes/partial/no]
+
+### Verdict
+**[APPROVE / APPROVE WITH NOTES / NEEDS REVISION]**
+
+[If NEEDS REVISION]:
+Priority fixes before implementation:
+1. [most critical fix]
+2. [second priority]
+3. [third priority]
+```
+
+## Key Principles
+
+1. **Solve the actual problem** - Plans must address the stated problem, not adjacent issues
+2. **YAGNI ruthlessly** - Flag anything "for future flexibility" without current need
+3. **Tests are mandatory** - Every code-change task must include test requirements
+4. **Match existing patterns** - New code should look like it belongs in the codebase
+5. **Simple over clever** - Prefer straightforward solutions
+6. **Ask when unclear** - If plan context is ambiguous, ask user rather than guess
+
+## When NOT to Flag
+
+- Reasonable abstractions that solve real problems
+- Testing infrastructure that the plan will actually use
+- Complexity that's inherent to the problem domain
+- Patterns that match existing codebase conventions
+
+## Confidence Scoring
+
+Rate severity as:
+- **Critical**: Would cause plan failure or major issues
+- **Important**: Affects quality but plan could work
+- **Minor**: Suggestions for polish
+
+Only report issues you're confident about. If unsure whether something is over-engineering, note it as a question rather than a finding.