@ifi/pi-spec

Native spec-driven workflow for pi, inspired by github/spec-kit.

@ifi/pi-spec is a pi extension package, not a shell wrapper and not a general-purpose JavaScript library. Its job is to bring the core spec-kit workflow into pi as a native TypeScript experience:

• one /spec command instead of a pile of separate commands and shell entrypoints
• deterministic local scaffolding under .specify/
• deterministic feature artifacts under specs/###-feature-name/
• native git/repo detection, branch naming, and feature numbering in TypeScript
• prompt handoff back into pi via pi.sendUserMessage(...)
• project-owned templates that can be customized locally after initialization

The package deliberately keeps the mental model of spec-kit, but replaces its shell orchestration with normal pi tools and normal pi conversations.

Install

pi install npm:@ifi/pi-spec

Or install the full oh-pi bundle:

npx @ifi/oh-pi

---

Purpose

The purpose of this package is to make spec-first development feel native inside pi.

In practice that means:

1. Requirements come first
   • You write or refine a spec before planning and implementation.
2. The workflow is explicit
   • /spec:specify, /spec:plan, /spec:tasks, /spec:implement are separate steps with clear outputs.
3. The repository owns the workflow state
   • Important artifacts live in normal files in your repo, not in hidden runtime state.
4. Pi stays in control of the work
   • Instead of calling external shell scripts, pi reads templates, edits files, runs tests, and explains what it did.
5. Teams can customize locally
   • The package seeds .specify/templates/, then gets out of the way.

Goals

The design goals for @ifi/pi-spec are:

• Native pi UX — use pi's existing tools, prompting, and slash-command system
• Spec-kit compatibility of concepts — keep the same major phases and familiar artifact layout
• Type-safe implementation — perform repo detection, path calculation, and branch generation in TypeScript
• Idempotent scaffolding — create missing files without constantly overwriting local customizations
• Low surprise — make state visible through files and /spec:status
• Good defaults, flexible templates — ship usable templates while letting projects evolve them

Non-goals

This package intentionally does not try to be:

• a 1:1 shell-script port of upstream spec-kit internals
• a hidden autonomous pipeline that silently runs every step for you
• a generic npm library with a stable programmatic JS API
• a hook runner that auto-executes .specify/extensions.yml scripts behind your back

The stable API surface is the slash command and the on-disk workflow structure.

---

The API I chose

Public API surface

The package has one primary public entrypoint:

/spec [subcommand] [freeform input]

Supported subcommands:

Canonical /spec subcommands exposed by the extension. Keep README command lists and exported type metadata in sync with this source of truth: status, help, init, constitution, specify, clarify, checklist, plan, tasks, analyze, implement, list, and next.

That is the intentional public API.

There is not a separate public JS/TS library API right now. Internal modules like workspace.ts, scaffold.ts, or prompts.ts are implementation details for contributors, not a versioned integration surface for consumers.

Core workflow steps:

Workflow steps that hand work back into pi for feature execution. These ordered steps are constitution, specify, clarify, checklist, plan, tasks, analyze, and implement. Keep contributor-facing docs aligned with the same sequence.

Why one /spec command is the right API

I chose one command with subcommands instead of many top-level commands like /specify, /clarify, /plan, /tasks, etc. for a few reasons:

1. It matches the workflow mental model

   • All of these actions are part of one lifecycle.
   • Grouping them under /spec makes that lifecycle obvious.

2. It avoids namespace clutter in pi

   • A spec workflow can easily consume half a dozen top-level slash commands.
   • /spec ... keeps the command surface organized.

3. It is easier to discover

   • /spec:help, /spec:status, and /spec:next make the system self-explanatory.
   • Users only need to remember one root command.

4. It preserves upstream familiarity without copying the shell UX

   • The step names still map cleanly to spec-kit concepts.
   • But the runtime behavior is pi-native instead of script-native.

5. It centralizes context resolution

   • Repo detection, active-feature resolution, scaffold creation, and prompt generation all happen in one place.
   • That reduces edge cases and keeps behavior consistent.

Why the API is file-centric

The second part of the API is the filesystem contract:

• .specify/ for reusable workflow state and templates
• specs/###-feature-name/ for per-feature artifacts

I think this is the correct design because it keeps the workflow:

• reviewable in git
• easy to inspect manually
• easy to customize
• resilient across agent restarts
• tool-agnostic at the file layer

In other words, the source of truth is not some in-memory session object; it is the repo itself.

---

Exact command behavior

Below is the practical contract for each subcommand.

