Initial commit
This commit is contained in:
Zhongwei Li
638
.claude/skills/project-planner/SKILL.md
Normal file
638
.claude/skills/project-planner/SKILL.md
Normal file
@@ -0,0 +1,638 @@
|
||||
---
|
||||
name: project-planner
|
||||
description: Transforms project ideas into structured documentation (overview + specifications). Use when starting new projects or when brief needs project-level planning with vision, features, and technical requirements.
|
||||
---
|
||||
|
||||
# Project Planner Skill
|
||||
|
||||
**Purpose**: Generate comprehensive project documentation from high-level descriptions.
|
||||
|
||||
**Trigger Words**: new project, project overview, project spec, technical requirements, project planning, architecture, system design
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision: Use Project Planning?
|
||||
|
||||
```python
|
||||
def needs_project_planning(context: dict) -> bool:
|
||||
"""Fast evaluation for project-level planning."""
|
||||
|
||||
# Indicators of project-level work
|
||||
project_indicators = [
|
||||
"new project", "project overview", "system design",
|
||||
"architecture", "technical requirements", "project spec",
|
||||
"build a", "create a", "develop a platform",
|
||||
"microservices", "full stack", "api + frontend"
|
||||
]
|
||||
|
||||
description = context.get("description", "").lower()
|
||||
return any(indicator in description for indicator in project_indicators)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
Generates TWO documents in `project-management/`:
|
||||
|
||||
### 1. PROJECT-OVERVIEW.md
|
||||
High-level vision and goals
|
||||
|
||||
### 2. SPECIFICATIONS.md
|
||||
Detailed technical requirements
|
||||
|
||||
---
|
||||
|
||||
## Document 1: PROJECT-OVERVIEW.md
|
||||
|
||||
### Template Structure
|
||||
|
||||
```markdown
|
||||
# {Project Name}
|
||||
|
||||
> {Tagline - one compelling sentence}
|
||||
|
||||
## Vision
|
||||
|
||||
{2-3 sentences describing the ultimate goal and impact}
|
||||
|
||||
## Goals
|
||||
|
||||
1. {Primary goal}
|
||||
2. {Secondary goal}
|
||||
3. {Tertiary goal}
|
||||
|
||||
## Key Features
|
||||
|
||||
- **{Feature 1}**: {Brief description}
|
||||
- **{Feature 2}**: {Brief description}
|
||||
- **{Feature 3}**: {Brief description}
|
||||
- **{Feature 4}**: {Brief description}
|
||||
- **{Feature 5}**: {Brief description}
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. **{Metric 1}**: {Target}
|
||||
2. **{Metric 2}**: {Target}
|
||||
3. **{Metric 3}**: {Target}
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Budget**: {If specified}
|
||||
- **Timeline**: {If specified}
|
||||
- **Technology**: {Required tech stack or limitations}
|
||||
- **Team**: {Team size/composition if known}
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- {What this project will NOT do}
|
||||
- {Features explicitly excluded}
|
||||
- {Future phases}
|
||||
```
|
||||
|
||||
### Example Output
|
||||
|
||||
```markdown
|
||||
# TaskFlow Pro
|
||||
|
||||
> Modern task management with AI-powered prioritization
|
||||
|
||||
## Vision
|
||||
|
||||
Build a task management platform that helps remote teams stay organized through intelligent prioritization, real-time collaboration, and seamless integrations with existing tools.
|
||||
|
||||
## Goals
|
||||
|
||||
1. Reduce task management overhead by 50%
|
||||
2. Enable real-time team collaboration
|
||||
3. Integrate with popular dev tools (GitHub, Jira, Slack)
|
||||
|
||||
## Key Features
|
||||
|
||||
- **AI Prioritization**: ML-based task ranking by urgency and impact
|
||||
- **Real-time Collaboration**: Live updates, comments, mentions
|
||||
- **Smart Integrations**: Auto-sync with GitHub issues, Jira tickets
|
||||
- **Custom Workflows**: Configurable pipelines per team
|
||||
- **Analytics Dashboard**: Team productivity insights
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. **User Adoption**: 1000 active users in 6 months
|
||||
2. **Performance**: <200ms API response time
|
||||
3. **Reliability**: 99.9% uptime
|
||||
|
||||
## Constraints
|
||||
|
||||
- Timeline: 6 months MVP
|
||||
- Technology: Python backend, React frontend, PostgreSQL
|
||||
- Team: 2 backend, 2 frontend, 1 ML engineer
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Mobile apps (Phase 2)
|
||||
- Video conferencing
|
||||
- Time tracking (separate product)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Document 2: SPECIFICATIONS.md
|
||||
|
||||
### Template Structure
|
||||
|
||||
```markdown
|
||||
# {Project Name} - Technical Specifications
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### Core Features
|
||||
|
||||
#### {Feature 1}
|
||||
- **Description**: {What it does}
|
||||
- **User Story**: As a {role}, I want {action} so that {benefit}
|
||||
- **Acceptance Criteria**:
|
||||
- [ ] {Criterion 1}
|
||||
- [ ] {Criterion 2}
|
||||
- [ ] {Criterion 3}
|
||||
|
||||
#### {Feature 2}
|
||||
{Repeat structure}
|
||||
|
||||
### User Flows
|
||||
|
||||
#### {Flow 1}: {Name}
|
||||
1. User {action}
|
||||
2. System {response}
|
||||
3. User {next action}
|
||||
4. Result: {outcome}
|
||||
|
||||
---
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
### Performance
|
||||
- API response time: <200ms (p95)
|
||||
- Page load time: <1s
|
||||
- Concurrent users: 10,000+
|
||||
- Database queries: <50ms
|
||||
|
||||
### Security
|
||||
- Authentication: OAuth2 + JWT
|
||||
- Authorization: Role-based access control (RBAC)
|
||||
- Data encryption: AES-256 at rest, TLS 1.3 in transit
|
||||
- Rate limiting: 100 req/min per user
|
||||
|
||||
### Reliability
|
||||
- Uptime: 99.9% SLA
|
||||
- Backup frequency: Daily
|
||||
- Recovery time: <1 hour (RTO)
|
||||
- Data loss: <5 minutes (RPO)
|
||||
|
||||
### Scalability
|
||||
- Horizontal scaling: Auto-scale based on load
|
||||
- Database: Read replicas for queries
|
||||
- Cache: Redis for hot data
|
||||
- CDN: Static assets
|
||||
|
||||
---
|
||||
|
||||
## API Contracts
|
||||
|
||||
### Authentication API
|
||||
|
||||
#### POST /api/auth/login
|
||||
```json
|
||||
// Request
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "hashed_password"
|
||||
}
|
||||
|
||||
// Response (200 OK)
|
||||
{
|
||||
"token": "jwt_token_here",
|
||||
"user": {
|
||||
"id": "user_123",
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe"
|
||||
}
|
||||
}
|
||||
|
||||
// Error (401 Unauthorized)
|
||||
{
|
||||
"error": "Invalid credentials"
|
||||
}
|
||||
```
|
||||
|
||||
#### POST /api/auth/logout
|
||||
{Repeat structure for each endpoint}
|
||||
|
||||
### Tasks API
|
||||
|
||||
#### GET /api/tasks
|
||||
```json
|
||||
// Query params: ?page=1&per_page=50&status=active
|
||||
// Response (200 OK)
|
||||
{
|
||||
"tasks": [
|
||||
{
|
||||
"id": "task_123",
|
||||
"title": "Fix bug in auth",
|
||||
"status": "active",
|
||||
"priority": "high",
|
||||
"assignee": "user_456",
|
||||
"created_at": "2025-10-30T10:00:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"per_page": 50,
|
||||
"total": 150
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
{Continue for all major endpoints}
|
||||
|
||||
---
|
||||
|
||||
## Data Models
|
||||
|
||||
### User
|
||||
```python
|
||||
class User:
|
||||
id: str (UUID)
|
||||
email: str (unique, indexed)
|
||||
password_hash: str
|
||||
name: str
|
||||
role: Enum['admin', 'member', 'viewer']
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
last_login: datetime | None
|
||||
```
|
||||
|
||||
### Task
|
||||
```python
|
||||
class Task:
|
||||
id: str (UUID)
|
||||
title: str (max 200 chars)
|
||||
description: str | None
|
||||
status: Enum['backlog', 'active', 'completed']
|
||||
priority: Enum['low', 'medium', 'high', 'urgent']
|
||||
assignee_id: str | None (FK -> User.id)
|
||||
project_id: str (FK -> Project.id)
|
||||
due_date: datetime | None
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
```
|
||||
|
||||
{Continue for all major models}
|
||||
|
||||
---
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Components
|
||||
- **API Gateway**: Kong/NGINX for routing and rate limiting
|
||||
- **Backend Services**: FastAPI/Django microservices
|
||||
- **Database**: PostgreSQL (primary), Redis (cache)
|
||||
- **Message Queue**: RabbitMQ for async tasks
|
||||
- **Storage**: S3 for file uploads
|
||||
- **Monitoring**: Prometheus + Grafana
|
||||
|
||||
### Deployment
|
||||
- **Infrastructure**: AWS/GCP Kubernetes
|
||||
- **CI/CD**: GitHub Actions
|
||||
- **Environments**: dev, staging, production
|
||||
- **Rollback**: Blue-green deployment
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Backend
|
||||
- Python 3.11+
|
||||
- FastAPI or Django REST Framework
|
||||
- SQLAlchemy or Django ORM
|
||||
- Celery for background tasks
|
||||
- pytest for testing
|
||||
|
||||
### Frontend
|
||||
- React 18+ or Vue 3+
|
||||
- TypeScript
|
||||
- Tailwind CSS or Material-UI
|
||||
- Axios for API calls
|
||||
- Vitest or Jest for testing
|
||||
|
||||
### Infrastructure
|
||||
- Docker + Docker Compose
|
||||
- Kubernetes (production)
|
||||
- PostgreSQL 15+
|
||||
- Redis 7+
|
||||
- NGINX or Caddy
|
||||
|
||||
---
|
||||
|
||||
## Development Phases
|
||||
|
||||
### Phase 1: MVP (Months 1-3)
|
||||
- [ ] User authentication
|
||||
- [ ] Basic task CRUD
|
||||
- [ ] Simple prioritization
|
||||
- [ ] API foundation
|
||||
|
||||
### Phase 2: Collaboration (Months 4-5)
|
||||
- [ ] Real-time updates (WebSocket)
|
||||
- [ ] Comments and mentions
|
||||
- [ ] Team management
|
||||
|
||||
### Phase 3: Integrations (Month 6)
|
||||
- [ ] GitHub integration
|
||||
- [ ] Jira sync
|
||||
- [ ] Slack notifications
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
- Coverage: >80%
|
||||
- All business logic functions
|
||||
- Mock external dependencies
|
||||
|
||||
### Integration Tests
|
||||
- API endpoint testing
|
||||
- Database transactions
|
||||
- Authentication flows
|
||||
|
||||
### E2E Tests
|
||||
- Critical user flows
|
||||
- Payment processing (if applicable)
|
||||
- Admin workflows
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### OWASP Top 10 Coverage
|
||||
1. **Injection**: Parameterized queries, input validation
|
||||
2. **Broken Auth**: JWT with refresh tokens, secure session management
|
||||
3. **Sensitive Data**: Encryption at rest and in transit
|
||||
4. **XXE**: Disable XML external entities
|
||||
5. **Broken Access Control**: RBAC enforcement
|
||||
6. **Security Misconfiguration**: Secure defaults, regular audits
|
||||
7. **XSS**: Output escaping, CSP headers
|
||||
8. **Insecure Deserialization**: Validate all input
|
||||
9. **Known Vulnerabilities**: Dependency scanning (Snyk, Dependabot)
|
||||
10. **Insufficient Logging**: Audit logs for sensitive actions
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
### Metrics
|
||||
- Request rate, error rate, latency (RED method)
|
||||
- Database connection pool usage
|
||||
- Cache hit/miss ratio
|
||||
- Background job queue length
|
||||
|
||||
### Logging
|
||||
- Structured JSON logs
|
||||
- Centralized logging (ELK stack or CloudWatch)
|
||||
- Log levels: DEBUG (dev), INFO (staging), WARN/ERROR (prod)
|
||||
|
||||
### Alerting
|
||||
- Error rate >5% (P1)
|
||||
- API latency >500ms (P2)
|
||||
- Database connections >80% (P2)
|
||||
- Disk usage >90% (P1)
|
||||
|
||||
---
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
- [ ] API documentation (OpenAPI/Swagger)
|
||||
- [ ] Setup guide (README.md)
|
||||
- [ ] Architecture diagrams
|
||||
- [ ] Deployment runbook
|
||||
- [ ] Troubleshooting guide
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Generation Process
|
||||
|
||||
### Step 1: Extract Project Context
|
||||
```python
|
||||
def extract_project_info(prompt: str) -> dict:
|
||||
"""Parse project description for key details."""
|
||||
|
||||
info = {
|
||||
"name": None,
|
||||
"description": prompt,
|
||||
"features": [],
|
||||
"tech_stack": [],
|
||||
"constraints": {},
|
||||
"goals": []
|
||||
}
|
||||
|
||||
# Extract from prompt:
|
||||
# - Project name (if mentioned)
|
||||
# - Desired features
|
||||
# - Technology preferences
|
||||
# - Timeline/budget constraints
|
||||
# - Success metrics
|
||||
|
||||
return info
|
||||
```
|
||||
|
||||
### Step 2: Apply Output Style
|
||||
Use `output-style-selector` to determine:
|
||||
- **PROJECT-OVERVIEW.md**: Bullet-points, concise
|
||||
- **SPECIFICATIONS.md**: Table-based for API contracts, YAML-structured for models
|
||||
|
||||
### Step 3: Generate Documents
|
||||
1. Create `project-management/` directory if needed
|
||||
2. Write PROJECT-OVERVIEW.md (vision-focused)
|
||||
3. Write SPECIFICATIONS.md (technical details)
|
||||
4. Validate completeness
|
||||
|
||||
### Step 4: Validation Checklist
|
||||
```markdown
|
||||
## Generated Documents Validation
|
||||
|
||||
PROJECT-OVERVIEW.md:
|
||||
- [ ] Project name and tagline present
|
||||
- [ ] Vision statement (2-3 sentences)
|
||||
- [ ] 3+ goals defined
|
||||
- [ ] 5-10 key features listed
|
||||
- [ ] Success criteria measurable
|
||||
- [ ] Constraints documented
|
||||
- [ ] Out-of-scope items listed
|
||||
|
||||
SPECIFICATIONS.md:
|
||||
- [ ] Functional requirements detailed
|
||||
- [ ] Non-functional requirements (perf, security, reliability)
|
||||
- [ ] API contracts with examples (if applicable)
|
||||
- [ ] Data models defined
|
||||
- [ ] Architecture overview
|
||||
- [ ] Dependencies listed
|
||||
- [ ] Development phases outlined
|
||||
- [ ] Testing strategy included
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Commands
|
||||
|
||||
### With `/lazy plan`
|
||||
```bash
|
||||
# Generate project docs first
|
||||
/lazy plan --project "Build AI-powered task manager"
|
||||
|
||||
→ project-planner skill triggers
|
||||
→ Generates PROJECT-OVERVIEW.md + SPECIFICATIONS.md
|
||||
→ Then creates first user story from specifications
|
||||
|
||||
# Or start from enhanced prompt
|
||||
/lazy plan --file enhanced_prompt.md
|
||||
|
||||
→ Detects project-level scope
|
||||
→ Runs project-planner
|
||||
→ Creates foundational docs
|
||||
→ Proceeds with story creation
|
||||
```
|
||||
|
||||
### With `/lazy code`
|
||||
```bash
|
||||
# Reference specifications during implementation
|
||||
/lazy code @US-3.4.md
|
||||
|
||||
→ context-packer loads SPECIFICATIONS.md
|
||||
→ API contracts and data models available
|
||||
→ Implementation follows spec
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What This Skill Does NOT Do
|
||||
|
||||
❌ Generate actual code (that's for `coder` agent)
|
||||
❌ Create user stories (that's for `project-manager` agent)
|
||||
❌ Make architectural decisions (provides template, you decide)
|
||||
❌ Replace technical design documents (TDDs)
|
||||
|
||||
✅ **DOES**: Create structured foundation documents for new projects.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
```bash
|
||||
# Minimal specs (faster, less detail)
|
||||
export LAZYDEV_PROJECT_SPEC_MINIMAL=1
|
||||
|
||||
# Skip API contracts (non-API projects)
|
||||
export LAZYDEV_PROJECT_NO_API=1
|
||||
|
||||
# Focus on specific aspects
|
||||
export LAZYDEV_PROJECT_FOCUS="security,performance"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips for Effective Project Planning
|
||||
|
||||
### For PROJECT-OVERVIEW.md
|
||||
1. **Vision**: Think big picture - why does this exist?
|
||||
2. **Goals**: Limit to 3-5 measurable outcomes
|
||||
3. **Features**: High-level only (not task-level details)
|
||||
4. **Success Criteria**: Must be measurable (numbers, percentages)
|
||||
|
||||
### For SPECIFICATIONS.md
|
||||
1. **API Contracts**: Start with authentication and core resources
|
||||
2. **Data Models**: Include relationships and constraints
|
||||
3. **Non-Functional**: Don't skip - these prevent tech debt
|
||||
4. **Security**: Reference OWASP Top 10 coverage
|
||||
5. **Phases**: Break into 2-3 month chunks maximum
|
||||
|
||||
### Best Practices
|
||||
- **Keep PROJECT-OVERVIEW under 2 pages**: Executive summary only
|
||||
- **SPECIFICATIONS can be longer**: This is the source of truth
|
||||
- **Update specs as you learn**: Living documents
|
||||
- **Version control both**: Track changes over time
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Scenarios
|
||||
|
||||
### Scenario 1: New Greenfield Project
|
||||
```
|
||||
User: "I want to build a real-time chat platform with video calls"
|
||||
|
||||
→ project-planner triggers
|
||||
→ Generates:
|
||||
- PROJECT-OVERVIEW.md (vision: modern communication platform)
|
||||
- SPECIFICATIONS.md (WebSocket APIs, video streaming, etc.)
|
||||
→ Ready for user story creation
|
||||
```
|
||||
|
||||
### Scenario 2: From Enhanced Prompt
|
||||
```
|
||||
User: /lazy plan --file enhanced_prompt.md
|
||||
# enhanced_prompt contains: detailed project requirements, tech stack, timeline
|
||||
|
||||
→ project-planner parses prompt
|
||||
→ Extracts structured information
|
||||
→ Generates both documents
|
||||
→ Proceeds to first user story
|
||||
```
|
||||
|
||||
### Scenario 3: Partial Information
|
||||
```
|
||||
User: "Build a task manager, not sure about details yet"
|
||||
|
||||
→ project-planner generates template
|
||||
→ Marks sections as [TODO: Specify...]
|
||||
→ User fills in gaps incrementally
|
||||
→ Re-generate or update manually
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Format (Completion)
|
||||
|
||||
```markdown
|
||||
## Project Planning Complete
|
||||
|
||||
**Documents Generated**:
|
||||
|
||||
1. **PROJECT-OVERVIEW.md** (2.4KB)
|
||||
- Project: TaskFlow Pro
|
||||
- Vision: Modern task management with AI
|
||||
- Features: 5 key features defined
|
||||
- Success criteria: 3 measurable metrics
|
||||
|
||||
2. **SPECIFICATIONS.md** (8.1KB)
|
||||
- Functional requirements: 5 core features detailed
|
||||
- API contracts: 12 endpoints documented
|
||||
- Data models: 6 models defined
|
||||
- Architecture: Microservices with Kubernetes
|
||||
- Development phases: 3 phases over 6 months
|
||||
|
||||
**Location**: `./project-management/`
|
||||
|
||||
**Next Steps**:
|
||||
1. Review and refine generated documents
|
||||
2. Run: `/lazy plan "First user story description"`
|
||||
3. Begin implementation with `/lazy code`
|
||||
|
||||
**Estimated Setup Time**: 15-20 minutes to review/customize
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Output Size**: 10-15KB total (both documents)
|
||||
**Generation Time**: ~30 seconds
|
||||
Reference in New Issue
Block a user