Component specification toolkit for breaking software projects into discrete, buildable blocks. Create detailed specifications with interfaces, dependencies, test criteria, and effort estimates for Claude Code to build incrementally.
Decomposes software projects into discrete, buildable components with detailed specifications for incremental development.
/plugin marketplace add flight505/claude-project-planner/plugin install claude-project-planner@claude-project-plannerThis skill is limited to using the following tools:
Building blocks are discrete, independently buildable components that together form a complete software system. This skill helps you decompose projects into well-specified blocks that Claude Code can build incrementally, with clear interfaces, dependencies, and acceptance criteria.
This skill should be used when:
When documenting building blocks, always include diagrams.
Use the project-diagrams skill to generate:
python .claude/skills/project-diagrams/scripts/generate_schematic.py "diagram description" -o diagrams/output.png
| Type | Description | Examples |
|---|---|---|
| frontend | User interface components | Dashboard, Forms, Navigation |
| backend | Server-side services | Auth Service, API Gateway, Business Logic |
| infrastructure | Platform and DevOps | CI/CD, Monitoring, Database Setup |
| integration | External system connectors | Payment Gateway, Email Service, Third-party APIs |
| shared | Cross-cutting components | Logging, Configuration, Utilities |
building_block:
# Identity
name: "string - clear, descriptive name"
id: "string - unique identifier (e.g., BB-001)"
type: "frontend | backend | infrastructure | integration | shared"
# Description
description: "string - what this block does and why"
responsibilities:
- "string - specific responsibility 1"
- "string - specific responsibility 2"
# Dependencies
dependencies:
internal:
- block_id: "BB-XXX"
type: "required | optional"
interface: "interface name"
external:
- name: "PostgreSQL"
version: ">=14.0"
purpose: "Primary data storage"
# Interfaces
interfaces:
api_endpoints:
- method: "GET | POST | PUT | PATCH | DELETE"
path: "/api/v1/resource"
description: "What this endpoint does"
request_schema: "schema reference or inline"
response_schema: "schema reference or inline"
auth_required: true | false
events_published:
- name: "event.name"
description: "When this event is emitted"
payload_schema: "schema reference"
events_consumed:
- name: "event.name"
description: "How this block responds"
data_contracts:
- name: "Contract name"
description: "Data structure shared"
schema: "schema reference"
# Estimation
complexity: "S | M | L | XL"
estimated_hours: number
story_points: number
# Quality
test_criteria:
- "string - acceptance criterion 1"
- "string - acceptance criterion 2"
# Metadata
priority: "critical | high | medium | low"
sprint_assignment: "Sprint N"
owner: "string - responsible team/person"
| Complexity | Hours | Story Points | Characteristics |
|---|---|---|---|
| S (Small) | 4-8 | 1-2 | Single responsibility, minimal dependencies, straightforward implementation |
| M (Medium) | 16-24 | 3-5 | Multiple responsibilities, some dependencies, standard patterns |
| L (Large) | 32-48 | 8-13 | Complex logic, multiple dependencies, custom implementations |
| XL (Extra Large) | 48-80 | 13-21 | Highly complex, many dependencies, novel solutions needed |
Start with domain-driven decomposition:
For each domain, identify components:
Questions to ask:
For each component:
Create a dependency graph:
BB-001 (Auth) ← BB-002 (User Service)
↑
BB-003 (API Gateway)
↑
BB-004 (Frontend)
Dependency Rules:
For each block:
building_block:
name: "User Authentication Service"
id: "BB-001"
type: "backend"
description: |
Handles user authentication, authorization, and session management.
Supports email/password login and OAuth2 social providers.
responsibilities:
- "User registration with email verification"
- "Login/logout with session management"
- "JWT token generation and validation"
- "OAuth2 integration (Google, GitHub)"
- "Password reset flow"
- "Role-based access control"
dependencies:
internal:
- block_id: "BB-010"
type: "required"
interface: "Database Service"
external:
- name: "PostgreSQL"
version: ">=14.0"
purpose: "User credentials and sessions"
- name: "Redis"
version: ">=6.0"
purpose: "Session cache and rate limiting"
interfaces:
api_endpoints:
- method: "POST"
path: "/api/v1/auth/register"
description: "Register new user with email/password"
request_schema:
email: "string (email format)"
password: "string (min 8 chars)"
name: "string"
response_schema:
user_id: "uuid"
message: "string"
auth_required: false
- method: "POST"
path: "/api/v1/auth/login"
description: "Authenticate user and return tokens"
request_schema:
email: "string"
password: "string"
response_schema:
access_token: "string (JWT)"
refresh_token: "string"
expires_in: "number (seconds)"
auth_required: false
- method: "POST"
path: "/api/v1/auth/refresh"
description: "Refresh access token"
auth_required: true
- method: "POST"
path: "/api/v1/auth/logout"
description: "Invalidate session"
auth_required: true
- method: "GET"
path: "/api/v1/auth/me"
description: "Get current user profile"
auth_required: true
events_published:
- name: "user.registered"
description: "Emitted when new user completes registration"
payload_schema:
user_id: "uuid"
email: "string"
registered_at: "timestamp"
- name: "user.logged_in"
description: "Emitted on successful login"
payload_schema:
user_id: "uuid"
login_at: "timestamp"
method: "password | oauth"
complexity: "M"
estimated_hours: 24
story_points: 5
test_criteria:
- "User can register with valid email and password"
- "Registration fails with invalid email format"
- "Registration fails with weak password"
- "User can login with correct credentials"
- "Login fails with incorrect password (returns 401)"
- "User receives valid JWT token on login"
- "JWT token contains correct claims (user_id, roles)"
- "Token refresh works with valid refresh token"
- "Logout invalidates session"
- "Protected endpoints reject invalid tokens"
- "Rate limiting prevents brute force attacks"
priority: "critical"
sprint_assignment: "Sprint 1"
building_block:
name: "Dashboard UI"
id: "BB-020"
type: "frontend"
description: |
Main dashboard interface showing key metrics, recent activity,
and navigation to other features.
responsibilities:
- "Display key performance metrics"
- "Show recent user activity feed"
- "Provide navigation to features"
- "Handle responsive layout"
- "Manage loading and error states"
dependencies:
internal:
- block_id: "BB-001"
type: "required"
interface: "Auth Service (for user context)"
- block_id: "BB-005"
type: "required"
interface: "Metrics API"
- block_id: "BB-025"
type: "required"
interface: "Design System Components"
external:
- name: "React"
version: ">=18.0"
purpose: "UI framework"
- name: "TanStack Query"
version: ">=5.0"
purpose: "Data fetching and caching"
interfaces:
api_consumed:
- endpoint: "GET /api/v1/metrics/summary"
purpose: "Load dashboard metrics"
- endpoint: "GET /api/v1/activity/recent"
purpose: "Load activity feed"
components_exposed:
- name: "DashboardPage"
description: "Main dashboard route component"
- name: "MetricsWidget"
description: "Reusable metrics display widget"
complexity: "M"
estimated_hours: 20
story_points: 5
test_criteria:
- "Dashboard loads and displays metrics"
- "Activity feed shows recent items"
- "Loading state shown while fetching"
- "Error state shown on API failure"
- "Responsive layout works on mobile"
- "Navigation links work correctly"
- "Auto-refresh updates data periodically"
priority: "high"
sprint_assignment: "Sprint 2"
building_block:
name: "CI/CD Pipeline"
id: "BB-100"
type: "infrastructure"
description: |
Continuous integration and deployment pipeline using GitHub Actions.
Handles testing, building, and deploying to staging and production.
responsibilities:
- "Run tests on pull requests"
- "Build Docker images"
- "Push to container registry"
- "Deploy to staging automatically"
- "Deploy to production with approval"
- "Run database migrations"
dependencies:
external:
- name: "GitHub Actions"
purpose: "CI/CD platform"
- name: "Docker Hub / ECR"
purpose: "Container registry"
- name: "AWS ECS / Kubernetes"
purpose: "Deployment target"
interfaces:
triggers:
- event: "push to main"
action: "Deploy to staging"
- event: "release tag"
action: "Deploy to production"
- event: "pull request"
action: "Run tests"
outputs:
- name: "Docker images"
format: "project/service:version"
- name: "Test reports"
format: "JUnit XML"
- name: "Coverage reports"
format: "Cobertura XML"
complexity: "M"
estimated_hours: 16
story_points: 3
test_criteria:
- "Pipeline triggers on push to main"
- "Tests run and report results"
- "Build creates valid Docker image"
- "Image is pushed to registry"
- "Staging deployment succeeds"
- "Production requires manual approval"
- "Rollback mechanism works"
- "Secrets are not exposed in logs"
priority: "critical"
sprint_assignment: "Sprint 1"
Primary output file listing all blocks:
# Building Blocks Specification
# Project: [Project Name]
# Generated: [Date]
metadata:
project: "[Project Name]"
total_blocks: N
total_estimated_hours: N
version: "1.0.0"
building_blocks:
- name: "Block 1"
id: "BB-001"
# ... full specification
- name: "Block 2"
id: "BB-002"
# ... full specification
dependency_graph:
- from: "BB-002"
to: "BB-001"
type: "required"
- from: "BB-003"
to: "BB-001"
type: "required"
build_order:
- phase: 1
blocks: ["BB-001", "BB-100"]
- phase: 2
blocks: ["BB-002", "BB-003"]
- phase: 3
blocks: ["BB-020", "BB-021"]
For complex blocks, create detailed specs:
components/
├── building_blocks.yaml # Master list
├── component_specs/
│ ├── BB-001_auth_service.md # Detailed spec
│ ├── BB-002_user_service.md
│ └── BB-020_dashboard_ui.md
└── interfaces/
├── api_contracts.yaml # OpenAPI specs
└── event_contracts.yaml # Event schemas
Before completing building blocks specification:
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.