zhongwei/gh-l-sypniewski-claude-code-toolkit-plugins-context-engineering
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-30 08:36:32 +08:00
commit 6c1573951f
12 changed files with 1995 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
commands/execute-prp.md Normal file
View File

@@ -0,0 +1,43 @@
# Execute BASE PRP
Implement a feature using using the PRP file.
## PRP File: $ARGUMENTS
## Execution Process
1. **Load PRP**
- Read the specified PRP file
- Understand all context and requirements
- Follow all instructions in the PRP and extend the research if needed
- Ensure you have all needed context to implement the PRP fully
- Do more web searches and codebase exploration as needed
2. **ULTRATHINK**
- Think hard before you execute the plan. Create a comprehensive plan addressing all requirements.
- Break down complex tasks into smaller, manageable steps using your todos tools.
- Use the TodoWrite tool to create and track your implementation plan.
- Identify implementation patterns from existing code to follow.
3. **Execute the plan**
- Execute the PRP
- Implement all the code
4. **Validate**
- Run each validation command
- Fix any failures
- Re-run until all pass
5. **Complete**
- Ensure all checklist items done
- Run final validation suite
- Report completion status
- Read the PRP again to ensure you have implemented everything
6. **Reference the PRP**
- You can always reference the PRP again if needed
Note: If validation fails, use error patterns in PRP to fix and retry.
## Additional instructions
Use sequential thinking, context7 MCPs to solve the problem using latest documentation and best practices. Ultrathink the approach and a plan.

81
commands/generate-prp.md Normal file
View File

@@ -0,0 +1,81 @@
# Create PRP
## GitHub Issue URL: $ARGUMENTS
Generate a complete PRP for general feature implementation with thorough research. Ensure context is passed to the AI agent to enable self-validation and iterative refinement. Read the GitHub issue first (specifically the context engineering comment created by `initial-github-issue` command) to understand what needs to be created, how the examples provided help, and any other considerations.
The AI agent only gets the context you are appending to the PRP and training data. Assuma the AI agent has access to the codebase and the same knowledge cutoff as you, so its important that your research findings are included or referenced in the PRP. The Agent has Websearch capabilities, so pass urls to documentation and examples.
## Research Process
1. **GitHub Issue Analysis**
- Fetch the GitHub issue using GitHub MCP
- Extract the context engineering comment (created by `initial-github-issue` command)
- Parse FEATURE, EXAMPLES, DOCUMENTATION, and OTHER CONSIDERATIONS sections
- Understand the complete feature requirements and constraints
2. **Codebase Analysis**
- Search for similar features/patterns in the codebase
- Identify files to reference in PRP
- Note existing conventions to follow
- Check test patterns for validation approach
3. **External Research**
- Search for similar features/patterns online
- Library documentation (include specific URLs)
- Implementation examples (GitHub/StackOverflow/blogs)
- Best practices and common pitfalls
4. **User Clarification** (if needed)
- Specific patterns to mirror and where to find them?
- Integration requirements and where to find them?
## PRP Generation
Using PRPs/templates/prp_base.md as template:
### Critical Context to Include and pass to the AI agent as part of the PRP
- **Documentation**: URLs with specific sections
- **Code Examples**: Real snippets from codebase
- **Gotchas**: Library quirks, version issues
- **Patterns**: Existing approaches to follow
### Implementation Blueprint
- Start with pseudocode showing approach
- Reference real files for patterns
- Include error handling strategy
- list tasks to be completed to fullfill the PRP in the order they should be completed
### Validation Gates (Must be Executable) for REWOS project
```bash
# Frontend Validation (Astro.js)
cd astro && npm run build
# CMS Validation (Strapi)
cd strapi/rewos && npm run build
# Integration Tests
cd tests && npm test
```
*** CRITICAL AFTER YOU ARE DONE RESEARCHING AND EXPLORING THE CODEBASE BEFORE YOU START WRITING THE PRP ***
*** ULTRATHINK ABOUT THE PRP AND PLAN YOUR APPROACH THEN START WRITING THE PRP ***
## Output
Save as: `PRPs/{feature-name}.md`
## Quality Checklist
- [ ] All necessary context included
- [ ] Validation gates are executable by AI
- [ ] References existing patterns
- [ ] Clear implementation path
- [ ] Error handling documented
Score the PRP on a scale of 1-10 (confidence level to succeed in one-pass implementation using claude codes)
Remember: The goal is one-pass implementation success through comprehensive context.
## Additional instructions
Use sequential thinking, context7 MCPs to solve the problem using latest documentation and best practices. Ultrathink the approach and a plan.

265
commands/initial-github-issue.md Normal file
View File

