ai-prompt-guide-mcp 1.0.2 → 1.0.3

package/.ai-prompt-guide/guides/research-guide.md

@@ -0,0 +1,86 @@
+---
+title: "Research Best Practices"
+description: "Finding and validating authoritative sources"
+---
+
+# Research Best Practices
+
+## Source Reliability Hierarchy
+
+**Primary Sources (Most Reliable):**
+- Official documentation: framework, library, or service docs
+- API specifications: OpenAPI, GraphQL schemas
+- GitHub repositories: official project repos, README files
+- Official blogs/changelogs: product announcements, release notes
+
+**Secondary Sources (Verify Carefully):**
+- Stack Overflow: for specific implementation questions
+- Developer blogs: individual experiences and tutorials
+- Community forums: Discord, Reddit, specialized communities
+- Video tutorials: recent content from reputable creators
+
+## Research Methodology
+
+**Start with Official Sources:**
+- Project homepage and documentation
+- Official API references
+- Release notes and changelogs
+- Migration guides
+
+**Verify Information Currency:**
+- Check publication/update dates
+- Look for "last modified" timestamps
+- Cross-reference version numbers
+- Note any deprecation warnings
+
+**Cross-Reference Multiple Sources:**
+- Compare information across 2-3 authoritative sources
+- Look for consensus on best practices
+- Note any conflicting information for further investigation
+
+**Test and Validate:**
+- Run code examples yourself when possible
+- Verify API endpoints and responses
+- Test compatibility with current versions
+- Document any discrepancies found
+
+## Staying Current
+
+**For Technical Documentation:**
+- Subscribe to official channels (newsletters, RSS feeds)
+- Follow project maintainers on social media
+- Monitor GitHub releases for breaking changes
+- Join community discussions for early insights
+
+**For Best Practices:**
+- Industry reports and surveys (State of JS, Stack Overflow Survey)
+- Conference talks and presentations
+- Peer-reviewed articles in technical publications
+- Expert practitioner blogs with strong track records
+
+## Warning Signs
+
+**Outdated Information:**
+- Old tutorial dates (2+ years for fast-moving tech)
+- References to deprecated APIs or methods
+- Screenshots of old UI versions
+- Missing recent security considerations
+
+**Unreliable Sources:**
+- Anonymous or unverified authors
+- Content farms optimized for SEO over accuracy
+- Tutorials with many negative comments/feedback
+- Information that contradicts official docs without explanation
+
+## Pre-Writing Validation
+
+Before documenting:
+- Found official documentation for all mentioned tools/APIs
+- Verified current version numbers and compatibility
+- Tested key code examples or procedures
+- Identified any recent breaking changes or deprecations
+- Located authoritative sources for best practices
+- Noted any security or performance considerations
+- Found examples of real-world implementations
+
+Great documentation starts with great research.

package/.ai-prompt-guide/guides/specification-writing.md

