pi-sdlc

Run an artifact-driven SDLC with intent, design, plan, verification, review, release and metric feedback.

Packages

Package details

extension

Install pi-sdlc from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-sdlc
Package
pi-sdlc
Version
0.2.0
Published
Nov 12, 2026
Downloads
351/mo · 351/wk
Author
fradser
License
MIT
Types
extension
Size
107.9 KB
Dependencies
1 dependency · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

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

README

pi-sdlc

Capture user intent and keep the next session ready to resume. This package ports the complete dotcodex SDLC workflow to native Pi lifecycle events and the sdlc tool. Python 3.11+ and Git are required. It adds no model provider or background agent. Configured review, eval and diagnosis adapters can make model calls.

Install

pi install npm:pi-sdlc

From a local checkout before publication:

pi install /absolute/path/to/pi-packages/packages/sdlc

The installed package bundles its workflow and templates. It does not require a dotcodex checkout. Development and native acceptance use Pi 1.3.0; published Pi core imports are host-supplied peers. Restart Pi after installation.

Full lifecycle

Read the playbook for all six course stages and the engine contract for configuration and commands. The sdlc tool supports init, status, advance, rewind, handoff, check, eval, review, deploy, metric and archive. The stage order is intent, design, plan, build, test, review, deploy and maintain. Use SPEC.md, PLAN.md and REVIEW.md alongside the existing intent and handoff. The bundled engine can also run directly:

python3 packages/sdlc/scripts/sdlc.py init --cwd /path/to/worktree
python3 packages/sdlc/scripts/sdlc.py status --cwd /path/to/worktree

Approve each artifact through an independent verifier configured in the protected, external SDLC_POLICY_FILE. The tool cannot create an approval. Configure real project checks and an independent historical-task eval suite before plan approval. Changes to source, policy or agent setup invalidate old verification evidence. Independent review checks bugs, security and intent/spec/plan compliance. Important findings block progression. Releases pin the committed version, verify current code owner and environment approvals, check health and roll back on failure. Metric detection uses deterministic bands and drift rules, with new intents in .sdlc/inbox for triage. A task archive keeps the task documents separate from the next change while referencing REVIEW.md by digest rather than duplicating a per-task review policy. ~/.sdlc (or SDLC_HOME) stores the installed method version/source/digest, review-policy and external approval/review references, and metadata-only events.jsonl without a separate methods/ tree or copied chat transcripts. Missing adapters leave a visible blocked stage.

The native edit guard protects planning-stage writes and routes release tools through the engine. Shell, alternate APIs and disabled extensions still need managed permissions, CI checks and service-side authorization. Use isolated CI runners and protected branches. Local state is not a tamper-proof audit service.

Records

The native input event appends the user's original text to INTENT.md in the working directory, before host template expansion. Steering during work and queued follow-ups are retained too. For SDK user runs without an input event, the extension uses the submitted user prompt. Generated extension messages are not user intent. The document uses the course format: an Intent title, an Author and Status line, and exactly these English sections: Problem, Proposed outcome, Affected users and systems, Constraints, Open questions. The body uses the user's language. Unknown authors remain Not provided and the status stays draft until explicit approval. Quoted source requests remain in collapsed details blocks. Corrections preserve prior requests.

The workflow requires the model to read HANDOFF.md and INTENT.md before work and update the handoff before finishing, a planned pause, or an agent handoff. It must checkpoint meaningful progress, keep one current state under 200 lines, link to INTENT.md, and avoid repeated requirements, prompts, final responses, and per-turn history. The current state includes execution decisions, observed checks and results, blockers, and concrete next steps.

before_agent_start injects this workflow through structured prompt sections without replacing other extensions' sections. Custom messages are not user intent; custom continuation runs in a managed session retain the handoff workflow. agent_settled replaces one latest lifecycle block. Abort marks interrupted work; model errors remain explicit. session_shutdown marks an active run interrupted. It does not overwrite an already settled checkpoint. Unexpected interruptions cannot run model work in advance, so the last evidence checkpoint remains. A turn ending is not proof of task completion.

The model reads relevant legacy CONTEXT.md progress and transfers only current decisions, evidence, blockers and next steps. The extension does not write or remove that legacy file. Review retained source text before sharing or committing it.

File safety

Cooperating package writers use pi-kit's exclusive JSON lock publication. Linked or non-regular documents and malformed lifecycle markers are rejected. Checked Markdown replacements use a private temporary file and atomic rename; pi-kit supplies JSON persistence but has no checked Markdown writer. Recording errors are reported through Pi notifications or headless stderr and run guidance. An interrupted writer can leave .sdlc-write-lock.json; inspect its owner before removing it. The extension never steals a lock.

The lock does not cover model edits or unrelated shell commands. Use separate working directories for parallel tasks. The file checks are not a process sandbox. The workflow makes handoff maintenance mandatory instructions; it cannot prove semantic summary quality or enforce a write against explicit user restrictions.

Verify

uv run --with pytest python -m pytest packages/sdlc/tests -q
bun run typecheck
bun pm pack --destination /tmp --quiet --cwd packages/sdlc
uv run --with pytest python packages/sdlc/tests/live_sdlc.py --output /tmp/pi-sdlc-e2e

Native E2E uses the real Pi print/RPC entrypoints, real tools and files, and a deterministic in-process provider with network transport denied. It proves lifecycle, tool execution and artifact behavior. It does not establish real-model instruction following, semantic quality, or physical-terminal interaction.