@@ -0,0 +1,265 @@
# Format GitHub Issue for Context Engineering
## GitHub Issue URL: $ARGUMENTS
Transform a GitHub issue to follow the INITIAL.md format for context engineering workflow.
```initial.md
## FEATURE:
[Insert your feature here]
## EXAMPLES:
[Provide and explain examples that you have in the `examples/` folder]
## DOCUMENTATION:
[List out any documentation (web pages, sources for an MCP server like Crawl4AI RAG, etc.) that will need to be referenced during development]
## OTHER CONSIDERATIONS:
[Any other considerations or specific requirements - great place to include gotchas that you see AI coding assistants miss with your projects a lot]
```
## CRITICAL: Follow INITIAL.md Best Practices
When executing this command, you MUST follow these specific rules:
### FEATURE Section Rules
- ❌ **NEVER write vague descriptions** like "Build a web scraper" or "Create a contact form"
- ✅ **ALWAYS be specific and comprehensive** like "Build an async web scraper using BeautifulSoup that extracts product data from e-commerce sites, handles rate limiting, and stores results in PostgreSQL"
- Include specific technologies, libraries, and integration points
- Define exact functionality, validation, error handling, and UX requirements
### EXAMPLES Section Rules
- **Leverage the examples/ folder** - always check for relevant patterns
- **Provide specific file references** - not generic descriptions
- **Explain what aspects to mimic** - styling, validation, state management, etc.
- Reference existing components in the REWOS codebase that follow similar patterns
### DOCUMENTATION Section Rules
- **Include ALL relevant resources** with direct URLs
- API documentation with specific section links
- Library guides (Astro.js, React, Zod, Cloudflare Workers, etc.)
- MCP server documentation when applicable
- Database schemas (Strapi content types)
### OTHER CONSIDERATIONS Rules
- **Capture project-specific details** that AI agents commonly miss
- Authentication requirements, API keys, permissions
- Rate limits and quotas (especially Cloudflare Workers constraints)
- Performance requirements (Lighthouse scores, Core Web Vitals)
- Common pitfalls specific to REWOS architecture
- Browser compatibility and accessibility requirements
### CRITICAL: Ask for Missing Information - Never Assume
**When information is missing or unclear, STOP and ask for clarification:**
- ❌ **NEVER make assumptions** about missing requirements
- ❌ **NEVER fill in blanks** with generic or guessed information
- ✅ **ALWAYS ask specific questions** to get missing details
- ✅ **IDENTIFY gaps** and request clarification before proceeding
**Common areas that need clarification:**
- **User interactions**: What exactly should happen when user does X?
- **Data sources**: Where does the data come from? What's the schema?
- **Integration requirements**: How should this connect to existing systems?
- **Performance constraints**: Are there specific speed/size requirements?
- **Validation rules**: What are the exact validation requirements?
- **Error scenarios**: How should errors be handled and displayed?
- **Responsive behavior**: How should this work across different screen sizes?
- **Authentication/permissions**: Who can access this feature and how?
**Ask questions like:**
- "The issue mentions 'form validation' - what specific validation rules are needed?"
- "You mentioned 'data processing' - what's the expected data format and source?"
- "For the responsive design - are there specific breakpoint requirements?"
- "What authentication method should be used for this feature?"
- "Are there specific performance or accessibility requirements?"
## Process
1. **Extract Issue Information**
- Parse the GitHub issue URL to get owner, repo, and issue number
- Fetch the current issue content using GitHub MCP
- Preserve the original issue description
2. **Analyze Issue for Completeness**
- Analyze the original issue description for specificity and completeness
- **CRITICAL: Identify missing or unclear information**
- Check for gaps in user interactions, data sources, validation rules, etc.
- **If information is missing: STOP and ask specific clarifying questions**
- Only proceed once all necessary details are clarified
3. **Enhance Issue Content (Only After Clarification)**
- Transform vague requirements into specific, comprehensive descriptions
- Research the codebase for relevant patterns and examples
- Identify documentation and resources needed for implementation
- Determine project-specific constraints and potential pitfalls
4. **Create Context Engineering Format**
- Add a comment to the GitHub issue with the enhanced, formatted content
- Use the INITIAL.md structure with best practices:
- **FEATURE**: Specific, comprehensive functionality description (not vague)
- **EXAMPLES**: Concrete file references from examples/ and existing codebase
- **DOCUMENTATION**: Complete list of URLs for APIs, libraries, guides
- **OTHER CONSIDERATIONS**: Authentication, performance, pitfalls, constraints
5. **GitHub MCP Integration**
- Use the GitHub MCP server to add a formatted comment to the issue
- Preserve original content by keeping it intact in the issue description
- The formatted comment becomes the context engineering specification
## Implementation Steps
1. **Parse Issue URL**
```
Extract: owner, repo, issue_number from URL pattern:
https://github.com/{owner}/{repo}/issues/{issue_number}
```
2. **Fetch Issue Content**
```
Use GitHub MCP to get issue title and body content
```
3. **Generate Formatted Comment**
```
Create a comment with this template following INITIAL.md best practices:
---
# Context Engineering Specification
## FEATURE
**Transform the original issue description to be specific and comprehensive:**
❌ Avoid: Vague descriptions like "Build a contact form"
✅ Provide: "Build an async contact form component for Astro.js that validates email/phone fields using Zod schemas, integrates with Cloudflare Workers for submission processing, handles spam protection with Turnstile, and provides real-time validation feedback with accessible error messages"
**Requirements:**
- Include specific technologies and libraries to be used
- Define exact functionality and behavior
- Specify integration points with existing REWOS architecture
- Detail validation, error handling, and user experience requirements
## EXAMPLES
**Leverage the examples/ folder and existing codebase patterns:**
- **Specific file references:** `examples/[relevant-pattern]/[file].tsx`
- **Existing components to follow:** `astro/src/components/[ComponentName]/`
- **Pattern explanations:** What aspects should be mimicked (styling, validation, state management)
- **Architecture patterns:** Reference similar implementations in the codebase
**Example format:**
```
Follow the pattern established in:
- `astro/src/components/ContactForm.astro` for form structure
- `examples/form-validation/zod-schema.ts` for validation patterns
- `astro/src/utils/component-to-html.ts` for HTML generation patterns
```
## DOCUMENTATION
**Include ALL relevant resources with specific URLs:**
- **API Documentation:** Direct links to relevant API sections
- **Library Guides:** Astro.js, React, Zod, Cloudflare Workers documentation
- **MCP Server Documentation:** If using GitHub, Playwright, or other MCP servers
- **Database Schemas:** Strapi content type definitions
- **Deployment Docs:** Cloudflare Pages/Workers specific documentation
**Example format:**
```
- Astro Forms: https://docs.astro.build/en/guides/server-side-rendering/#form-actions
- Zod Validation: https://zod.dev/?id=basic-usage
- Cloudflare Workers: https://developers.cloudflare.com/workers/runtime-apis/request/
- Strapi API: https://docs.strapi.io/dev-docs/api/rest
```
## OTHER CONSIDERATIONS
**Capture important implementation details:**
- **Authentication Requirements:** API keys, user sessions, permissions
- **Rate Limits/Quotas:** Cloudflare Workers limits, API rate limits
- **Common Pitfalls:** REWOS-specific gotchas that AI agents commonly miss
- **Performance Requirements:** Bundle size, loading time, Core Web Vitals impact
- **Browser Compatibility:** Specific browser support requirements
- **Accessibility:** WCAG compliance, screen reader support
- **Responsive Design:** Breakpoint-specific behavior, container queries usage
- **Integration Constraints:** How this affects existing Astro/Strapi integration
**Example format:**
```
- Cloudflare Workers have 10ms CPU time limit for form processing
- Must use CSS container queries (not viewport queries) for responsive behavior
- REWOS project requires Lighthouse score >95 - optimize for Core Web Vitals
- Form validation must work without JavaScript (progressive enhancement)
- Spam protection: Use Turnstile, not reCAPTCHA (brand consistency)
```
---
*This comment contains the context engineering specification for this feature following INITIAL.md best practices.*
```
4. **Add Comment to Issue**
```
Use GitHub MCP to post the formatted comment to the issue
```
## Expected Outcome
### If Issue Has Complete Information:
- Original issue description remains unchanged
- New comment contains the INITIAL.md formatted specification
- Comment can be referenced by the `generate-prp` command
- Workflow can proceed with GitHub issue as the source of truth
### If Issue Has Missing Information:
- **Command pauses and asks for clarification** with specific questions
- User provides missing details in response
- **Only then** proceeds to create the formatted comment
- Ensures comprehensive context before moving to PRP generation
**Key Principle**: Better to ask questions upfront than implement based on assumptions.
## Error Handling
- Validate GitHub URL format
- Check if issue exists and is accessible
- Handle authentication errors gracefully
- Provide clear feedback if formatting fails
## Usage Example
```
/initial-github-issue https://github.com/owner/repo/issues/123
```
This will fetch issue #123, analyze its content, and add a formatted comment following the context engineering principles.
## Additional instructions
Use sequential thinking, context7 MCPs to solve the problem using latest documentation and best practices. Ultrathink the approach and a plan.