Skip to content

PLAN.md

Latest commit

 

History

History
207 lines (176 loc) · 11.1 KB

PLAN.md

File metadata and controls

207 lines (176 loc) · 11.1 KB

pi-spec-kit Build Plan

Created: 2026-02-08 Design doc: ~/Documents/obsidian/projects/pi-speckit/design.md Status: In progress

Phase 1: Repo Scaffolding

  • Create package.json with pi.skills manifest and pi-package keyword
    • Set initial version to 0.1.0
  • Create README.md with:
    • Overview / what this is
    • Installation instructions (global and per-project)
    • Full skill listing with descriptions
    • End-to-end workflow walkthrough (init → specify → clarify → plan → tasks → implement)
    • Template customization docs
    • Version check instructions
  • Create CHANGELOG.md (will be auto-maintained by release-please)
  • Create directory structure:
    • skills/ (empty subdirs for each skill)
    • templates/
    • scripts/
  • Initialize git repo, create .gitignore
  • Set up versioning and release automation:
    • Adopt conventional commits (feat:, fix:, chore:, docs:)
    • Add .github/workflows/release-please.yml GitHub Action
    • Configure release-please for node package type (bumps package.json version)
    • Action creates a release PR on push to main; merging it tags + creates GitHub Release
  • Verify pi recognizes the package structure (pi install ./ from a test project)

Phase 2: Port Templates

Source: /Users/michelleweirathmueller/Documents/TOOLS/spec-kit/templates/

  • spec-template.md — copy as-is
  • plan-template.md — copy as-is
  • tasks-template.md — copy as-is
  • checklist-template.md — copy as-is
  • roadmap-template.md — copy as-is (fork addition)
  • tests-template.md — copy as-is (fork addition)
  • constitution-template.md — extract from agent-file-template.md or create new
    • Note: fork's agent-file-template.md is a Claude-specific agent file, not a constitution template. Need to decide: does speckit-constitution need a template, or does it generate from scratch? Check pf-animats skill for current behavior.
  • Drop: agent-file-template.md (pi uses project-context skills instead)
  • Drop: vscode-settings.json (not relevant)
  • Drop: commands/ directory (replaced by skills)
  • Review each ported template for agent-neutral language (remove Claude Code-specific references, make harness-agnostic)

Phase 3: Port Scripts

Source: /Users/michelleweirathmueller/Documents/TOOLS/spec-kit/scripts/bash/

  • create-new-feature.sh — port, review for path assumptions
    • This creates specs/<feature>/ directory structure. Skills will call it.
  • setup-plan.sh — port, review for path assumptions
    • This sets up specs/<feature>/plan/ structure. Used by speckit-plan.
  • Drop: check-prerequisites.sh (checks for Claude Code CLI — not relevant)
  • Drop: common.sh (shared functions for the dropped scripts — check if create-new-feature.sh or setup-plan.sh depend on it first)
  • Drop: update-agent-context.sh (updates CLAUDE.md — pi loads context on-demand)
  • Drop: all PowerShell scripts
  • Update script paths to work relative to the skill directory (pi resolves relative to SKILL.md parent)
  • Harden all kept scripts:
    • Add set -euo pipefail to each script
    • Run shellcheck and fix warnings
    • Ensure idempotency (safe to run twice without breaking anything)
    • Add clear error messages for failure cases

Phase 4: Port Core Skills (8 existing)

Source: pf-animats skills at /Users/michelleweirathmueller/Documents/ANIMATS/pf-animats/.pi/skills/speckit-*/ Cross-reference: fork commands at /Users/michelleweirathmueller/Documents/TOOLS/spec-kit/templates/commands/

Before porting, define the skill consistency pattern:

  • Establish standard SKILL.md structure all skills will follow:
    • Frontmatter format (name, description — required by Agent Skills spec)
    • Section ordering (e.g., Overview → Inputs → Workflow → Template Reference → Next Steps)
    • How to reference templates (consistent path pattern, fallback instructions)
    • How to reference scripts (consistent path pattern)
    • "Next step" suggestions (e.g., "Next: run /skill:speckit-plan") — consistent phrasing
  • Write a brief style guide or example that we apply to each skill