Command	Purpose	Model handoff	Filesystem side effects
/spec or /spec:status	Show current workflow state	No	None
/spec:help	Show available commands and guidance	No	None
/spec:init	Create the base workflow scaffold	No	Creates missing .specify/ files
/spec:constitution [principles]	Create or revise the project constitution	Yes	Ensures base scaffold exists
/spec:specify <feature description>	Create the next numbered feature workspace	Yes	Ensures scaffold, creates specs/###-.../, may create/switch git branch
/spec:clarify [focus]	Ask and resolve high-impact ambiguities in the active spec	Yes	Ensures scaffold exists
/spec:checklist [domain]	Generate or refine requirement-quality checklists	Yes	Ensures scaffold exists
/spec:plan [technical context]	Build the implementation plan and design artifacts	Yes	Ensures scaffold, creates plan.md if missing
/spec:tasks [context]	Generate an executable tasks.md	Yes	Ensures scaffold exists
/spec:analyze [focus]	Run a read-only consistency review	Yes	Ensures scaffold exists
/spec:implement [focus]	Execute tasks and update completion state	Yes	Ensures scaffold exists; prompts if checklists are incomplete
/spec:list	List known feature directories	No	None
/spec:next	Show the next recommended step	No	None

Input rules

The command accepts freeform text after the subcommand.

Examples:

/spec:constitution Security-first, testable, low-complexity defaults
/spec:specify Add usage-based billing alerts for workspace admins
/spec:plan Use TypeScript, Vitest, and direct pi tool access
/spec:analyze Focus on contradictions between spec.md and tasks.md
/spec:implement Start with the MVP story and update tasks as you go

Notes:

• /spec:specify effectively requires a real feature description.
• Other workflow steps accept freeform guidance and can also run with minimal or no extra guidance.
• When pi has UI input capabilities available, the extension can prompt for missing input instead of failing immediately.

Active feature resolution

For steps that operate on a feature (clarify, checklist, plan, tasks, analyze, implement), the extension resolves the active feature using this order:

1. current branch name if it matches a numbered feature directory
2. a single known feature directory, if there is only one
3. a UI selection prompt, if multiple features exist and the UI supports selection
4. otherwise the latest numbered feature directory

This keeps the common path simple while still working in multi-feature repos.

---

Files and directories created by the package

Base workflow scaffold

/spec:init creates the base workflow scaffold if it is missing.

.specify/
├── README.md
├── extensions.yml
├── memory/
│   ├── constitution.md
│   └── pi-agent.md
└── templates/
    ├── agent-file-template.md
    ├── checklist-template.md
    ├── constitution-template.md
    ├── plan-template.md
    ├── spec-template.md
    ├── tasks-template.md
    └── commands/
        ├── analyze.md
        ├── checklist.md
        ├── clarify.md
        ├── constitution.md
        ├── implement.md
        ├── plan.md
        ├── specify.md
        └── tasks.md

What these are for:

• .specify/README.md — local explanation of the workflow as installed in this repo
• .specify/extensions.yml — compatibility/config surface; pi inspects it manually when relevant rather than auto-running hooks
• .specify/memory/constitution.md — canonical governance/principles file
• .specify/memory/pi-agent.md — pi-native replacement for agent-context update scripts
• .specify/templates/ — local, editable workflow templates copied from the packaged defaults

Per-feature workspace

/spec:specify <description> creates a numbered feature workspace:

specs/
└── 001-my-feature/
    ├── spec.md
    ├── checklists/
    ├── plan.md
    ├── research.md
    ├── data-model.md
    ├── quickstart.md
    ├── contracts/
    └── tasks.md

Not every file exists immediately.

Current behavior:

• spec.md is scaffolded during /spec:specify
• plan.md is scaffolded during /spec:plan if it is missing
• other files are referenced by the workflow and created as the step needs them

Idempotency rules

Scaffolding is intentionally conservative:

• missing files are created
• existing files are left alone
• bundled templates are copied into the repo once, then become the repo's copies to edit

That is important because the package should seed a workflow, not keep fighting your local customization.

---

How to use it in practice

1) Initialize the workflow

/spec:init

Use this when introducing the workflow to a repo for the first time.

What happens:

• .specify/ is created if missing
• default templates are copied in
• constitution and pi-agent memory files are created if missing
• a report is rendered in pi explaining what was created

2) Define the project's constitution

/spec:constitution Security-first, testable, backwards-compatible changes by default

Use this to establish the rules the workflow should follow.

Typical outcomes:

• the constitution file is created or updated in .specify/memory/constitution.md
• related templates may be aligned with those rules
• future workflow steps can refer back to the same governance file

3) Create a feature spec

/spec:specify Add SSO login for enterprise tenants

What happens:

• the next feature number is computed
• a branch name is generated from the description
• specs/###-feature-name/ is created
• spec.md is scaffolded
• if git is available and you are not already on that feature branch, the extension creates and switches to it
• pi receives a prompt instructing it to follow the local specify template using the prepared paths

