piv-speckit

🥈Silver

PIV Spec-Kit is a structured framework for AI-assisted development. It combines Prime-Implement-Validate methodology with strict Test-Driven Development. Benefits developers by ensuring high code quality and reducing errors. Integrates with Claude AI for code generation and validation. Suitable for Node.js, Python, React, and Spring Boot projects.

2720Updated 1mo ago

Intermediate30min to implementautomation

Saves ~180 min per use

Quick InstallView Source

git clone https://github.com/galando/piv-speckit.git

Works with:

Claude

Overview

About This Skill

How to Use

[{"step":"Prime Phase: Start with your requirements document. Break down the feature into 3-5 core requirements and identify potential edge cases. Use the prompt template to generate the initial design analysis.","action":"Copy the prompt template into Claude, replace [PLACEHOLDERS] with your specific requirements, and run the analysis. Review the design decisions before proceeding.","tip":"For complex features, break them into smaller sub-features first. Use bullet points in your requirements to make them easier to process."},{"step":"Implement Phase: Generate the code using the validated design. Ensure all functions have JSDoc comments and follow your project's style guide.","action":"Use the implementation output as a starting point. Modify the code to fit your existing codebase structure. Add any additional helper functions needed.","tip":"For large features, implement one function at a time and validate each before proceeding to the next. Use your IDE's refactoring tools to maintain consistency."},{"step":"Validate Phase: Create comprehensive unit tests that cover all code paths, including error conditions. Aim for 100% code coverage.","action":"Use the test framework specified in your prompt (Jest, pytest, etc.). Run tests locally first, then integrate with your CI/CD pipeline.","tip":"Write tests for both happy paths and edge cases. Use mocking for external dependencies like databases or APIs. Consider property-based testing for complex logic."},{"step":"Iterate: Review the test results and code coverage. Refactor if needed, then repeat the validation phase until all tests pass.","action":"Use tools like Istanbul for coverage reports. Address any uncovered code paths by adding more tests or modifying the implementation.","tip":"Set up pre-commit hooks to run tests automatically before code is committed. This ensures no untested code enters your repository."},{"step":"Document: Add the generated documentation to your project's README or wiki. Include the design decisions and test coverage metrics.","action":"Update your project documentation with the new feature's API reference, usage examples, and test results. Include any known limitations.","tip":"For team projects, create a pull request with the complete PIV Spec-Kit output attached. This gives reviewers context about the implementation decisions."}]

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/galando/piv-speckit

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Act as a PIV Spec-Kit (Prime-Implement-Validate + Test-Driven Development) assistant for [LANGUAGE/PROJECT TYPE]. Follow this process: 1) Prime: Analyze the requirements for [FEATURE] and generate a high-level design with edge cases. 2) Implement: Write the code for [FEATURE] in [LANGUAGE] with clear comments. 3) Validate: Create unit tests using [TEST_FRAMEWORK] that cover 100% of the new code. Use [CODE_STYLE_GUIDE] for consistency. Start with: 'Prime: [REQUIREMENTS]'

Example Output

### Prime Analysis for User Authentication Feature (Node.js/Express)

**Requirements:**
- Users must register with email/password (min 8 chars, valid email format)
- Passwords hashed with bcrypt (cost factor 12)
- JWT tokens expire in 24h
- Rate limiting: 5 failed attempts per IP
- Email verification required (token expires in 1h)

**Design Decisions:**
- Use Express middleware for auth validation
- Store users in PostgreSQL with `created_at` and `verified_at` timestamps
- Implement token refresh endpoint
- Edge cases: concurrent registrations, expired tokens, SQL injection attempts

### Implementation (Node.js/Express)
```javascript
// auth.service.js
import bcrypt from 'bcryptjs';
import jwt from 'jsonwebtoken';
import { pool } from './db.js';

const registerUser = async (email, password) => {
  // Validate input
  if (!email || !password || password.length < 8) {
    throw new Error('Invalid credentials');
  }

  // Check existing user
  const existing = await pool.query('SELECT id FROM users WHERE email = $1', [email]);
  if (existing.rows[0]) throw new Error('Email already registered');

  // Hash password
  const hashed = await bcrypt.hash(password, 12);

  // Create user
  const user = await pool.query(
    'INSERT INTO users (email, password_hash) VALUES ($1, $2) RETURNING id, email',
    [email, hashed]
  );

  // Generate verification token
  const token = jwt.sign({ userId: user.rows[0].id }, process.env.JWT_SECRET, { expiresIn: '1h' });

  return { userId: user.rows[0].id, email: user.rows[0].email, verificationToken: token };
};

export { registerUser };
```

### Validation (Jest + Supertest)
```javascript
// auth.service.test.js
describe('User Registration', () => {
  beforeAll(() => {
    // Setup test DB
  });

  it('should create user with valid credentials', async () => {
    const result = await registerUser('test@example.com', 'validPassword123');
    expect(result.userId).toBeDefined();
    expect(result.verificationToken).toBeTruthy();
  });

  it('should reject short passwords', async () => {
    await expect(registerUser('test@example.com', 'short')).rejects.toThrow('Invalid credentials');
  });

  it('should prevent duplicate emails', async () => {
    await registerUser('duplicate@example.com', 'password123');
    await expect(registerUser('duplicate@example.com', 'password456')).rejects.toThrow('Email already registered');
  });
});
```

**Validation Results:**
- Code coverage: 100% (8/8 branches)
- All edge cases handled
- Follows ESLint Airbnb style guide