@nicknisi/pi-ideation

Transform brain dumps into structured implementation specs with confidence-gated workflows, codebase exploration, and automated review cycles.

A pi package ported from claude-plugins/ideation.

Installation

pi install npm:@nicknisi/pi-ideation

Recommended packages

These packages enhance the ideation workflow. The skills work without them but with reduced functionality. A warning is shown at session start for any missing packages.

| Package | Install | What it adds | |---------|---------|-------------| | pi-subagents | pi install npm:pi-subagents | Scout/reviewer agents, parallel execution, chains | | pi-askuserquestion | pi install git:github.com/ghoseb/pi-askuserquestion | Structured TUI for clarifying questions |

Without pi-subagents, execute-spec falls back to inline codebase exploration and skips the automated review cycle. Without pi-askuserquestion, the LLM asks questions as numbered plain-text options instead of an interactive TUI.

What's Included

Skills

| Skill | Command | Description | |-------|---------|-------------| | ideation | /skill:ideation | Transform messy ideas into structured contracts and implementation specs | | execute-spec | /skill:execute-spec | Execute a spec with scout → build → review cycles |

Agents (for pi-subagents)

| Agent | Description | |-------|-------------| | scout | Read-only codebase exploration. Scores implementation readiness across 5 dimensions. | | reviewer | Spec-aware code review. Compares git diff against the spec and produces structured findings. |

Agents are automatically installed to ~/.pi/agent/agents/ on first load.

Usage

Ideation (planning)

/skill:ideation

I have this idea for a feature... [brain dump here]

The ideation skill will:

1. Accept your messy input
2. Explore the codebase (if not greenfield)
3. Ask clarifying questions until confidence ≥ 95%
4. Generate a contract for approval
5. Break scope into phases
6. Generate implementation specs
7. Create an execution plan

Artifacts are written to ./docs/ideation/{project-name}/.

Execute Spec (implementation)

/skill:execute-spec docs/ideation/my-feature/spec-phase-1.md

The execute-spec skill will:

1. Run the scout agent to map the codebase
2. Build components incrementally with feedback loops
3. Run validation commands
4. Invoke the reviewer agent (up to 3 cycles)
5. Commit on review pass

For parallel execution of independent components:

/skill:execute-spec --parallel docs/ideation/my-feature/spec-phase-1.md

Using agents directly

With pi-subagents installed:

/run scout "analyze the auth module for phase 2 implementation"
/run reviewer "review changes against docs/ideation/auth/spec-phase-1.md"
/chain scout "explore codebase" -> worker "implement spec" -> reviewer "review against spec"

Bundled References

The ideation skill includes reference templates and examples:

• references/contract-template.md — Contract template
• references/prd-template.md — PRD template
• references/spec-template.md — Implementation spec template
• references/confidence-rubric.md — Confidence scoring criteria
• references/feedback-loop-guide.md — Feedback loop design guide
• references/workflow-example.md — End-to-end workflow walkthrough
• examples/contract-example.md — Example contract
• examples/prd-example.md — Example PRD
• examples/spec-example.md — Example spec

License

MIT