For each skill: copy from pf-animats, diff against fork command, reconcile any differences, apply consistency pattern, update template/script paths to use package-relative references, review for agent-neutral language.

  • speckit-specify — create/update feature spec
    • Copy SKILL.md from pf-animats
    • Diff against fork's commands/specify.md for any missed content
    • Update template references to point to ../../templates/spec-template.md
    • Update script references to point to ../../scripts/create-new-feature.sh
    • Review for agent-neutral language
  • speckit-clarify — ask clarification questions on a spec
    • Copy SKILL.md from pf-animats
    • Diff against fork's commands/clarify.md
    • Update any template/script paths
    • Review for agent-neutral language
  • speckit-plan — generate implementation plan from spec
    • Copy SKILL.md from pf-animats
    • Diff against fork's commands/plan.md
    • Update template references to ../../templates/plan-template.md
    • Update script references to ../../scripts/setup-plan.sh
    • Review for agent-neutral language
  • speckit-tasks — generate tasks from plan
    • Copy SKILL.md from pf-animats
    • Diff against fork's commands/tasks.md
    • Update template references to ../../templates/tasks-template.md
    • Review for agent-neutral language
  • speckit-implement — execute tasks with review workflow
    • Copy SKILL.md from pf-animats
    • Diff against fork's commands/implement.md
    • Verify review-pause behavior and [Q:]/[C:]/[TODO:] markers are preserved
    • No template references expected, but verify
    • Review for agent-neutral language
  • speckit-analyze — cross-artifact consistency check
    • Copy SKILL.md from pf-animats
    • Diff against fork's commands/analyze.md
    • Review for agent-neutral language
  • speckit-checklist — generate requirements quality checklist
    • Copy SKILL.md from pf-animats
    • Diff against fork's commands/checklist.md
    • Update template references to ../../templates/checklist-template.md
    • Review for agent-neutral language
  • speckit-constitution — create/update project constitution
    • Copy SKILL.md from pf-animats
    • Diff against fork's commands/constitution.md
    • Decide on constitution template (see Phase 2 note)
    • Review for agent-neutral language

Phase 5: Add Missing Skills (2 new ports + 1 brand new)

These exist in the fork but weren't ported to pf-animats yet.

  • speckit-roadmap — create/update project roadmap
    • Port from fork's commands/roadmap.md
    • Convert to SKILL.md format (frontmatter + instructions)
    • Reference ../../templates/roadmap-template.md
  • speckit-tests — generate test plans
    • Port from fork's commands/tests.md
    • Convert to SKILL.md format
    • Reference ../../templates/tests-template.md
  • speckit-init — scaffold .specify/ in a project (brand new)
    • Write SKILL.md that replaces the specify init Python CLI
    • Behavior:
      • Create .specify/memory/ directory
      • Create .specify/templates/ and copy templates from package (with fallback logic)
      • Create .specify/roadmap.md from template
      • Optionally scaffold constitution interactively
      • Create specs/ directory
    • Handle "already initialized" gracefully (don't overwrite existing files)
    • Skip: AI instruction file creation (that's not speckit's job in pi)
    • Skip: .pi/settings.json creation (user handles this via pi install)

Phase 6: Template Fallback Logic

Implement the "project-first, package-fallback" pattern described in design doc.

  • Document the convention: skills check .specify/templates/<name> first, fall back to package ../../templates/<name>
  • Add this logic to each skill that references a template (or create a shared pattern/instruction in the skill text)
  • speckit-init copies package templates into .specify/templates/ on first run
  • speckit-init does NOT overwrite existing templates on re-run
  • Consider: add a --update-templates flag or separate instruction for updating stale templates

Phase 7: Test Locally

  • Install the package locally in a fresh test project: pi install /Users/michelleweirathmueller/Documents/TOOLS/pi-spec-kit
  • Verify all 11 skills appear in pi's skill list
  • Run /skill:speckit-init — confirm scaffolding works
  • Run /skill:speckit-specify with a test feature — confirm spec generation
  • Run /skill:speckit-clarify on the test spec
  • Run /skill:speckit-plan — confirm plan artifacts generated
  • Run /skill:speckit-tasks — confirm tasks generated
  • Run /skill:speckit-implement — confirm review workflow works
  • Run /skill:speckit-analyze — confirm cross-artifact analysis
  • Run /skill:speckit-checklist — confirm checklist generation
  • Run /skill:speckit-constitution — confirm constitution workflow
  • Run /skill:speckit-roadmap — confirm roadmap management
  • Run /skill:speckit-tests — confirm test plan generation
  • Verify template fallback: modify a project template, confirm skill uses the project version

Phase 8: Publish

  • Push to GitHub as Waveform-Analytics/pi-spec-kit
  • Verify release-please Action runs and opens first release PR
  • Merge release PR to create v0.1.0 tag and GitHub Release
  • Test install via git: pi install git:github.com/Waveform-Analytics/pi-spec-kit
  • Test pinned install: pi install git:github.com/Waveform-Analytics/pi-spec-kit@v0.1.0
  • Update design doc status in obsidian vault

Decisions to Make Along the Way

  • Constitution template: Does one exist, or does the skill generate from scratch? (Phase 2/4)
  • common.sh dependency: Do create-new-feature.sh or setup-plan.sh source common.sh? If so, port the needed functions. (Phase 3)
  • Template update strategy: How do users update stale project templates when the package updates? (Phase 6)
  • taskstoissues: Deferred — the design doc says to build this later with gh CLI, not as part of initial release.

Source Material Quick Reference

What Where
Fork (templates, commands, scripts) /Users/michelleweirathmueller/Documents/TOOLS/spec-kit/
pf-animats skills (already converted) /Users/michelleweirathmueller/Documents/ANIMATS/pf-animats/.pi/skills/speckit-*/
Migration notes /Users/michelleweirathmueller/Documents/ANIMATS/pf-animats/.pi/scratch/claude-to-pi-migration.md
Design doc ~/Documents/obsidian/projects/pi-speckit/design.md
Pi package docs ~/.nvm/versions/node/v22.13.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/packages.md
Pi skills docs ~/.nvm/versions/node/v22.13.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/skills.md