@@ -0,0 +1,151 @@
+---
+title: "Technical Specification Writing"
+description: "Best practices for creating comprehensive technical specifications"
+---
+
+# Technical Specification Writing
+
+**Purpose:** Create comprehensive technical specifications for tools, APIs, and systems with authoritative accuracy and structured organization.
+
+## Research & Intelligence Gathering
+
+**Find Authoritative Sources:**
+
+**Official Documentation:**
+- Search: `[tool name] official documentation site:docs.*`
+- Look for: API references, OpenAPI specs, SDK documentation
+- Verify: version numbers, last updated dates
+
+**Source Code & Repositories:**
+- GitHub official repos (README, examples, API definitions)
+- Package registries (npm, PyPI, crates.io) for latest versions
+- Release notes and changelogs for recent changes
+
+**Technical Specifications:**
+- OpenAPI/Swagger definitions
+- GraphQL schemas
+- Protocol specifications (RFCs, standards docs)
+- Database schemas and ERDs
+
+**Validation Priorities:**
+- Current version numbers
+- Deprecation warnings
+- Breaking changes in recent releases
+- Official API endpoints/methods
+- Authentication requirements
+- Rate limits and quotas
+
+## Document Structure & Organization
+
+**Path Architecture:**
+- `/api/[service]/[endpoint]` - API endpoint documentation
+- `/tools/[tool-name]/[feature]` - Tool specifications
+- `/systems/[component]/[aspect]` - System architecture
+- `/protocols/[protocol-name]` - Communication protocols
+- `/schemas/[data-type]` - Data structure definitions
+
+**Essential Sections:**
+- Overview: brief description and purpose
+- Technical Requirements: version, dependencies, platform
+- Configuration: setup and configuration details
+- API Reference/Interface: detailed technical interface
+- Data Structures: schemas, types, models
+- Examples: working code with expected outputs
+- Error Handling: error codes, exceptions, troubleshooting
+- Performance: limits, optimization, best practices
+- Security: authentication, authorization, considerations
+- References: links to official documentation
+
+## Technical Content Standards
+
+**Code Examples:**
+- Include language-specific examples where relevant
+- Show both request and response formats
+- Include error handling scenarios
+- Test all examples before documenting
+- Add inline comments for clarity
+
+**API Documentation:**
+- List all endpoints with HTTP methods
+- Document all parameters (required/optional)
+- Include request/response schemas
+- Show authentication headers
+- Document rate limits and quotas
+- Include pagination details
+
+**Data Structure Documentation:**
+- Use JSON Schema or similar formal notation
+- Include field types and constraints
+- Document enums and constants
+- Show relationships between entities
+- Include validation rules
+
+## Accuracy Verification
+
+**Technical Validation:**
+- Test all API endpoints with actual calls
+- Verify response formats match documentation
+- Confirm error codes and messages
+- Check compatibility with specified versions
+- Validate against official specs (OpenAPI, etc.)
+
+**Cross-Reference:**
+- Compare with official documentation
+- Verify against source code
+- Check community feedback for gotchas
+- Review recent issues/discussions
+
+## Writing Priorities
+
+**Precision over simplicity:**
+- No room for interpretation
+- Technical accuracy maintained
+- Complete information: all parameters, options, edge cases
+- Version-specific: always indicate applicable versions
+
+**Maintenance approach:**
+- Date stamp technical information
+- Track API versions and deprecations
+- Update immediately for breaking changes
+- Archive old versions separately
+
+**Quality requirements:**
+- All code examples executable
+- All endpoints tested
+- All data structures validated
+- All links verified
+- All version numbers current
+
+## Common Specification Types
+
+**API Specifications:** Endpoints, methods, parameters, authentication, rate limits, response formats, error codes
+
+**Tool Specifications:** Installation, configuration, CLI commands, options/flags, input/output formats, integration points
+
+**System Specifications:** Architecture, components, interfaces, data flow, protocols, performance specs, scaling limits
+
+**Protocol Specifications:** Message formats, handshake procedures, state machines, error handling, security measures
+
+## Finding API Documentation
+
+**Search strategies:**
+- "[API name] REST API documentation"
+- "[Tool name] OpenAPI specification"
+- "[Service] API reference" site:docs.*
+- "[Platform] developer documentation"
+- intitle:"API Reference" [tool name]
+
+**Key documentation sites:**
+- docs.[company].com
+- developer.[company].com
+- api.[company].com
+- [company].readme.io
+- [tool].readthedocs.io
+
+**Latest information sources:**
+- GitHub releases within last 3 months
+- "What's New" or "Changelog" sections
+- Migration guides from previous versions
+- Deprecation notices and sunset dates
+
+Always verify with multiple authoritative sources and test actual behavior when documenting technical specifications.

package/.ai-prompt-guide/guides/tutorial-writing.md

