@feniix/pi-specdocs

Structured spec documentation — PRDs, ADRs, and implementation plans with cross-referencing

Package details

← Back
extensionskillprompt

Install @feniix/pi-specdocs from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@feniix/pi-specdocs
Package
@feniix/pi-specdocs
Version
2.4.4
Published
Apr 23, 2026
Downloads
3,097/mo · 938/wk
Author
feniix
License
MIT
Types
extension, skill, prompt
Size
143.4 KB
Dependencies
6 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions/index.ts"
  ],
  "skills": [
    "./skills"
  ],
  "prompts": [
    "./prompts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@feniix/pi-specdocs

Structured spec documentation workflow for pi — PRDs, ADRs, and implementation plans with cross-referencing.

Features

  • PRD Skill (prd): Draft structured Product Requirements Documents with Gherkin acceptance criteria, design decisions, and concrete file breakdowns
  • ADR Skill (adr): Create Architecture Decision Records in MADR 4.0 format with PRD linkage
  • Plan-PRD Skill (plan-prd): Generate implementation plans from PRDs with ADR cross-references
  • Architect Prompt (/architect): End-to-end initiative planning — assess feasibility, decompose into workstreams, produce artifacts
  • Refine Prompt (/refine): Deep review of PRDs/ADRs for risks, bugs, ambiguities, errors, and inconsistencies
  • Session Hook: Automatically scans docs/ on session start and displays a summary of existing spec documents
  • Validation Command (specdocs-validate): Checks spec docs for typed frontmatter validity, required sections/tables, numbering, duplicate IDs, and plan filename issues
  • Formatting Command (specdocs-format <path>): Normalizes supported spec documents in-process without external tools while preserving common GFM constructs

Install

pi install npm:@feniix/pi-specdocs

Ephemeral (one-off) use:

pi -e npm:@feniix/pi-specdocs

Skills (auto-trigger)

prd

Triggers when you ask to write a PRD, scope a feature, write requirements, or break down a GitHub issue. Produces a 14-section PRD stored at docs/prd/PRD-NNN-slug.md and optionally posted to GitHub.

adr

Triggers when you ask to create an ADR, document a technical decision, or compare options. Uses the 4-point test to determine if a decision warrants a standalone ADR. Stored at docs/adr/ADR-NNNN-slug.md.

plan-prd

Triggers when you ask to create an implementation plan from a PRD. Generates architecture overview, component breakdown, phased implementation, and flags ADR candidates.

Prompt Templates (manual invocation)

/architect [description | issue-number | prd-path]

End-to-end initiative planning. Acts as a Product Architect — assesses feasibility, decomposes into workstreams, determines which artifacts are needed, and produces them in sequence.

/refine [path-to-document]

Deep review of a PRD or ADR. Validates against the codebase, researches external claims, and presents findings organized by category with severity levels.

Document Storage

Type Location Naming
PRDs docs/prd/ PRD-NNN-slug.md (3-digit)
ADRs docs/adr/ ADR-NNNN-slug.md (4-digit)
Plans docs/architecture/ plan-slug.md

Commands

These are pi slash commands, not shell executables on PATH. Invoke them inside pi as /specdocs-validate and /specdocs-format <path>.

  • specdocs-validate — validate spec documents in the workspace
  • specdocs-format <path> — format one or more PRD, ADR, or plan documents in place
    • accepts plain paths, @path/file.md references, multiple paths, and simple * globs such as @docs/adr/ADR-*.md
    • validates typed frontmatter, required headings, and required table shapes
    • plan docs also warn on missing recommended sections such as Risks and Mitigations and Open Questions
    • duplicate PRD/ADR numbers and invalid direct-child plan filenames are surfaced in workspace validation
    • normalizes frontmatter fences and section spacing
    • normalizes GFM table spacing/alignment
    • preserves thematic breaks, task lists, and other common GFM syntax

Tools

These tools are available to the LLM during a pi session and are the preferred execution path when the model should validate or format documents itself:

  • specdocs_validate — validate the current workspace's spec documents
  • specdocs_format — format one or more spec documents in place
    • accepts path, file_path, or paths
    • supports plain paths, @path/file.md, multiple files, and simple * globs
    • validates typed frontmatter, required headings, and required table shapes
    • plan docs also warn on missing recommended sections such as Risks and Mitigations and Open Questions
    • duplicate PRD/ADR numbers and invalid direct-child plan filenames are surfaced in workspace validation
    • normalizes frontmatter fences and section spacing
    • normalizes GFM table spacing/alignment
    • preserves thematic breaks, task lists, and other common GFM syntax

In short:

  • use specdocs_validate / specdocs_format for LLM tool execution
  • use /specdocs-validate / /specdocs-format ... for manual interactive invocation inside pi

Tool Integration

Skills prefer MCP tools when available, with fallback to built-in alternatives:

Purpose Preferred Fallback
Codebase exploration serena Read, Grep, Glob
External research exa, ref WebSearch, WebFetch
GitHub gh CLI gh CLI

Session Hook

On session start, the extension scans docs/prd/, docs/adr/, and docs/architecture/ and displays:

  • Count of existing PRDs, ADRs, and plans
  • Proposed ADRs needing review
  • Draft PRDs still in progress

Performance verification

A reproducible local benchmark is included for the PRD-004 validation targets.

Run it from packages/pi-specdocs/:

npm run perf:validation

Latest recorded local measurement in this repo:

  • single-file validation: ~7.41 ms
  • workspace validation (25 docs): ~19.14 ms

Requirements

  • pi v0.51.0 or later
  • gh CLI (for GitHub integration)

Uninstall

pi remove npm:@feniix/pi-specdocs

License

MIT