This is the key step that turns a vague idea into a concrete feature workspace.

4) Clarify open questions

/spec:clarify

or

/spec:clarify Focus on tenant boundaries, auth edge cases, and failure states

This step is meant to remove the highest-impact ambiguities before planning.

5) Generate a requirement-quality checklist

/spec:checklist Authentication quality gates

This is not supposed to generate implementation TODOs. It is meant to verify that the spec is precise, complete, and testable.

6) Build the implementation plan

/spec:plan Use TypeScript, Vitest, and existing auth services; avoid new infrastructure

What happens:

• plan.md is created if missing
• pi is instructed to use the local plan workflow template
• pi-agent.md is treated as the pi-native context artifact instead of shell-generated agent files

7) Generate tasks

/spec:tasks

or

/spec:tasks Prioritize the MVP path and keep tasks grouped by user story

This step should produce a tasks.md with a strict checkbox-oriented execution plan.

8) Analyze for contradictions

/spec:analyze

This step is intentionally read-only. It is there to catch inconsistencies between the spec, plan, checklists, and tasks before coding begins.

9) Implement

/spec:implement

or

/spec:implement Start with story 1, update tasks.md as each item completes

Behavior worth knowing:

• checklist files are summarized before implementation
• if incomplete checklist items exist and the UI supports confirmation, pi asks whether you want to continue
• the implementation prompt reminds pi to mark completed tasks as [x]

10) Inspect progress any time

/spec:status
/spec:next
/spec:list

Use these when you want visibility rather than action:

• /spec:status shows artifact presence, checklist summaries, current branch, and known features
• /spec:next recommends the next workflow command
• /spec:list lists all numbered feature directories in specs/

---

Example end-to-end session

/spec:init
/spec:constitution Security-first, testable, low-complexity defaults
/spec:specify Build a native spec workflow package for pi
/spec:clarify
/spec:checklist Requirements quality for the initial MVP
/spec:plan Use TypeScript, Vitest, and direct pi tool access
/spec:tasks Group work by independently testable user stories
/spec:analyze
/spec:implement

That sequence is the intended happy path.

---

Native behavior vs upstream spec-kit

This package is inspired by upstream spec-kit, but the runtime model is different on purpose.

What is preserved

• the phase names and overall lifecycle
• the numbered feature directory convention
• the use of templates to guide each phase
• the idea of constitution/spec/plan/tasks/checklist artifacts

What changed

• shell scripts are replaced with TypeScript helpers
• repo/branch/path preparation happens inside the extension
• workflow execution is handed back to pi as a normal prompt-driven task
• .specify/memory/pi-agent.md replaces agent-update shell behavior
• .specify/extensions.yml is preserved as a file, but not auto-executed as hooks

Why this is the correct adaptation for pi

Because pi already has:

• tools for file IO
• tools for running validation commands
• a conversation model for asking clarifying questions
• slash commands for entering workflows

Using shell wrappers would add indirection without adding capability. Native TypeScript makes the workflow:

• easier to test
• easier to reason about
• more portable across environments
• less dependent on shell behavior differences
• more aligned with how pi already works

---

Internal implementation overview

These modules are useful for contributors, but they are not the promised external API.

• extension/index.ts — command registration, dispatch, prompting, and model handoff
• extension/workspace.ts — repo detection, feature numbering, branch slugging, and path building
• extension/scaffold.ts — idempotent scaffold/template creation
• extension/prompts.ts — native workflow prompt builder and step-specific notes
• extension/status.ts — status reporting and checklist summarization
• extension/git.ts — minimal git adapter used by the workflow
• extension/assets/templates/ — vendored workflow and file templates adapted from spec-kit

I split the implementation this way because the workflow naturally has four concerns:

1. command API and UX
2. filesystem/workspace logic
3. prompt-generation logic
4. status/reporting logic

Keeping those concerns separate made the package easier to test thoroughly.

---

Customization

After initialization, you can customize the workflow by editing files in your repo:

• .specify/memory/constitution.md
• .specify/memory/pi-agent.md
• .specify/templates/*.md
• .specify/templates/commands/*.md

This is another core design choice: the workflow should become your repo's workflow, not remain locked inside the npm package.

---

Summary

If I had to describe the package in one sentence:

@ifi/pi-spec is a native pi implementation of a spec-first workflow whose public API is one /spec command plus a deterministic .specify/ and specs/###-feature-name/ file layout.

I think that is the correct API because it is:

• small enough to remember
• explicit enough to inspect
• compatible enough to feel familiar to spec-kit users
• native enough to feel right inside pi
• testable enough to maintain over time