@@ -0,0 +1,170 @@
+---
+title: "Tutorial & Guide Writing"
+description: "Best practices for creating clear, actionable guides and tutorials"
+---
+
+# Tutorial & Guide Writing
+
+**Purpose:** Create clear, actionable guides and tutorials for processes, workflows, and step-by-step instructions that users or LLMs can follow effectively.
+
+## Audience & Purpose Analysis
+
+**Define Your Guide:**
+
+**Target Audience:**
+- Technical level (beginner/intermediate/advanced)
+- Background knowledge required
+- Tools they have access to
+
+**Guide Objectives:**
+- What will users accomplish?
+- What problems does this solve?
+- What's the expected outcome?
+
+**Prerequisites:**
+- Required tools/software
+- Necessary permissions
+- Prior knowledge needed
+- Time investment expected
+
+## Research & Validation
+
+**Gather Accurate Information:**
+- Test the process: actually perform the steps yourself
+- Check multiple sources: verify approaches with 2-3 sources
+- Find common issues: search for FAQ/troubleshooting
+- Identify variations: note platform/version differences
+
+**Research Sources:**
+- Official getting started guides
+- Video tutorials (check comments for issues)
+- Community forums and discussions
+- Stack Overflow for common problems
+- Blog posts from practitioners
+
+**Validation priorities:**
+- Tested the complete process end-to-end
+- Identified potential failure points
+- Found alternative approaches
+- Collected troubleshooting tips
+- Verified tool/version compatibility
+
+## Structure & Organization
+
+**Path Architecture:**
+- `/guides/getting-started/` - Initial setup and basics
+- `/tutorials/[topic]/` - Step-by-step tutorials
+- `/how-to/[task]/` - Specific task instructions
+- `/workflows/[process]/` - Multi-step processes
+- `/troubleshooting/[issue]/` - Problem-solving guides
+
+**Standard Template:**
+- Title: action-oriented
+- Overview: what this accomplishes (1-2 sentences)
+- Prerequisites: required software, permissions, knowledge, time estimate
+- Steps: clear actions with expected results
+- Verification: how to confirm success
+- Troubleshooting: common issues and solutions
+- Next Steps: related guides and advanced topics
+- Quick Reference: summary of key commands/actions
+
+## Writing Effective Instructions
+
+**Step-by-Step Clarity:**
+- Start with a verb: "Click", "Run", "Configure"
+- Be specific: "Click the blue 'Submit' button" not "Click submit"
+- One action per step: break complex actions into substeps
+- Include expected outcomes: "You should see a confirmation message"
+- Add context when needed: explain why a step is important
+
+**Visual Aids & Examples:**
+- Include command examples with actual values
+- Show expected output/results
+- Use formatted code blocks
+- Add screenshots for UI steps (when possible)
+- Include decision trees for branching paths
+
+**Progressive Disclosure:**
+- Start with the happy path
+- Add variations after basics
+- Include advanced options separately
+- Keep troubleshooting at the end
+
+## User Experience Optimization
+
+**Make Guides Scannable:**
+- Use descriptive headings
+- Include table of contents for long guides
+- Highlight important warnings/notes
+- Use consistent formatting
+- Add summary/quick reference sections
+
+**Accommodate Different Skill Levels:**
+- Provide context for beginners
+- Include shortcuts for experts
+- Offer multiple approaches when applicable
+- Link to background information
+
+**Test Guide Usability:**
+- Follow your own instructions exactly
+- Note any ambiguous points
+- Time the process
+- Identify missing steps
+- Add clarifications as needed
+
+## Writing Style Priorities
+
+**Voice and approach:**
+- Action-oriented: focus on doing, not theory
+- Conversational but clear: friendly yet precise
+- Present tense: "Click" not "You will click"
+- Active voice: direct and engaging
+- Consistent terminology: same names throughout
+
+## Common Guide Types
+
+**Getting Started Guides:** Installation and setup, first-time configuration, hello world examples, basic feature tours
+
+**How-To Guides:** Specific task completion, problem-solving approaches, feature implementation, integration procedures
+
+**Tutorials:** Learning-focused walkthroughs, build something from scratch, progressive skill building, hands-on exercises
+
+**Workflow Guides:** End-to-end processes, multi-tool procedures, team collaborations, deployment pipelines
+
+## Quality Requirements
+
+Before publishing:
+- All steps tested and working
+- Prerequisites clearly stated
+- Time estimates accurate
+- Troubleshooting section complete
+- Examples use realistic data
+- Links and references verified
+- Version compatibility noted
+- Next steps provided
+
+## Audience-Specific Considerations
+
+**For End Users:** Minimize technical jargon, provide GUI-based instructions, include plenty of examples, focus on outcomes over process, add glossary for technical terms
+
+**For Developers/LLMs:** Include CLI commands, provide scriptable examples, document exit codes/returns, show API/programmatic approaches, include automation possibilities
+
+**For System Administrators:** Document configuration files, include security considerations, provide backup/rollback steps, note performance impacts, include monitoring/logging
+
+## Finding Information
+
+**Search strategies:**
+- "how to [task] [tool/platform]"
+- "[tool] getting started guide"
+- "[task] tutorial" site:youtube.com (check recent dates)
+- "[error message]" + solution
+- intitle:"tutorial" OR intitle:"guide" [topic]
+
+**Quality indicators:**
+- Recent publication date
+- Positive community feedback
+- Official or verified sources
+- Step-by-step structure
+- Includes troubleshooting
+
+The best guides come from actually doing the task and documenting issues you encounter along the way.

