{"id":50306699,"url":"https://github.com/felipefontoura/pi-sdd-kit","last_synced_at":"2026-05-28T17:01:21.452Z","repository":{"id":358056743,"uuid":"1239353812","full_name":"felipefontoura/pi-sdd-kit","owner":"felipefontoura","description":"Pi skill pack for practical Specification-Driven Development workflows.","archived":false,"fork":false,"pushed_at":"2026-05-15T13:26:26.000Z","size":79,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T14:34:27.212Z","etag":null,"topics":["pi-agent","pi-dev","pi-package","skills"],"latest_commit_sha":null,"homepage":"https://pi.dev/packages/@felipefontoura/pi-sdd-kit?name=pi-sdd-kit","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/felipefontoura.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-15T02:32:13.000Z","updated_at":"2026-05-15T14:14:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/felipefontoura/pi-sdd-kit","commit_stats":null,"previous_names":["felipefontoura/pi-sdd-kit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/felipefontoura/pi-sdd-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipefontoura%2Fpi-sdd-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipefontoura%2Fpi-sdd-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipefontoura%2Fpi-sdd-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipefontoura%2Fpi-sdd-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/felipefontoura","download_url":"https://codeload.github.com/felipefontoura/pi-sdd-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipefontoura%2Fpi-sdd-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33617718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pi-agent","pi-dev","pi-package","skills"],"created_at":"2026-05-28T17:01:19.406Z","updated_at":"2026-05-28T17:01:21.443Z","avatar_url":"https://github.com/felipefontoura.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pi SDD Kit\n\nA skill pack for the [Pi Coding Agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) that implements a practical **Specification-Driven Development (SDD)** workflow for small and medium projects.\n\nIt helps turn raw ideas into implemented software through explicit artifacts, human gates, validated status transitions, traceability, and verification.\n\n```text\nIDEA → PLAN → PRD → SPEC → TASKS → EXEC → REVIEW\n```\n\nThe pack also includes skills to initialize the AI workspace, maintain reusable project context, inspect the current SDD status, consume optional upstream handoffs, produce downstream handoff briefs, and provide ready-to-use templates for users.\n\n---\n\n## Language policy\n\nThis package source, skill instructions, templates, and documentation are written in **EN-US**.\n\nAt runtime, skills should adapt to the user's chat language:\n\n- respond in the language used by the user at the start of the chat or skill request;\n- write generated project artifacts in that same language;\n- preserve canonical technical identifiers such as file names, status values, commands, code symbols, and stable IDs;\n- default to EN-US when the user's language is ambiguous.\n\nExample: if the user starts in Portuguese, the skill should answer in Portuguese and write `requirements.md`, `design.md`, `tasks.md`, etc. in Portuguese, while keeping paths, status values, and IDs unchanged.\n\n---\n\n## Additional study material\n\nFor a deeper explanation of the SDD methodology and examples of how to use the workflow, see:\n\n- [felipefontoura/sdd-book](https://github.com/felipefontoura/sdd-book)\n\n## Acknowledgements\n\nSpecial thanks to the [Compozy skills](https://github.com/compozy/compozy/tree/main/skills) project. Its skill design demonstrates an excellent level of technical rigor, operational quality, explicit gates, verification discipline, and practical AI workflow structure. This package was inspired by that quality bar and adapts similar principles to a lightweight SDD workflow for Pi.\n\n---\n\n## Why use this\n\nAI can accelerate development, but it can also accelerate ambiguity. This kit enforces a simple discipline:\n\n1. explore before planning;\n2. define **WHAT/WHY** before **HOW**;\n3. break implementation into verifiable tasks;\n4. implement only after human approval;\n5. review the delivery against approved artifacts.\n\nThe result is less rework, less implicit scope, and more predictable implementation.\n\n---\n\n## Installation\n\nFrom npm:\n\n```bash\npi install npm:@felipefontoura/pi-sdd-kit\n```\n\nLocal development install:\n\n```bash\npi install /absolute/path/to/pi-sdd-kit\n```\n\nThen reload Pi:\n\n```text\n/reload\n```\n\n---\n\n## Available skills\n\nThis package is intended to be used through SDD-prefixed Pi skill commands: `/skill:sdd-*`.\n\n```text\n/skill:sdd-init\n/skill:sdd-steering\n/skill:sdd-idea\n/skill:sdd-plan\n/skill:sdd-prd\n/skill:sdd-spec\n/skill:sdd-tasks\n/skill:sdd-exec\n/skill:sdd-review\n/skill:sdd-status\n```\n\n### `/skill:sdd-init`\n\nInitializes the project AI/SDD workspace.\n\nTypical structure:\n\n```text\n.ai/\n  steering/\n  sdd/\n```\n\nUse this when adopting the workflow in a new or existing project.\n\n---\n\n### `/skill:sdd-steering`\n\nCreates or updates reusable global context in:\n\n```text\n.ai/steering/\n```\n\nExamples:\n\n```text\n.ai/steering/product.md\n.ai/steering/tech-stack.md\n.ai/steering/conventions.md\n.ai/steering/principles.md\n.ai/steering/lp.md\n```\n\nUse it for product vision, stack, conventions, project principles, UX rules, landing page rules, business domain guidance, or any context reused by multiple skills.\n\n---\n\n### `/skill:sdd-idea`\n\nExplores a raw idea before turning it into a plan or requirements.\n\nUse it when you are still thinking and want cognitive clarity.\n\nTypical output:\n\n```text\n.ai/sdd/ideas/001-feature-idea.md\n```\n\n---\n\n### `/skill:sdd-plan`\n\nCreates or updates a project/product plan.\n\nOptional for small changes and recommended for medium projects with multiple features, phases, or dependencies.\n\nTypical output:\n\n```text\n.ai/sdd/PLAN.md\n```\n\n---\n\n### `/skill:sdd-prd`\n\nCreates `requirements.md` for a feature.\n\nFocuses on **WHAT/WHY**:\n\n- users;\n- user stories;\n- acceptance criteria;\n- EARS-style functional requirements;\n- non-functional requirements;\n- explicit out-of-scope boundaries;\n- guided requirement questions and recorded decisions when ambiguity matters.\n\nTypical output:\n\n```text\n.ai/sdd/specs/001-feature-name/requirements.md\n.ai/sdd/specs/001-feature-name/.status\n```\n\nFeature IDs are assigned from the actual directories under `.ai/sdd/specs/` using the next available numeric prefix. `.ai/sdd/INDEX.md` is a dashboard, not the numbering source.\n\n---\n\n### `/skill:sdd-spec`\n\nCreates `design.md` from approved requirements.\n\nFocuses on **HOW**:\n\n- architecture;\n- components/modules;\n- state/data;\n- APIs/integrations;\n- security/permissions;\n- edge cases;\n- technical decisions;\n- verification strategy.\n\nTypical output:\n\n```text\n.ai/sdd/specs/001-feature-name/design.md\n```\n\n---\n\n### `/skill:sdd-tasks`\n\nCreates `tasks.md` from an approved design.\n\nTasks are small, dependency-aware, verifiable, and traceable to requirements. This step also performs the implementation readiness check, so users do not need a separate analysis command.\n\nTypical output:\n\n```text\n.ai/sdd/specs/001-feature-name/tasks.md\n.ai/sdd/handoff/sdd-brief.md   # after tasks:approved\n```\n\n---\n\n### `/skill:sdd-exec`\n\nExecutes an approved task.\n\nThe skill should:\n\n- require `tasks:approved`;\n- keep scope limited to the selected task;\n- follow project conventions;\n- run verification;\n- update progress only with evidence.\n\n---\n\n### `/skill:sdd-review`\n\nReviews implementation against:\n\n- `requirements.md`;\n- `design.md`;\n- `tasks.md`;\n- produced code;\n- verification evidence.\n\nTypical output:\n\n```text\n.ai/sdd/specs/001-feature-name/review.md\n.ai/sdd/handoff/sdd-brief.md   # refreshed after review:done\n```\n\n---\n\n### `/skill:sdd-status`\n\nShows a dashboard of the current SDD state.\n\nUse it to see:\n\n- existing ideas;\n- current plan;\n- specs in draft/approved/implementation/review states;\n- blockers;\n- the next safe action.\n\nThis is a read-only skill.\n\n---\n\n## User-facing templates\n\nThis package includes ready-to-copy templates in:\n\n```text\ntemplates/\n```\n\nThey are based on the SDD flow and include practical structure inspired by PRD, TechSpec, task, review, issue, and ADR workflows.\n\nAvailable templates:\n\n```text\ntemplates/sdd-index.md\ntemplates/sdd-workflow.md\ntemplates/steering-product.md\ntemplates/steering-tech-stack.md\ntemplates/steering-conventions.md\ntemplates/steering-principles.md\ntemplates/steering-landing-page.md\ntemplates/idea.md\ntemplates/plan.md\ntemplates/requirements.md\ntemplates/design.md\ntemplates/tasks.md\ntemplates/task.md\ntemplates/review.md\ntemplates/handoff.md\ntemplates/issue.md\ntemplates/adr.md\n```\n\nUse them as examples, copy them manually, or let the skills fill equivalent artifacts in the user's chat language.\n\n---\n\n## Artifact structure\n\nThe package separates reusable AI context from SDD-specific artifacts.\n\n```text\n.ai/\n  steering/\n    product.md\n    tech-stack.md\n    conventions.md\n    principles.md\n    lp.md\n  strategy/\n    handoff/\n      strategy-brief.md          # optional upstream input from pi-strategy or another package\n  sdd/\n    INDEX.md\n    WORKFLOW.md\n    PLAN.md\n    handoff/\n      sdd-brief.md               # downstream SDD output contract\n    ideas/\n      001-feature-idea.md\n    specs/\n      001-feature-name/\n        .status\n        requirements.md\n        design.md\n        tasks.md\n        review.md\n        decisions.md\n```\n\n### `.ai/steering/`\n\nReusable context for any skill or AI workflow.\n\nExamples:\n\n- product vision;\n- personas;\n- stack;\n- verification commands;\n- architecture conventions;\n- landing page rules;\n- copywriting rules;\n- accessibility standards.\n\n### `.ai/sdd/`\n\nArtifacts specific to the Specification-Driven Development workflow.\n\n### Optional upstream handoff\n\nWhen present, SDD skills may read:\n\n```text\n.ai/strategy/handoff/strategy-brief.md\n```\n\nThis file is optional. It can seed `/skill:sdd-idea`, `/skill:sdd-plan`, or `/skill:sdd-prd`, but it does **not** bypass SDD approval gates.\n\n### SDD handoff output\n\nAfter approved tasks, and again after completed review, SDD can write or refresh:\n\n```text\n.ai/sdd/handoff/sdd-brief.md\n```\n\nThis is the consolidated output contract for downstream agents/packages. It summarizes source inputs, approved requirements, design decisions, task order, verification plan, review status, blockers, and readiness while preserving links to the original artifacts.\n\n---\n\n## Workflow states\n\nEach feature spec uses a `.status` file with one of these values:\n\n```text\nidea:exploring\nidea:captured\nplan:draft\nplan:approved\nrequirements:draft\nrequirements:approved\ndesign:draft\ndesign:approved\ntasks:draft\ntasks:approved\nimplementation:in-progress\nimplementation:done\nreview:done\n```\n\nDrafts may be saved before approval, but **drafts do not unlock gates**. Skills must validate `.status` before advancing a phase; artifact existence alone never counts as approval.\n\n---\n\n## Human gates\n\nThe kit is designed to preserve human decision points.\n\n```text\nrequirements:draft   → human approval → requirements:approved\ndesign:draft         → human approval → design:approved\ntasks:draft          → human approval → tasks:approved\ntasks:approved       → implementation allowed\nimplementation:done  → review\n```\n\nImportant rules:\n\n- do not implement before `tasks:approved`;\n- do not treat drafts as approved artifacts;\n- do not silently change requirements or design during implementation;\n- do not claim completion without fresh verification evidence.\n\n---\n\n## Traceability\n\nTemplates use stable IDs:\n\n```text\nUS-001   User Story\nFR-001   Functional Requirement\nNFR-001  Non-Functional Requirement\nTD-001   Technical Decision\nT1       Task\n```\n\nThey also include mappings for:\n\n- requirements → design;\n- requirements → tasks;\n- requirements/tasks → review;\n- SDD handoff → requirements, design, tasks, review, and `.status`.\n\nThis helps both humans and AI notice uncovered requirements or implementation drift.\n\n---\n\n## Workflow guide\n\nFor a copyable user-facing guide to the SDD flow, see:\n\n```text\ntemplates/sdd-workflow.md\n```\n\nIt documents the simple flow, gates, status rules, feature IDs, steering context, and recommended next actions.\n\nIt also makes explicit that clarification and analysis/checklist behavior are embedded in existing phases (`PRD` and `TASKS`) instead of extra public commands.\n\n## Recommended quickstart\n\n### 1. Initialize the project\n\n```text\n/skill:sdd-init\n```\n\n### 2. Create reusable context\n\n```text\n/skill:sdd-steering\n```\n\nFor example: `product.md`, `tech-stack.md`, `conventions.md`, and optional `principles.md`.\n\n### 3. Explore an idea\n\n```text\n/skill:sdd-idea\n```\n\n### 4. Plan if needed\n\n```text\n/skill:sdd-plan\n```\n\nFor small features, you can go directly to PRD.\n\n### 5. Create requirements\n\n```text\n/skill:sdd-prd\n```\n\n### 6. Create technical design\n\n```text\n/skill:sdd-spec\n```\n\n### 7. Break into tasks\n\n```text\n/skill:sdd-tasks\n```\n\n### 8. Execute incrementally\n\n```text\n/skill:sdd-exec\n```\n\n### 9. Review\n\n```text\n/skill:sdd-review\n```\n\n### 10. Check status anytime\n\n```text\n/skill:sdd-status\n```\n\n---\n\n## When to use PLAN\n\nUse `/skill:sdd-plan` when there are:\n\n- multiple features;\n- delivery phases;\n- dependencies between modules;\n- different personas;\n- unclear MVP boundaries;\n- risk of uncontrolled scope growth.\n\nSkip PLAN for:\n\n- small adjustments;\n- isolated screens;\n- well-bounded changes;\n- simple bug fixes.\n\n---\n\n## Example: small flow\n\n```text\n/skill:sdd-init\n/skill:sdd-prd      → creates requirements.md\n/skill:sdd-spec     → creates design.md\n/skill:sdd-tasks    → creates tasks.md\n/skill:sdd-exec     → implements T1\n/skill:sdd-review   → validates delivery\n```\n\n## Example: medium flow\n\n```text\n/skill:sdd-init\n/skill:sdd-steering\n/skill:sdd-idea\n/skill:sdd-plan\n/skill:sdd-prd\n/skill:sdd-spec\n/skill:sdd-tasks\n/skill:sdd-exec\n/skill:sdd-status\n/skill:sdd-review\n```\n\n---\n\n## Philosophy\n\nThis kit follows a few principles:\n\n- **The spec is a contract, not decoration.**\n- **Code is a consequence of the spec.**\n- **Human approval is a gate, not a formality.**\n- **Draft does not mean approved.**\n- **Tasks must be verifiable.**\n- **Review should validate against artifacts, not only opinion.**\n- **Global context belongs in `.ai/steering/`, not in every feature.**\n- **Handoffs are contracts between workflow stages, not replacements for source artifacts.**\n\n---\n\n## Package development\n\nValidate package contents:\n\n```bash\nnpm pack --dry-run\n```\n\nPackage structure:\n\n```text\nskills/\n  _shared/references/sdd-practical.md\n  _shared/references/templates.md\n  sdd-init/SKILL.md\n  sdd-steering/SKILL.md\n  sdd-idea/SKILL.md\n  sdd-plan/SKILL.md\n  sdd-prd/SKILL.md\n  sdd-spec/SKILL.md\n  sdd-tasks/SKILL.md\n  sdd-exec/SKILL.md\n  sdd-review/SKILL.md\n  sdd-status/SKILL.md\ntemplates/\n  README.md\n  requirements.md\n  design.md\n  tasks.md\n  review.md\n  handoff.md\n  adr.md\n  ...\n```\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipefontoura%2Fpi-sdd-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelipefontoura%2Fpi-sdd-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipefontoura%2Fpi-sdd-kit/lists"}