{"id":41955543,"url":"https://github.com/galando/piv-speckit","last_synced_at":"2026-01-25T22:23:24.283Z","repository":{"id":331996689,"uuid":"1132429144","full_name":"galando/piv-speckit","owner":"galando","description":"PIV (Prime-Implement-Validate) + Spec-Kit: Structured specs, strict TDD, for AI-assisted development.","archived":false,"fork":false,"pushed_at":"2026-01-22T22:32:31.000Z","size":1187,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T00:13:53.019Z","etag":null,"topics":["ai-assisted-development","anthropic","claude","claude-ai","claude-code","code-quality","context-engineering","copilot","cursor","developer-tools","nodejs","piv-methodology","python","react","software-development-workflow","spring-boot","template"],"latest_commit_sha":null,"homepage":"https://galando.github.io/piv-speckit/","language":"Shell","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/galando.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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},"funding":{"custom":["https://buymeacoffee.com/galando"]}},"created_at":"2026-01-11T23:53:38.000Z","updated_at":"2026-01-22T22:32:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/galando/piv-speckit","commit_stats":null,"previous_names":["galando/claude-piv-skeleton","galando/claude-dev-framework","galando/piv-speckit"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/galando/piv-speckit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galando%2Fpiv-speckit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galando%2Fpiv-speckit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galando%2Fpiv-speckit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galando%2Fpiv-speckit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/galando","download_url":"https://codeload.github.com/galando/piv-speckit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galando%2Fpiv-speckit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28760643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T20:56:06.009Z","status":"ssl_error","status_checked_at":"2026-01-25T20:54:48.203Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-assisted-development","anthropic","claude","claude-ai","claude-code","code-quality","context-engineering","copilot","cursor","developer-tools","nodejs","piv-methodology","python","react","software-development-workflow","spring-boot","template"],"created_at":"2026-01-25T22:23:20.296Z","updated_at":"2026-01-25T22:23:24.275Z","avatar_url":"https://github.com/galando.png","language":"Shell","funding_links":["https://buymeacoffee.com/galando"],"categories":[],"sub_categories":[],"readme":"# PIV Spec-Kit\n\n[![PIV Spec-Kit](https://img.shields.io/badge/PIV_Spec--Kit-Framework-blue?style=for-the-badge)](https://github.com/galando/piv-speckit)\n[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)\n[![Visual Guide](https://img.shields.io/badge/🌐_Visual_Guide-Interactive-467fd9?style=for-the-badge)](https://galando.github.io/piv-speckit/)\n[![Inspired by Spec-Kit](https://img.shields.io/badge/Inspired_By-Spec--Kit-blue?style=for-the-badge)](https://github.com/github/spec-kit)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/galando/piv-speckit)\n\n**PIV (Prime-Implement-Validate) + Spec-Kit: Structured specs, strict TDD, for AI-assisted development.**\n\nWorks with **Claude Code**, **Cursor**, **GitHub Copilot**, **OpenAI Codex**, and 20+ AI coding tools.\n\n---\n\n## What is PIV?\n\n**PIV = Prime → Implement → Validate**\n\nA development methodology for AI-assisted software development:\n\n- **Prime**: Load codebase context before making changes\n- **Implement**: Write tests FIRST (strict TDD), then minimal code\n- **Validate**: Automatic testing and verification\n\n[→ Interactive Visual Guide](https://galando.github.io/piv-speckit/) | [→ Full Methodology](.claude/reference/methodology/PIV-METHODOLOGY.md)\n\n---\n\n## Enhanced with Spec-Kit\n\nThis framework integrates best practices from [GitHub's Spec-Kit](https://github.com/github/spec-kit), adding **structured specification artifacts** to the PIV methodology.\n\n### What This Adds\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `constitution.md` | Project principles (one-time setup) | `/piv-speckit:constitution` |\n| `spec.md` | Functional requirements (WHAT) | `/piv-speckit:plan-feature` |\n| `plan.md` | Technical approach (HOW) | `/piv-speckit:plan-feature` |\n| `tasks.md` | Implementation steps (DO) | `/piv-speckit:plan-feature` |\n| `quickstart.md` | TL;DR for humans | `/piv-speckit:plan-feature` |\n\n### Multi-AI Compatibility\n\nAll artifacts are **structured Markdown** - works with ANY AI tool:\n- **Claude Code** (plugin) - Full experience with commands\n- **Cursor** - Reads files directly\n- **GitHub Copilot** - Reads files directly\n\nNo Claude Code dependency for planning or implementation!\n\n---\n\n## Installation\n\n### Claude Code (Full Experience) ⭐ Recommended\n\n```bash\n# Add marketplace\n/plugin marketplace add galando/piv-speckit\n\n# Install PIV + Spec-Kit\n/plugin install piv-speckit\n```\n\n**Commands:** `/piv-speckit:prime`, `/piv-speckit:plan-feature`, `/piv-speckit:execute`, `/piv-speckit:constitution`\n\n**Features:** Auto-activating skills (TDD, code-review, security), full reference docs, agent context system.\n\n### Cursor / GitHub Copilot / Other AI Tools\n\n```bash\ncurl -s https://raw.githubusercontent.com/galando/piv-speckit/main/scripts/piv.sh | bash\n```\n\n**How it works:**\n- Generates `AGENTS.md` - a single file with PIV methodology instructions\n- Cursor, Copilot, and other tools read `AGENTS.md` automatically via their project-aware features\n- **No slash commands** - type your requests naturally, the AI follows PIV methodology\n\n**Difference from Claude Code:**\n\n| Feature | Claude Code | Cursor / Copilot |\n|---------|-------------|-------------------|\n| Slash commands | ✅ `/piv-speckit:*` | ❌ (natural language) |\n| Auto-skills | ✅ TDD, security | ❌ |\n| Constitution template | ✅ **Embedded in plugin** | ✅ Included |\n| Spec templates | ✅ **Embedded in plugin** | ✅ Included |\n| PIV methodology | ✅ Full | ✅ Compact (AGENTS.md) |\n\n**Note:** Plugin templates are embedded directly in command files - they work immediately after installation without needing external template files.\n\n---\n\n## Tool Comparison\n\n| Feature | Claude Code (Plugin) | Cursor / Copilot (Script) |\n|---------|---------------------|----------------------------|\n| Commands | `/piv-speckit:prime`, `/piv-speckit:plan-feature`, `/piv-speckit:execute`, `/piv-speckit:constitution` | Natural language (AI reads AGENTS.md) |\n| Auto-Skills | ✅ TDD, code-review, security activate automatically | ❌ |\n| Spec Templates | ✅ Included | ✅ Included |\n| Constitution | ✅ Included | ✅ Included |\n| Context Loading | Smart layering (~15KB on-demand) | AGENTS.md (~500 lines, always loaded) |\n| Updates | `/plugin update` | Re-run script |\n\n---\n\n## Architecture \u0026 Workflow\n\n### Complete Development Flow\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                           PIV SPEC-KIT WORKFLOW                             │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                             │\n│  1. CONSTITUTION (One-time)                                                 │\n│     ┌─────────────────────────────────────────────────────────────────┐    │\n│     │ /piv-speckit:constitution                                          │    │\n│     │ → Creates .claude/memory/constitution.md                        │    │\n│     │ → Defines: purpose, principles, stack, constraints              │    │\n│     └─────────────────────────────────────────────────────────────────┘    │\n│                                    ↓                                        │\n│  2. PRIME (Context Loading)                                               │\n│     ┌─────────────────────────────────────────────────────────────────┐    │\n│     │ /piv-speckit:prime                                                  │    │\n│     │ → Analyzes codebase structure                                   │    │\n│     │ → Identifies patterns, conventions, tech stack                  │    │\n│     │ → Loads only relevant context (smart layering)                 │    │\n│     └─────────────────────────────────────────────────────────────────┘    │\n│                                    ↓                                        │\n│  3. PLAN (Structured Specs)                                               │\n│     ┌─────────────────────────────────────────────────────────────────┐    │\n│     │ /piv-speckit:plan-feature \"Add user authentication\"              │    │\n│     │ → Creates .claude/specs/{feature}/                              │    │\n│     │   ├─ spec.md        (WHAT: requirements, user stories)          │    │\n│     │   ├─ plan.md        (HOW: architecture, data model, APIs)       │    │\n│     │   ├─ tasks.md       (DO: step-by-step implementation)          │    │\n│     │   └─ quickstart.md  (TL;DR: quick reference)                   │    │\n│     └─────────────────────────────────────────────────────────────────┘    │\n│                                    ↓                                        │\n│  4. IMPLEMENT (Strict TDD)                                               │\n│     ┌─────────────────────────────────────────────────────────────────┐    │\n│     │ /piv-speckit:execute .claude/specs/{feature}/tasks.md              │    │\n│     │                                                                  │    │\n│     │   For each task:                                                 │    │\n│     │   ├─ RED:   Write failing test first                            │    │\n│     │   ├─ GREEN: Write minimal code to pass                          │    │\n│     │   └─ REFACTOR: Improve while tests stay green                   │    │\n│     │                                                                  │    │\n│     │   Skills auto-activate: TDD, code-review, security              │    │\n│     └─────────────────────────────────────────────────────────────────┘    │\n│                                    ↓                                        │\n│  5. VALIDATE (Automatic)                                                 │\n│     ┌─────────────────────────────────────────────────────────────────┐    │\n│     │ Auto-runs after execute                                          │    │\n│     │ → Tests: all passing?                                           │    │\n│     │ → Coverage: ≥80%?                                               │    │\n│     │ → Security: no vulnerabilities?                                  │    │\n│     │ → TDD compliance: tests written first?                          │    │\n│     └─────────────────────────────────────────────────────────────────┘    │\n│                                    ↓                                        │\n│  6. COMMIT                                                                  │\n│     ┌─────────────────────────────────────────────────────────────────┐    │\n│     │ /commit                                                          │    │\n│     │ → Conventional commit message                                    │    │\n│     │ → Atomic, focused changes                                       │    │\n│     └─────────────────────────────────────────────────────────────────┘    │\n│                                                                             │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Component Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                     SOURCE OF TRUTH                              │\n│                     /.claude/ directory                         │\n│                                                                    │\n│  .claude/                                                          │\n│  ├── commands/           # Slash command definitions            │\n│  │   ├── piv_loop/       # Prime, Plan, Execute, Constitution   │\n│  │   ├── validation/     # Validate, code-review, learn         │\n│  │   └── bug_fix/        # RCA, fix                               │\n│  ├── skills/            # Auto-activating quality enforcers      │\n│  │   ├── test-driven-development    # TDD enforcement            │\n│  │   ├── code-review                # Quality checks              │\n│  │   ├── api-design                 # REST API patterns           │\n│  │   └── security                   # Security guidelines         │\n│  ├── specs/.templates/  # Spec artifact templates               │\n│  ├── memory/           # Stored context (constitution)          │\n│  └── reference/         # Complete methodology docs           │\n└───────────────────────────────┬─────────────────────────────────┘\n                                │\n        ┌───────────────────────┼───────────────────────────────┐\n        ▼                       ▼                               ▼\n┌───────────────┐      ┌───────────────┐              ┌───────────────┐\n│  CLAUDE CODE  │      │    CURSOR     │              │ OTHER TOOLS   │\n│   (Plugin)    │      │   (Script)    │              │   (Script)    │\n│               │      │               │              │               │\n│ Full commands │      │  AGENTS.md    │              │  AGENTS.md    │\n│ Auto-skills   │      │  (\u003c 500 lines)│              │               │\n│ Smart context │      │               │              │               │\n└───────────────┘      └───────────────┘              └───────────────┘\n```\n\n### Key Principles\n\n| Principle | Description |\n|-----------|-------------|\n| **Context Layering** | Load only relevant context (~15KB), not entire codebase |\n| **Spec Artifacts** | Split WHAT (spec), HOW (plan), DO (tasks) for clarity |\n| **Strict TDD** | RED → GREEN → REFACTOR - never write code before tests |\n| **Auto-Validation** | Quality checks run automatically after implementation |\n| **Multi-AI Compatible** | All artifacts are Markdown - works with any AI tool |\n\n---\n\n## Key Features\n\n| Feature | Description |\n|---------|-------------|\n| 🚨 **Strict TDD** | Mandatory RED-GREEN-REFACTOR cycle. Zero exceptions. |\n| ⚡ **Skills System** | Auto-activating behaviors enforce best practices in real-time |\n| 🧠 **Adaptive Learning** | Framework gets smarter with every feature you build |\n| 🔧 **Technology Agnostic** | Works with Spring Boot, Node.js, Python, React, and more |\n| ⚙️ **Commands** | `/piv-speckit:prime`, `/piv-speckit:plan-feature`, `/piv-speckit:execute` |\n\n[→ See all features](docs/features/) | [→ Full commands list](docs/getting-started/02-quick-start.md#piv-commands-reference)\n\n---\n\n## 🎬 See It In Action\n\n**Watch PIV power a real feature from start to finish:**\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│  USER: \"/piv-speckit:prime\"                                                │\n│                                                                          │\n│  CLAUDE: [Loads project context]                                         │\n│    → \"Project: Spring Boot + React + PostgreSQL\"                        │\n│    → \"Architecture: Controller → Service → Repository\"                 │\n│    → \"15 Java classes, 8 React components identified\"                  │\n└─────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────────────────┐\n│  USER: \"Plan a password reset feature\"                              │\n│  AI: Creates spec.md, plan.md, tasks.md, quickstart.md              │\n│                                                                          │\n│  CLAUDE: [Loads from .claude/reference/methodology/]                    │\n│    → Reads PIV-METHODOLOGY.md for planning steps                        │\n│    → [Loads from technologies/backend/spring-boot/]                      │\n│    → Reads security patterns, email templates                           │\n│    → Creates implementation plan...                                      │\n│    → Plan saved to .claude/agents/plans/                               │\n└─────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────────────────┐\n│  USER: \"/piv-speckit:execute\"                                              │\n│                                                                          │\n│  CLAUDE: [test-driven-development SKILL ACTIVATES 🔴]                    │\n│    → \"🔴 RED: Writing test FIRST...\"                                     │\n│    → Creates PasswordResetServiceTest.java                             │\n│    → Test FAILS ✅                                                       │\n│                                                                          │\n│    → \"🟢 GREEN: Writing minimal code...\"                                │\n│    → Creates PasswordResetService.java                                │\n│    → Test PASSES ✅                                                       │\n│                                                                          │\n│    → \"🔵 REFACTOR: Improving...\"                                       │\n│    → Extracts EmailService to separate class                             │\n│    → Tests STILL PASS ✅                                                 │\n└─────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────────────────┐\n│  [validation:code-review SKILL ACTIVATES]                              │\n│                                                                          │\n│  CLAUDE: [Reviews code, references .claude/rules/security.md]            │\n│    → \"✅ Uses bcrypt for password hashing\"                              │\n│    → \"✅ Token expires in 1 hour\"                                       │\n│    → \"⚠️  Suggestion: Add rate limiting\"                                 │\n│    → Report saved to .claude/agents/code-reviews/                       │\n└─────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────────────────┐\n│  [validation:learn SKILL ACTIVATES]                                    │\n│                                                                          │\n│  CLAUDE: [Extracts learning from review]                                 │\n│    → \"Pattern captured: Always set token expiration to 1 hour\"          │\n│    → \"Pattern captured: Use bcrypt for password hashing\"                │\n│    → Saves to .claude/agents/learnings/                                │\n│                                                                          │\n│  → Next security feature: \"Based on past learnings, I'll use           │\n│     bcrypt and 1-hour expiration...\"                                   │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n**This is the PIV difference:**\n- ✅ **Active enforcement** - Skills activate in real-time\n- ✅ **Captures learning** - Framework gets smarter\n- ✅ **Technology-aware** - Loads patterns from `technologies/`\n- ✅ **Full trace** - Every step recorded and reviewable\n\n---\n\n## Documentation\n\n### Getting Started\n| Guide | Description |\n|-------|-------------|\n| [Quick Start](docs/getting-started/02-quick-start.md) | Get started in 5 minutes |\n| [PIV Methodology](.claude/reference/methodology/PIV-METHODOLOGY.md) | Complete methodology guide |\n\n**[→ Documentation Hub](docs/README.md)** — Full index: Features, Commands, Support, Extending\n\n### Tool-Specific Guides\n| Guide | Description |\n|-------|-------------|\n| [Cursor Guide](docs/getting-started/05-cursor-guide.md) | Complete guide for Cursor users |\n| [GitHub Copilot Guide](docs/getting-started/06-copilot-guide.md) | Complete guide for Copilot users |\n\n---\n\n## Supported Technologies\n\n**Backend:** Spring Boot • Node.js/Express • Python/FastAPI\n**Frontend:** React + TypeScript\n**Database:** PostgreSQL\n\n[→ Add new technologies](docs/extending/01-adding-technologies.md)\n\n---\n\n## Repository Structure\n\n```\npiv-speckit/\n├── .claude/                     # Claude Code configuration\n│   ├── CLAUDE.md                # Project instructions\n│   ├── agents/                  # Artifact directories\n│   ├── commands/                # PIV command definitions\n│   ├── reference/               # Complete guides\n│   ├── rules/                   # Coding rules\n│   └── skills/                  # Auto-activating behaviors\n├── .claude-plugin/              # Claude Code plugin manifest\n├── marketplace/                 # Plugin marketplace catalog\n├── AGENTS.md                    # PIV methodology for AI tools\n├── .cursor/rules/               # Cursor auto-attach rules\n├── .github/                     # GitHub configuration\n├── docs/                        # Comprehensive documentation\n├── scripts/                     # Utility scripts\n├── technologies/                # Technology templates\n└── VERSION                      # Single source of truth for versioning\n```\n\n---\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## Origins\n\n**PIV Methodology created by [Cole Medin (coleam00)](https://github.com/coleam00)**\n\nBased on [context-engineering-intro](https://github.com/coleam00/context-engineering-intro) and [habit-tracker](https://github.com/coleam00/habit-tracker).\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n---\n\n**Made with ❤️ for the AI-assisted development community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalando%2Fpiv-speckit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgalando%2Fpiv-speckit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalando%2Fpiv-speckit/lists"}