package/.ai-prompt-guide/guides/writing-standards.md

@@ -0,0 +1,94 @@
+---
+title: "Documentation Writing Standards"
+description: "Content organization, writing style, and formatting standards"
+---
+
+# Documentation Writing Standards
+
+## Content Organization
+
+**Path Structure:**
+- Use lowercase with hyphens for multi-word paths
+- Keep paths logical and hierarchical
+- Maximum 4 levels deep for maintainability
+- Examples: `/api/authentication`, `/guides/getting-started`
+
+**Heading Hierarchy:**
+- H1: Document title (one per document)
+- H2: Main sections
+- H3: Subsections
+- H4: Sub-subsections (sparingly)
+- H5-H6: Avoid except for special cases
+
+**Standard Structure:**
+- Brief introduction explaining purpose and scope
+- Prerequisites: required knowledge, tools, versions
+- Main content with clear sections and subsections
+- Related documents with links
+- Troubleshooting section for common issues
+
+## Writing Style
+
+**Voice and Tone:**
+- Clear and direct: avoid unnecessary complexity
+- Active voice: "Configure the server" not "The server should be configured"
+- Present tense: "The API returns..." not "The API will return..."
+- Conversational but professional
+
+**Technical Writing Priorities:**
+- Define acronyms on first use: "Application Programming Interface (API)"
+- Use consistent terminology throughout
+- Write scannable content with bullets and short paragraphs
+- Include context for code examples
+
+**Code and Examples:**
+- Use syntax highlighting with appropriate language tags
+- Include input and expected output where relevant
+- Explain non-obvious code with comments or prose
+- Test all examples before publishing
+
+## Formatting Standards
+
+**Code Blocks:**
+- Always specify language for syntax highlighting
+- Include comments explaining non-obvious parts
+- Use proper indentation
+- Show realistic, runnable examples
+
+**Lists and Bullets:**
+- Use parallel structure in lists
+- Start each item with same part of speech
+- Keep items roughly equal in length
+- Use numbered lists for sequential steps
+
+**Links and References:**
+- Use descriptive link text instead of "click here"
+- Test all links before publishing
+- Use relative paths for internal documents
+- Include access dates for time-sensitive external links
+
+## Maintenance Standards
+
+**Review Schedule:**
+- Monthly reviews for rapidly changing topics
+- Quarterly reviews for stable technical content
+- Annual reviews for foundational documentation
+- Immediate updates for security-related changes
+
+**Version Control:**
+- Document major changes in commit messages
+- Use semantic versioning for major doc overhauls
+- Tag releases for coordinated documentation updates
+- Maintain changelog for complex documents
+
+**Quality Requirements:**
+- All code examples tested and working
+- All links verified and functional
+- Spelling and grammar checked
+- Consistent with style guidelines
+- Peer reviewed when possible
+- Accurate and up-to-date information
+- Clear purpose and target audience
+- Logical flow and organization
+
+Consistency builds trust, accuracy builds reputation.

package/.ai-prompt-guide/workflows/audit.md

@@ -0,0 +1,46 @@
+---
+title: "Audit"
+description: "🔍 AUDIT: Comprehensive quality audit with parallel agents, each focusing on specific issue types"
+whenToUse: "Deep quality analysis across codebase dimensions before production or when needing specialized expert review"
+---
+
+# Workflow: Comprehensive Codebase Audit
+
+1. [Coordinator] Select 5-10 issue types from standard categories
+2. [Coordinator] Prioritize essential three: Security Vulnerabilities, Error Handling, Data Validation
+
+**LOOP: For each selected issue_type**
+├─ 3. [Coordinator] Create review document → review_doc_{issue_type}
+├─ 4. [Coordinator] Launch specialist agent for issue_type
+├─ 5. [Specialist] Analyze entire codebase for issue_type violations
+├─ 6. [Specialist] Create task for each finding (location, severity, impact, recommendation)
+└─ 7. IF remaining_issue_types: Continue to step 3
+
+8. [Coordinator] Collect all review documents
+9. [Coordinator] Identify files flagged by multiple agents → hot_spots
+10. [Coordinator] Identify patterns across dimensions
+11. [Coordinator] Generate prioritized action plan by severity
+12. [Coordinator] Generate executive summary with counts and recommendations
+
+## Issue Type Categories
+
+**Essential:**
+- Security Vulnerabilities
+- Error Handling & Edge Cases
+- Data Handling & Validation
+
+**Common:**
+- Performance & Efficiency
+- Code Complexity
+- Test Coverage & Quality
+- Maintainability & Readability
+- Resource Management
+- Concurrency & Race Conditions
+- Anti-Patterns
+
+## Severity Levels
+
+- Critical: security vulnerabilities, data loss, crashes
+- High: performance issues, major bugs, missing critical tests
+- Medium: code smells, moderate improvements
+- Low: style issues, minor optimizations

