zhongwei/gh-henkisdabro-wookstar-claude-code-plugins-productivity-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:32:48 +08:00
commit 9997176040
24 changed files with 2371 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

400
skills/prp-generator/SKILL.md Normal file
View File

@@ -0,0 +1,400 @@
---
name: prp-generator
description: Generate comprehensive Product Requirement Plans (PRPs) for feature implementation with thorough codebase analysis and external research. Use when the user requests a PRP, PRD, or detailed implementation plan for a new feature. Conducts systematic research, identifies patterns, and creates executable validation gates for one-pass implementation success.
---
# PRP Generator
## Overview
This skill generates comprehensive Product Requirement Plans (PRPs) that enable AI agents to implement features in a single pass with high success rates. The skill combines systematic codebase analysis with external research to create detailed, context-rich implementation blueprints.
## When to Use This Skill
Invoke this skill when:
- User requests a PRP or PRD (Product Requirement Plan/Document)
- User wants a detailed implementation plan for a new feature
- User asks to "plan out" or "design" a complex feature
- Beginning a significant feature development that would benefit from structured planning
- User provides a feature description file and asks for implementation guidance
## Core Principle
**Context is Everything**: The AI agent implementing your PRP only receives:
1. The PRP content you create
2. Training data knowledge
3. Access to the codebase
4. WebSearch capabilities
Therefore, your PRP must be self-contained with all necessary context, specific references, and executable validation gates.
## Workflow
### Phase 1: Understanding the Feature
1. **Read the Feature Request**
- If user provides a feature file path, read it completely
- If user provides verbal description, clarify requirements by asking:
- What is the user trying to accomplish?
- What are the acceptance criteria?
- Are there any specific constraints or requirements?
- Identify the core problem being solved
2. **Clarify Ambiguities**
- Use AskUserQuestion tool for any unclear requirements
- Confirm technology stack assumptions
- Verify integration points
- Ask about specific patterns to follow if not obvious
### Phase 2: Codebase Analysis (Mandatory)
**Goal**: Understand existing patterns, conventions, and integration points
Refer to `references/research_methodology.md` for detailed guidance, but the core steps are:
1. **Search for Similar Features**
```
Use Grep to search for:
- Similar component names
- Similar functionality keywords
- Similar UI patterns
- Similar API endpoints
```
Document findings with:
- Exact file paths and line numbers
- Code snippets showing patterns
- Relevance to new feature
- Necessary adaptations
2. **Identify Architectural Patterns**
- Directory structure conventions
- Component organization patterns
- State management approach
- API structure patterns
- Routing patterns (if applicable)
Example findings:
```
Pattern: Feature-based directory structure
Location: src/features/
Application: Create src/features/[new-feature]/
```
3. **Document Coding Conventions**
- TypeScript usage patterns (interfaces vs types, strict mode)
- Component patterns (FC vs function, default vs named exports)
- Styling approach (CSS modules, styled-components, Tailwind)
- Import ordering and organization
- Function and variable naming
- Comment style
Example:
```
Convention: Named exports for all components
Example: export function UserProfile() { ... }
Found in: src/components/*.tsx
```
4. **Study Test Patterns**
- Test framework and version
- Test file naming and location
- Mock strategies
- Coverage expectations
- Example test to mirror
Document:
```
Framework: Vitest + @testing-library/react
Pattern: Co-located tests with *.test.tsx
Example: src/components/Button/Button.test.tsx
Mock Strategy: Use vi.fn() for functions, MSW for HTTP
```
5. **Check Project Configuration**
- Review `package.json` for dependencies and scripts
- Check `tsconfig.json` for TypeScript settings
- Review build configuration (vite.config.ts, etc.)
- Note path aliases and special configurations
Document:
```
Build Tool: Vite 5.x
Path Aliases: '@/' → 'src/', '@components/' → 'src/components/'
TypeScript: Strict mode enabled
```
### Phase 3: External Research (Mandatory)
**Goal**: Find best practices, documentation, examples, and gotchas
Refer to `references/research_methodology.md` for detailed guidance, but the core steps are:
1. **Search for Library Documentation**
- Go to official documentation for any libraries being used
- Find the SPECIFIC version in package.json
- Document exact URLs to relevant sections
- Note version-specific features or changes
Example output:
```
Library: @tanstack/react-query
Version: 5.28.0 (from package.json)
Docs: https://tanstack.com/query/latest/docs/react/overview
Key Sections:
- Queries: https://tanstack.com/query/latest/docs/react/guides/queries
- Mutations: https://tanstack.com/query/latest/docs/react/guides/mutations
Gotchas:
- Query keys must be arrays
- Automatic refetching on window focus
- Default staleTime is 0
```
2. **Find Implementation Examples**
- Search GitHub for similar implementations
- Look for StackOverflow solutions (recent, highly-voted)
- Find blog posts from reputable sources
- Check official example repositories
Document:
```
Example: Form validation with React Hook Form + Zod
Source: https://github.com/react-hook-form/react-hook-form/tree/master/examples/V7/zodResolver
Relevance: Shows exact integration pattern needed
Key Takeaway: Use zodResolver from @hookform/resolvers
```
3. **Research Best Practices**
- Search for "[technology] best practices [current year]"
- Look for common pitfalls and gotchas
- Research performance considerations
- Check security implications (OWASP guidelines)
Document:
```
Practice: Input sanitization for user content
Why: Prevent XSS attacks
How: Use DOMPurify before rendering HTML
Reference: https://owasp.org/www-community/attacks/xss/
Warning: NEVER use dangerouslySetInnerHTML without sanitization
```
4. **Performance & Security Research**
- Bundle size implications of new dependencies
- Runtime performance patterns
- Security vulnerabilities to avoid
- Accessibility considerations
Document specific URLs and recommendations
### Phase 4: Ultra-Thinking (Critical)
**STOP AND THINK DEEPLY BEFORE WRITING THE PRP**
This is the most important phase. Spend significant time analyzing:
1. **Integration Analysis**
- How does the new feature connect to existing code?
- What existing patterns should be followed?
- Where might conflicts arise?
- What files will need to be created vs modified?
2. **Implementation Path Planning**
- What is the logical order of implementation steps?
- What are the dependencies between steps?
- Where are the potential roadblocks?
- What edge cases need handling?
3. **Validation Strategy**
- What can be validated automatically?
- What requires manual testing?
- How can the implementer verify each step?
- What are the success criteria?
4. **Context Completeness Check**
Ask yourself:
- Could an AI agent implement this without asking questions?
- Are all integration points documented?
- Are all necessary examples included?
- Are gotchas and warnings clearly stated?
- Are validation gates executable?
- Is the implementation path clear and logical?
5. **Quality Assessment**
- Is this PRP comprehensive enough for one-pass implementation?
- What could cause the implementation to fail?
- What additional context would be helpful?
- Are all assumptions documented?
### Phase 5: Generate the PRP
Use the template from `assets/prp_template.md` as the base structure, and populate it with:
1. **Metadata Section**
- Feature name
- Timeline estimate
- Confidence score (1-10)
- Creation date
2. **Executive Summary**
- 2-3 sentences describing the feature
- Core value proposition
3. **Research Findings**
- Codebase analysis results (with file:line references)
- External research (with specific URLs and sections)
- Document EVERYTHING discovered in Phase 2 and 3
4. **Technical Specification**
- Architecture overview
- Component breakdown
- Data models
- API endpoints (if applicable)
5. **Implementation Blueprint**
- Prerequisites
- Step-by-step implementation (with pseudocode)
- File-by-file changes
- Reference patterns from codebase
- Error handling strategy
- Edge cases
6. **Testing Strategy**
- Unit test approach
- Integration test approach
- Manual testing checklist
7. **Validation Gates**
Must be EXECUTABLE commands:
```bash
# Type checking
npm run type-check
# Linting
npm run lint
# Tests
npm run test
# Build
npm run build
```
8. **Success Criteria**
- Clear, measurable completion criteria
- Checklist format
### Phase 6: Quality Scoring
Score the PRP on a scale of 1-10 for one-pass implementation success:
**Scoring Criteria**:
- **9-10**: Exceptionally detailed, all context included, clear path, executable gates
- **7-8**: Very good, minor gaps, mostly clear implementation path
- **5-6**: Adequate, some ambiguity, may require clarification
- **3-4**: Incomplete research, missing context, unclear path
- **1-2**: Insufficient for implementation
**If score is below 7**: Go back and improve the PRP before delivering it.
### Phase 7: Save and Deliver
1. **Determine Feature Name**
- Use kebab-case
- Be descriptive but concise
- Example: "user-authentication", "dark-mode-toggle", "data-export"
2. **Save the PRP**
```
Save to: PRPs/[feature-name].md
```
If PRPs directory doesn't exist, create it:
```bash
mkdir -p PRPs
```
3. **Deliver Summary to User**
Provide:
- Brief summary of the feature
- Location of saved PRP
- Confidence score and rationale
- Next steps recommendation
## Quality Checklist
Before delivering the PRP, verify:
- [ ] Feature requirements fully understood
- [ ] Codebase analysis completed with specific file references
- [ ] External research completed with URLs and versions
- [ ] All similar patterns identified and documented
- [ ] Coding conventions documented
- [ ] Test patterns identified
- [ ] Implementation steps clearly defined
- [ ] Validation gates are executable (not pseudo-code)
- [ ] Error handling strategy documented
- [ ] Edge cases identified
- [ ] Success criteria defined
- [ ] Confidence score 7+ (if not, improve the PRP)
- [ ] No assumptions left undocumented
- [ ] Integration points clearly identified
- [ ] PRP saved to correct location
## Common Pitfalls to Avoid
1. **Vague References**
- ❌ "There's a similar component somewhere"
- ✅ "See UserProfile at src/components/UserProfile.tsx:45-67"
2. **Missing Version Information**
- ❌ "Use React Query"
- ✅ "Use @tanstack/react-query v5.28.0"
3. **Non-Executable Validation Gates**
- ❌ "Run tests and make sure they pass"
- ✅ "npm run test && npm run build"
4. **Generic Best Practices**
- ❌ "Follow React best practices"
- ✅ "Use named exports (see src/components/Button.tsx:1)"
5. **Incomplete Research**
- ❌ Skipping codebase analysis
- ✅ Thoroughly document existing patterns
6. **Missing Gotchas**
- ❌ Assuming smooth implementation
- ✅ Document known issues and edge cases
## Example Usage
**User Request**:
> "Create a PRP for adding dark mode support to the application"
**Your Response**:
1. Clarify: "Should dark mode preference persist across sessions? Should it respect system preferences?"
2. Research codebase for theme-related code
3. Research external resources (dark mode best practices, library options)
4. Ultra-think about implementation approach
5. Generate comprehensive PRP using template
6. Score the PRP
7. Save to `PRPs/dark-mode-support.md`
8. Deliver summary with confidence score
## Resources
### Template
- `assets/prp_template.md` - Base template for all PRPs
### References
- `references/research_methodology.md` - Detailed research guidance and best practices
## Notes
- **Research is mandatory**: Never skip codebase or external research
- **Be specific**: Always include file paths, line numbers, URLs, versions
- **Think deeply**: Phase 4 (Ultra-Thinking) is critical for success
- **Validate everything**: All validation gates must be executable
- **Score honestly**: If confidence is below 7, improve the PRP
- **Context is king**: The implementer only has what you put in the PRP

