zhongwei/gh-l-sypniewski-claude-code-toolkit-plugins-context-engineering

Fork 0

Files

Zhongwei Li 6c1573951f Initial commit

2025-11-30 08:36:32 +08:00

10 KiB

Raw Permalink Blame History

Format GitHub Issue for Context Engineering

GitHub Issue URL: $ARGUMENTS

Transform a GitHub issue to follow the INITIAL.md format for context engineering workflow.

## 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

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
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
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
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
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

Parse Issue URL

Extract: owner, repo, issue_number from URL pattern:
https://github.com/{owner}/{repo}/issues/{issue_number}

Fetch Issue Content

Use GitHub MCP to get issue title and body content

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.*

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.

10 KiB Raw Permalink Blame History