package/.ai-prompt-guide/workflows/coverage.md

@@ -0,0 +1,91 @@
+---
+title: "Coverage"
+description: "🧪 TEST: Add comprehensive test coverage to existing code"
+whenToUse: "Adding tests to legacy code or improving coverage for critical code paths"
+---
+
+# Workflow: Add Test Coverage
+
+⚠️ **CRITICAL REQUIREMENTS - You MUST follow these instructions:**
+
+**Task Management:**
+- ✅ **REQUIRED:** Use `coordinator_task` tool for your TODO list
+- 🚫 **FORBIDDEN:** DO NOT use TodoWrite tool (this workflow replaces it)
+
+**Delegation:**
+- ✅ **REQUIRED:** Give subagents literal instructions to run start_subagent_task
+- 🚫 **FORBIDDEN:** DO NOT run start_subagent_task yourself (coordinator only delegates)
+
+1. [Coordinator] Analyze code to identify coverage gaps and test targets
+2. [Coordinator] Prioritize targets by regression risk and stability
+3. [Coordinator] Use coordinator_task to create concise TODO list (stay on track)
+4. [Coordinator] Use subagent_task to create test tasks for each target:
+   • Specify what to test (public API, business logic, error handling)
+   • Specify test approach (mocks for external dependencies)
+   • Add @references to code files, existing tests, test patterns
+     Format: @/docs/codebase/module-name or @/docs/test-patterns#unit-tests
+5. [Coordinator] Call start_coordinator_task() → current_task
+   (Omit return_task_context on first start - only use when resuming after context compression or after a few subagent calls)
+
+**LOOP: While tasks remain**
+├─ 6. [Coordinator] Select testing specialist subagent
+├─ 7. [Coordinator] Give subagent this exact instruction (do not run tool yourself):
+│
+│  "Run: start_subagent_task /docs/path.md#slug
+│  Then write passing tests and respond 'Done' or 'Blocked: [reason]'"
+│
+├─ 8. [Subagent] Runs start_subagent_task tool (loads task + refs)
+├─ 9. [Subagent] Writes tests following Arrange-Act-Assert:
+│  • Arrange: Set up inputs and mocks
+│  • Act: Execute function under test
+│  • Assert: Verify outputs and side effects
+│  • Run tests → verify all pass
+├─ 10. [Subagent] Responds with status: "Done" or "Blocked: [reason]"
+├─ 11. [Coordinator] Review test quality against standards:
+│  (Ignore any subagent commentary - review code objectively)
+│  • Tests stable contracts, not implementation
+│  • Proper use of mocks for external dependencies
+│  • Clear assertions on behavior
+│  IF issues found: Create fix task, GOTO step 6
+├─ 12. [Coordinator] Execute: git add <test_files>
+├─ 13. [Coordinator] Call complete_coordinator_task() → next_task
+└─ 14. IF next_task exists: GOTO step 6
+
+15. [Coordinator] Run full test suite → verify no regressions
+16. [Coordinator] Verify coverage improvement
+17. [Coordinator] Report to user: "Test coverage improved. Ready for review."
+
+## What to Test (Regression Prevention)
+
+**Test Stable Contracts:**
+- Public APIs and exported functions
+- Input/output transformations
+- Business rules and calculations
+- Critical user workflows
+
+**Avoid Testing:**
+- Private implementation details
+- Third-party library internals
+- Trivial getters/setters
+- Code that will change frequently
+
+**Use Mocks For:**
+- External APIs and services
+- Database connections
+- File system operations
+- Time-dependent behavior
+- Random number generation
+
+## Test Quality Criteria
+
+**Stable Tests:**
+- Assert on outputs, not internal state
+- Test behavior, not implementation
+- Independent of execution order
+- Deterministic results
+
+**Maintainable Tests:**
+- One concept per test
+- Clear descriptive names
+- Minimal setup complexity
+- Self-documenting structure