316
skills/prp-generator/assets/prp_template.md Normal file
View File

@@ -0,0 +1,316 @@
# Product Requirement Plan: [Feature Name]
## Metadata
- **Feature**: [Feature name]
- **Target Completion**: [Timeline estimate]
- **Confidence Score**: [1-10] - Likelihood of one-pass implementation success
- **Created**: [Date]
## Executive Summary
[2-3 sentences describing what this feature does and why it's valuable]
## Research Findings
### Codebase Analysis
#### Similar Patterns Found
[List similar features or patterns discovered in the codebase with file references]
- **Pattern**: [Pattern name]
- **Location**: `path/to/file.ts:line`
- **Description**: [What this pattern does]
- **Relevance**: [Why this is useful for the current feature]
#### Existing Conventions
[List coding conventions, architectural patterns, and style guidelines to follow]
- **Convention**: [Convention name]
- **Example**: [Code snippet or file reference]
- **Application**: [How to apply this to the new feature]
#### Test Patterns
[Document existing test patterns and validation approaches]
- **Test Framework**: [Framework name and version]
- **Pattern**: [Test pattern to follow]
- **Location**: `path/to/test.spec.ts`
### External Research
#### Documentation References
[List all relevant documentation with specific URLs and sections]
- **Resource**: [Library/Framework name]
- **URL**: [Specific URL to docs]
- **Key Sections**: [Relevant sections to read]
- **Version**: [Specific version]
- **Gotchas**: [Known issues or quirks]
#### Implementation Examples
[List real-world examples and references]
- **Example**: [Title/Description]
- **Source**: [GitHub/StackOverflow/Blog URL]
- **Relevance**: [What to learn from this]
- **Cautions**: [What to avoid]
#### Best Practices
[Document industry best practices and common pitfalls]
- **Practice**: [Best practice name]
- **Why**: [Rationale]
- **How**: [Implementation approach]
- **Warning**: [What to avoid]
## Technical Specification
### Architecture Overview
[High-level architecture diagram or description]
```
[ASCII diagram or description of component interactions]
```
### Component Breakdown
#### Component 1: [Name]
- **Purpose**: [What this component does]
- **Location**: `path/to/component`
- **Dependencies**: [List dependencies]
- **Interface**: [API or props interface]
#### Component 2: [Name]
[Repeat for each major component]
### Data Models
[Define all data structures, types, and schemas]
```typescript
// Example: Define interfaces/types
interface FeatureData {
// ...
}
```
### API Endpoints (if applicable)
[Document any new API endpoints]
- **Endpoint**: `POST /api/feature`
- **Purpose**: [What it does]
- **Request**: [Request schema]
- **Response**: [Response schema]
- **Authentication**: [Auth requirements]
## Implementation Blueprint
### Prerequisites
[List any setup steps, dependencies to install, or environment configuration needed]
1. [Prerequisite 1]
2. [Prerequisite 2]
### Implementation Steps (in order)
#### Step 1: [Step Name]
**Goal**: [What this step accomplishes]
**Pseudocode Approach**:
```
// High-level pseudocode showing the approach
function stepOne() {
// ...
}
```
**Files to Create/Modify**:
- `path/to/file1.ts` - [What changes]
- `path/to/file2.ts` - [What changes]
**Reference Pattern**: See `existing/pattern/file.ts:123` for similar implementation
**Validation**: [How to verify this step works]
#### Step 2: [Step Name]
[Repeat for each implementation step]
### Error Handling Strategy
[Document how errors should be handled]
- **Client-side errors**: [Approach]
- **Server-side errors**: [Approach]
- **Validation errors**: [Approach]
- **Network errors**: [Approach]
### Edge Cases
[List all edge cases to handle]
1. **Edge Case**: [Description]
- **Solution**: [How to handle]
## Testing Strategy
### Unit Tests
[Describe unit test approach]
- **Coverage Target**: [Percentage or scope]
- **Key Test Cases**: [List critical test scenarios]
- **Mock Strategy**: [What to mock and why]
### Integration Tests
[Describe integration test approach]
- **Test Scenarios**: [List integration test cases]
- **Setup Required**: [Test environment setup]
### Manual Testing Checklist
- [ ] [Test scenario 1]
- [ ] [Test scenario 2]
- [ ] [Edge case 1]
- [ ] [Edge case 2]
## Validation Gates
### Pre-Implementation Validation
```bash
# Ensure development environment is ready
[Commands to verify environment setup]
```
### During Implementation Validation
```bash
# Type checking
npm run type-check
# Linting
npm run lint
# Unit tests (watch mode during development)
npm run test:watch
```
### Post-Implementation Validation
```bash
# Full test suite
npm run test
# Type checking
npm run type-check
# Linting
npm run lint
# Build verification
npm run build
# E2E tests (if applicable)
npm run test:e2e
```
### Manual Validation Steps
1. [Manual test step 1]
2. [Manual test step 2]
3. [Verify in browser/UI]
## Dependencies
### New Dependencies (if any)
```json
{
"dependencies": {
"package-name": "^version"
},
"devDependencies": {
"test-package": "^version"
}
}
```
**Justification**: [Why each dependency is needed]
### Version Compatibility
- **Node**: [Version requirement]
- **Framework**: [Version requirement]
- **Other**: [Version requirements]
## Migration & Rollout
### Database Migrations (if applicable)
[Document any database schema changes]
### Feature Flags (if applicable)
[Document feature flag strategy]
### Rollout Plan
1. [Rollout step 1]
2. [Rollout step 2]
## Success Criteria
- [ ] All validation gates pass
- [ ] All test cases pass (unit, integration, manual)
- [ ] No TypeScript errors
- [ ] No linting errors
- [ ] Build succeeds
- [ ] Feature works as specified
- [ ] Edge cases handled
- [ ] Error handling implemented
- [ ] Code follows existing conventions
- [ ] Documentation updated
## Known Limitations
[Document any known limitations or future enhancements]
## References
### Internal Documentation
- [Link to internal docs]
### External Resources
- [Link to external resources used during research]
## Appendix
### Code Snippets from Research
[Include any useful code snippets discovered during research]
```typescript
// Example from existing codebase
```
### Additional Notes
[Any additional context that doesn't fit elsewhere]

334
skills/prp-generator/references/research_methodology.md Normal file
View File

@@ -0,0 +1,334 @@
# Research Methodology for PRP Generation
This document provides detailed guidance on conducting thorough research for creating comprehensive Product Requirement Plans.
## Research Philosophy
The AI agent implementing the PRP only receives:
1. The context you include in the PRP
2. Their training data knowledge
3. Access to the codebase
4. WebSearch capabilities
Therefore, your research findings MUST be:
- **Comprehensive**: Cover all aspects of implementation
- **Specific**: Include exact URLs, file paths, line numbers
- **Actionable**: Provide concrete examples and patterns
- **Complete**: Assume the implementer won't have your conversation context
## Codebase Analysis Process
### 1. Find Similar Features
**Goal**: Identify existing implementations that solve similar problems
**Approach**:
```bash
# Search for similar feature keywords
# Use Grep tool with relevant patterns
# Look for:
- Similar UI components
- Similar API endpoints
- Similar data models
- Similar business logic
```
**What to Document**:
- Exact file paths with line numbers (e.g., `src/components/UserProfile.tsx:45-67`)
- Code snippets showing the pattern
- Why this pattern is relevant
- Any modifications needed
**Example**:
```
Found: User authentication flow in `src/auth/AuthProvider.tsx:23-89`
Pattern: Context provider with useAuth hook
Relevance: Similar state management approach needed for feature X
Adaptation: Will need to add Y and Z properties
```
### 2. Identify Architectural Patterns
**Goal**: Understand how the codebase is structured
**Look for**:
- Directory structure conventions
- File naming patterns
- Component organization
- State management approach (Redux, Context, Zustand, etc.)
- API structure patterns
- Database access patterns
- Error handling patterns
**What to Document**:
```
Pattern: Feature-based directory structure
Example: src/features/authentication/
Application: Create src/features/[new-feature]/ with:
- components/
- hooks/
- types/
- api/
- tests/
```
### 3. Analyze Coding Conventions
**Goal**: Ensure consistency with existing codebase
**Check**:
- TypeScript usage (strict mode? interfaces vs types?)
- Component patterns (FC vs function? default vs named exports?)
- Styling approach (CSS modules, styled-components, Tailwind?)
- Import ordering
- Comment style
- Function naming (camelCase, descriptive names)
**What to Document**:
```
Convention: Named exports for all components
Example: export function UserProfile() { ... }
Reasoning: Easier refactoring and better IDE support
```
### 4. Study Test Patterns
**Goal**: Write tests that match existing patterns
**Investigate**:
- Test framework (Jest, Vitest, etc.)
- Testing library usage (@testing-library/react?)
- Test file naming (`*.test.ts` or `*.spec.ts`?)
- Test organization (co-located or separate test directory?)
- Mock patterns
- Test coverage expectations
**What to Document**:
```
Pattern: Co-located tests with *.test.tsx suffix
Framework: Vitest + @testing-library/react
Example: src/components/Button.test.tsx
Approach: Test user interactions, not implementation details
Mock Strategy: Use vi.fn() for callbacks, MSW for API calls
```
### 5. Check Configuration Files
**Goal**: Understand build, lint, and tooling setup
**Review**:
- `package.json` - scripts and dependencies
- `tsconfig.json` - TypeScript configuration
- `vite.config.ts` or `webpack.config.js` - build setup
- `.eslintrc` - linting rules
- `.prettierrc` - formatting rules
**What to Document**:
```
TypeScript: Strict mode enabled
Build: Vite with React plugin
Path Aliases: '@/' maps to 'src/'
Must use: Import type syntax for type-only imports
```
## External Research Process
### 1. Library Documentation
**When to Search**:
- Using a new library or framework feature
- Integrating third-party services
- Implementing complex functionality
**How to Search**:
1. Go directly to official documentation
2. Search for the specific version being used
3. Look for:
- Getting started guides
- API references
- Examples
- Migration guides
- Known issues
**What to Document**:
```
Library: @tanstack/react-query v5
URL: https://tanstack.com/query/latest/docs/react/guides/queries
Key Sections:
- Queries: https://tanstack.com/query/latest/docs/react/guides/queries
- Mutations: https://tanstack.com/query/latest/docs/react/guides/mutations
Version: 5.28.0 (check package.json)
Gotchas:
- Query keys must be arrays
- Automatic refetching on window focus (may want to disable)
- Stale time defaults to 0
```
### 2. Implementation Examples
**Where to Search**:
- GitHub repositories (search: "language:typescript [feature]")
- StackOverflow (recent answers)
- Official example repositories
- Blog posts from reputable sources
**What to Look For**:
- Production-grade code (not quick hacks)
- Recent examples (check dates)
- Well-explained implementations
- Edge case handling
**What to Document**:
```
Example: Form validation with Zod and React Hook Form
Source: https://github.com/react-hook-form/react-hook-form/tree/master/examples/V7/zodResolver
Relevance: Shows integration pattern we need
Key Takeaway: Use zodResolver for seamless integration
Caution: Needs @hookform/resolvers package
```
### 3. Best Practices Research
**Search Queries**:
- "[Technology] best practices 2024"
- "[Feature] common pitfalls"
- "[Library] performance optimization"
- "[Pattern] security considerations"
**What to Document**:
```
Practice: Input sanitization for user-generated content
Why: Prevent XSS attacks
How: Use DOMPurify library before rendering HTML
Reference: https://owasp.org/www-community/attacks/xss/
Warning: Never use dangerouslySetInnerHTML without sanitization
```
### 4. Performance Considerations
**Research**:
- Bundle size implications
- Runtime performance patterns
- Common optimization techniques
- Lazy loading opportunities
**What to Document**:
```
Performance: Large data table rendering
Solution: Use virtualization (@tanstack/react-virtual)
Reference: https://tanstack.com/virtual/latest
Benefit: Render only visible rows (handles 100k+ items)
Tradeoff: Adds 15KB to bundle
```
### 5. Security Research
**Check**:
- Common vulnerabilities (OWASP Top 10)
- Authentication/authorization patterns
- Data validation requirements
- Secure defaults
**What to Document**:
```
Security: API authentication
Pattern: Use HTTP-only cookies for tokens
Reference: https://owasp.org/www-community/HttpOnly
Implementation: Configure in Cloudflare Workers
Warning: Don't store tokens in localStorage
```
## Combining Research Findings
### Integration Analysis
After completing both codebase and external research:
1. **Match external patterns to codebase conventions**
- "Library X recommends pattern Y, but codebase uses pattern Z"
- Document adaptations needed
2. **Identify conflicts or gaps**
- "Existing auth pattern doesn't support OAuth"
- Document how to extend existing patterns
3. **Plan integration points**
- "New feature will integrate with existing [Component] at [Location]"
- Document all touch points
### Context Completeness Check
Before finalizing research, verify:
- [ ] Can implementer understand the codebase structure from your findings?
- [ ] Are all external dependencies documented with versions and URLs?
- [ ] Are code examples specific enough to follow?
- [ ] Are gotchas and warnings clearly stated?
- [ ] Are all integration points identified?
- [ ] Can implementer validate their work with the gates you've defined?
## Research Output Format
Organize findings into these categories for the PRP:
1. **Codebase Analysis**
- Similar patterns (with file:line references)
- Existing conventions (with examples)
- Test patterns (with framework details)
2. **External Research**
- Documentation references (with specific URLs and sections)
- Implementation examples (with source links and relevance)
- Best practices (with rationale and warnings)
3. **Integration Points**
- Where new code connects to existing code
- What patterns to follow
- What conventions to maintain
## Common Research Pitfalls to Avoid
1. **Vague references**: "There's a similar component somewhere" ❌
- Should be: "See UserProfile component at src/components/UserProfile.tsx:45" ✅
2. **Outdated examples**: Linking to old blog posts or deprecated APIs ❌
- Should be: Check dates, verify current best practices ✅
3. **Missing version info**: "Use React Query" ❌
- Should be: "Use @tanstack/react-query v5.28.0" ✅
4. **No gotchas**: Assuming smooth implementation ❌
- Should be: Document known issues, common mistakes, edge cases ✅
5. **Too generic**: "Follow React best practices" ❌
- Should be: Specific patterns with code examples ✅
## Research Time Allocation
**Codebase Analysis**: 40% of research time
- Critical for maintaining consistency
- Most valuable for implementation
**External Research**: 35% of research time
- Essential for new technologies
- Validation of approaches
**Integration Planning**: 15% of research time
- Connecting the dots
- Identifying conflicts
**Documentation**: 10% of research time
- Organizing findings
- Creating clear references
## Quality Indicators
Your research is complete when:
- ✅ An implementer could start coding immediately
- ✅ All necessary context is documented
- ✅ Integration points are clear
- ✅ Validation approach is defined
- ✅ Edge cases are identified
- ✅ Error handling strategy is outlined
- ✅ No assumptions are left undocumented

136
skills/timezone-tools/SKILL.md Normal file
View File

@@ -0,0 +1,136 @@
---
name: timezone-tools
description: Get current time in any timezone and convert times between timezones. Use when working with time, dates, timezones, scheduling across regions, or when user mentions specific cities/regions for time queries. Supports IANA timezone names.
---
# Timezone Tools
Get current time in any timezone and convert times between different timezones using IANA timezone database.
## Quick Start
### Get current time in a timezone
```bash
python scripts/get_time.py "America/New_York"
```
### Convert time between timezones
```bash
python scripts/convert_time.py "America/New_York" "14:30" "Australia/Perth"
```
### Search for timezone names
```bash
python scripts/list_timezones.py "perth"
```
## Instructions
When the user asks about time or timezones:
1. **For current time queries** (e.g., "What time is it in Tokyo?"):
- Use `get_time.py` with IANA timezone name
- If unsure of timezone name, search first with `list_timezones.py`
- Script outputs: timezone, datetime, day of week, DST status
2. **For time conversions** (e.g., "What's 2pm EST in Perth time?"):
- Use `convert_time.py` with source timezone, time (HH:MM 24-hour), target timezone
- Script shows source time, target time, and time difference
- Automatically handles DST changes
3. **For timezone searches**:
- Use `list_timezones.py` with city/country name
- Returns matching IANA timezone names
## Common Timezones Reference
For quick reference, see [data/common_timezones.json](data/common_timezones.json) which includes major cities worldwide, with Perth prominently featured.
**User's local timezone**: The scripts automatically detect your local timezone using `tzlocal`.
## Examples
### Example 1: Current time query
User: "What time is it in Perth?"
```bash
python scripts/list_timezones.py "perth"
# Output: Australia/Perth
python scripts/get_time.py "Australia/Perth"
# Output:
# Timezone: Australia/Perth
# Current time: 2025-11-07T15:30:45
# Day: Thursday
# DST: No
```
### Example 2: Time conversion
User: "I have a meeting at 2pm New York time, what time is that in Perth?"
```bash
python scripts/convert_time.py "America/New_York" "14:00" "Australia/Perth"
# Output:
# Source: America/New_York - 2025-11-07T14:00:00 (Thursday, DST: No)
# Target: Australia/Perth - 2025-11-08T03:00:00 (Friday, DST: No)
# Time difference: +13.0h
```
### Example 3: Multiple timezone search
User: "What are the timezone codes for London, Tokyo, and Sydney?"
```bash
python scripts/list_timezones.py "london"
python scripts/list_timezones.py "tokyo"
python scripts/list_timezones.py "sydney"
# Outputs:
# Europe/London
# Asia/Tokyo
# Australia/Sydney
```
## Time Format
- All times use **24-hour format** (HH:MM): `14:30` not `2:30 PM`
- ISO 8601 datetime format for output: `2025-11-07T14:30:45`
- IANA timezone names (e.g., `America/New_York`, not `EST`)
## Troubleshooting
### "Invalid timezone" error
- Use IANA timezone names: `America/New_York` not `EST` or `Eastern`
- Search with `list_timezones.py` if unsure
- Check [data/common_timezones.json](data/common_timezones.json) for reference
### "Invalid time format" error
- Use 24-hour format: `14:30` not `2:30 PM`
- Format must be `HH:MM` with colon separator
### Missing dependencies
Install required Python packages:
```bash
pip install tzlocal
```
## Dependencies
- Python 3.9+
- `tzlocal>=5.0` - for local timezone detection
- `zoneinfo` - built-in Python 3.9+ (IANA timezone database)
## Notes
- Scripts automatically handle Daylight Saving Time (DST)
- Local timezone is auto-detected from system
- All timezone data uses IANA Time Zone Database
- Perth, Australia timezone: `Australia/Perth` (UTC+8, no DST)

67
skills/timezone-tools/data/common_timezones.json Normal file
View File

@@ -0,0 +1,67 @@
{
"australia": {
"Perth": "Australia/Perth",
"Sydney": "Australia/Sydney",
"Melbourne": "Australia/Melbourne",
"Brisbane": "Australia/Brisbane",
"Adelaide": "Australia/Adelaide",
"Darwin": "Australia/Darwin",
"Hobart": "Australia/Hobart"
},
"north_america": {
"New York": "America/New_York",
"Los Angeles": "America/Los_Angeles",
"Chicago": "America/Chicago",
"Denver": "America/Denver",
"Toronto": "America/Toronto",
"Vancouver": "America/Vancouver",
"Mexico City": "America/Mexico_City"
},
"europe": {
"London": "Europe/London",
"Paris": "Europe/Paris",
"Berlin": "Europe/Berlin",
"Madrid": "Europe/Madrid",
"Rome": "Europe/Rome",
"Amsterdam": "Europe/Amsterdam",
"Stockholm": "Europe/Stockholm",
"Moscow": "Europe/Moscow"
},
"asia": {
"Tokyo": "Asia/Tokyo",
"Hong Kong": "Asia/Hong_Kong",
"Singapore": "Asia/Singapore",
"Beijing": "Asia/Shanghai",
"Mumbai": "Asia/Kolkata",
"Dubai": "Asia/Dubai",
"Seoul": "Asia/Seoul",
"Bangkok": "Asia/Bangkok"
},
"south_america": {
"Sao Paulo": "America/Sao_Paulo",
"Buenos Aires": "America/Argentina/Buenos_Aires",
"Lima": "America/Lima",
"Bogota": "America/Bogota",
"Santiago": "America/Santiago"
},
"africa": {
"Cairo": "Africa/Cairo",
"Johannesburg": "Africa/Johannesburg",
"Lagos": "Africa/Lagos",
"Nairobi": "Africa/Nairobi"
},
"pacific": {
"Auckland": "Pacific/Auckland",
"Fiji": "Pacific/Fiji",
"Honolulu": "Pacific/Honolulu",
"Guam": "Pacific/Guam"
},
"utc": {
"UTC": "UTC"
},
"_notes": {
"format": "City Name -> IANA Timezone",
"perth_details": "Perth: UTC+8, no DST, Western Australia",
"usage": "Use list_timezones.py to search for additional cities"
}
}

89
skills/timezone-tools/scripts/convert_time.py Executable file
View File

@@ -0,0 +1,89 @@
#!/usr/bin/env python3
"""Convert time between timezones."""
import sys
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
def convert_time(source_tz: str, time_str: str, target_tz: str) -> None:
"""Convert time from source timezone to target timezone.
Args:
source_tz: Source IANA timezone name (e.g., 'America/New_York')
time_str: Time to convert in 24-hour format (HH:MM)
target_tz: Target IANA timezone name (e.g., 'Australia/Perth')
"""
try:
# Parse timezone names
source_timezone = ZoneInfo(source_tz)
target_timezone = ZoneInfo(target_tz)
# Parse time string
try:
parsed_time = datetime.strptime(time_str, "%H:%M").time()
except ValueError:
print(f"Error: Invalid time format '{time_str}'", file=sys.stderr)
print("Expected format: HH:MM (24-hour, e.g., '14:30')", file=sys.stderr)
sys.exit(1)
# Create datetime for today in source timezone
now = datetime.now(source_timezone)
source_time = datetime(
now.year,
now.month,
now.day,
parsed_time.hour,
parsed_time.minute,
tzinfo=source_timezone,
)
# Convert to target timezone
target_time = source_time.astimezone(target_timezone)
# Calculate time difference
source_offset = source_time.utcoffset() or timedelta()
target_offset = target_time.utcoffset() or timedelta()
hours_difference = (target_offset - source_offset).total_seconds() / 3600
# Format time difference (handle fractional hours like Nepal's +5:45)
if hours_difference.is_integer():
time_diff_str = f"{hours_difference:+.1f}h"
else:
time_diff_str = f"{hours_difference:+.2f}".rstrip("0").rstrip(".") + "h"
# Check DST status
source_dst = source_time.dst() is not None and source_time.dst().total_seconds() != 0
target_dst = target_time.dst() is not None and target_time.dst().total_seconds() != 0
# Output formatted information
print(f"Source: {source_tz} - {source_time.isoformat(timespec='seconds')} "
f"({source_time.strftime('%A')}, DST: {'Yes' if source_dst else 'No'})")
print(f"Target: {target_tz} - {target_time.isoformat(timespec='seconds')} "
f"({target_time.strftime('%A')}, DST: {'Yes' if target_dst else 'No'})")
print(f"Time difference: {time_diff_str}")
except Exception as e:
if "ZoneInfo" in str(type(e).__name__):
print(f"Error: Invalid timezone", file=sys.stderr)
else:
print(f"Error: {str(e)}", file=sys.stderr)
sys.exit(1)
def main():
if len(sys.argv) != 4:
print("Usage: python convert_time.py <source_tz> <time> <target_tz>", file=sys.stderr)
print("Example: python convert_time.py 'America/New_York' '14:30' 'Australia/Perth'",
file=sys.stderr)
sys.exit(1)
source_tz = sys.argv[1]
time_str = sys.argv[2]
target_tz = sys.argv[3]
convert_time(source_tz, time_str, target_tz)
if __name__ == "__main__":
main()

45
skills/timezone-tools/scripts/get_time.py Executable file
View File

@@ -0,0 +1,45 @@
#!/usr/bin/env python3
"""Get current time in a specific timezone."""
import sys
from datetime import datetime
from zoneinfo import ZoneInfo
def get_current_time(timezone_name: str) -> None:
"""Get and display current time in specified timezone.
Args:
timezone_name: IANA timezone name (e.g., 'America/New_York')
"""
try:
timezone = ZoneInfo(timezone_name)
current_time = datetime.now(timezone)
# Check if DST is active
is_dst = current_time.dst() is not None and current_time.dst().total_seconds() != 0
# Output formatted information
print(f"Timezone: {timezone_name}")
print(f"Current time: {current_time.isoformat(timespec='seconds')}")
print(f"Day: {current_time.strftime('%A')}")
print(f"DST: {'Yes' if is_dst else 'No'}")
except Exception as e:
print(f"Error: Invalid timezone '{timezone_name}'", file=sys.stderr)
print(f"Details: {str(e)}", file=sys.stderr)
sys.exit(1)
def main():
if len(sys.argv) != 2:
print("Usage: python get_time.py <timezone>", file=sys.stderr)
print("Example: python get_time.py 'America/New_York'", file=sys.stderr)
sys.exit(1)
timezone_name = sys.argv[1]
get_current_time(timezone_name)
if __name__ == "__main__":
main()

53
skills/timezone-tools/scripts/list_timezones.py Executable file
View File

@@ -0,0 +1,53 @@
#!/usr/bin/env python3
"""Search for IANA timezone names."""
import sys
from zoneinfo import available_timezones
def list_timezones(search_term: str = "") -> None:
"""List timezone names matching the search term.
Args:
search_term: Optional search term to filter timezone names (case-insensitive)
"""
try:
all_timezones = sorted(available_timezones())
if search_term:
# Case-insensitive search
search_lower = search_term.lower()
matching = [tz for tz in all_timezones if search_lower in tz.lower()]
if matching:
print(f"Timezones matching '{search_term}':")
for tz in matching:
print(f" {tz}")
else:
print(f"No timezones found matching '{search_term}'", file=sys.stderr)
print("\nTip: Try searching for city names like 'perth', 'london', 'tokyo'",
file=sys.stderr)
sys.exit(1)
else:
# List all timezones (this is a lot!)
print(f"All available timezones ({len(all_timezones)} total):")
for tz in all_timezones:
print(f" {tz}")
except Exception as e:
print(f"Error: {str(e)}", file=sys.stderr)
sys.exit(1)
def main():
if len(sys.argv) > 2:
print("Usage: python list_timezones.py [search_term]", file=sys.stderr)
print("Example: python list_timezones.py 'perth'", file=sys.stderr)
sys.exit(1)
search_term = sys.argv[1] if len(sys.argv) == 2 else ""
list_timezones(search_term)
if __name__ == "__main__":
main()

7
skills/timezone-tools/scripts/requirements.txt Normal file
View File

@@ -0,0 +1,7 @@
# Timezone Tools - Python Dependencies
# Install with: pip install -r requirements.txt
# Local timezone detection
tzlocal>=5.0
# Note: zoneinfo is built into Python 3.9+, no installation needed