ai-prompt-guide-mcp 1.0.2 → 1.0.3

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

@@ -0,0 +1,124 @@
+---
+title: "Develop"
+description: "🔨 DEVELOP: Simple development with anti-pattern detection and regression prevention"
+whenToUse: "Single-file or small scope features without needing multi-agent coordination, especially frontend work"
+---
+
+# Workflow: Simple Development with Best Practices
+
+⚠️ **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)
+
+1. [Agent] Analyze requirements and write out your understanding:
+   • What is the goal? (feature, enhancement, modification)
+   • What is the expected behavior?
+   • What files/components will be affected?
+   • What should NOT change?
+
+2. [Agent] Define scope boundaries explicitly:
+   • List files that WILL change
+   • List files that will NOT change (but might be related)
+   • Identify dependencies between components
+   • Document change scope limits
+
+3. [Agent] Scan existing code in change area for anti-patterns:
+   • Check against anti-pattern categories (see below)
+   • Note any problematic patterns found
+   • Flag for potential refactoring (if in scope)
+
+4. [Agent] IF multiple implementation approaches exist:
+   • Use decide workflow to evaluate approaches
+   • Prioritize: correctness > best practices > simplicity
+   • Select approach that aligns with existing patterns
+   ELSE:
+   • Proceed with single clear approach
+
+5. [Agent] Use coordinator_task to create TODO list:
+   • Break work into specific, testable steps
+   • Each task should be verifiable
+   • Keep scope aligned with step 2 boundaries
+
+6. [Agent] Implement changes following best practices:
+   • Follow existing code conventions
+   • Apply anti-pattern avoidance (see below)
+   • Add clear comments for complex logic
+   • Keep changes minimal and focused
+
+7. [Agent] Verify implementation:
+   • Test the new/changed functionality works correctly
+   • Test related functionality still works (regression check)
+   • Verify unchanged areas remain unchanged
+   • Check for edge cases and error handling
+
+8. [Agent] Add clarifying comments to code:
+   • Document non-obvious patterns or logic
+   • Explain WHY certain approaches were chosen
+   • Note edge cases or constraints
+   • Help prevent future regression when code is modified
+
+9. [Agent] Document findings:
+   • List any anti-patterns discovered
+   • Note any technical debt created/removed
+   • Suggest architecture improvements if design issues found
+   • Recommend follow-up improvements (outside current scope)
+
+10. [Agent] Report completion:
+   • Summary of changes made
+   • Files modified
+   • Anti-patterns addressed/flagged
+   • Regression test results
+   • Suggested improvements for future
+
+## Anti-Pattern Detection
+
+**Common Anti-Patterns:**
+
+*Code Organization:*
+- ❌ Magic numbers/strings, copy-paste code, deep nesting (>3 levels), multi-purpose functions
+- ✅ Named constants, DRY principle, flat logic, single responsibility
+
+*State & Data:*
+- ❌ State in wrong location, duplicate state, mutable shared state, implicit dependencies
+- ✅ State at appropriate level, single source of truth, immutable updates, explicit dependencies
+
+*Error Handling:*
+- ❌ Silent failures, generic messages, missing edge case handling, unchecked null/undefined
+- ✅ Explicit handling, clear messages, defensive programming
+
+*Side Effects & Timing:*
+- ❌ Side effects in wrong places, missing cleanup, race conditions, resource leaks
+- ✅ Proper lifecycle management, cleanup, synchronization handling
+
+*Component/Module Design:*
+- ❌ God objects, tight coupling, mixed responsibilities, unclear boundaries
+- ✅ Single responsibility, loose coupling, clear separation of concerns
+
+## Regression Prevention
+
+**Test Scope:**
+1. **Primary:** Changed functionality works as expected
+2. **Secondary:** Related functionality still works
+3. **Tertiary:** Adjacent features unaffected
+4. **Boundary:** Edge cases and error conditions handled
+
+## Scope Management
+
+**Minimal Change Principle:**
+- Only modify what's necessary to achieve the goal
+- Resist urge to refactor unrelated code
+- Keep changes focused and verifiable
+- Document broader improvements for future work
+
+**Change Boundary Definition:**
+- **In Scope:** Direct requirements, related fixes, necessary updates
+- **Out of Scope:** Nice-to-have improvements, unrelated refactoring, performance optimizations (unless required)
+- **Adjacent:** Closely related code that may need updates for consistency
+
+**Impact Analysis:**
+- What depends on what you're changing?
+- What uses the modified functionality?
+- What side effects might occur?
+- What tests/validations are needed?

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

@@ -0,0 +1,51 @@
+---
+title: "Review"
+description: "🔍 REVIEW: Targeted review of specific changes, PRs, or components"
+whenToUse: "Reviewing pull requests, specific changes, or individual modules before merge"
+---
+
+# Workflow: Code Review
+
+1. [Reviewer] Define review scope:
+   • Pull request or commit range
+   • Specific files or modules
+   • Focused area or component
+
+2. [Reviewer] Review across quality dimensions:
+   • Correctness: logic accuracy, edge cases, error handling
+   • Code Quality: readability, maintainability, naming
+   • Testing: coverage, assertions, edge cases
+   • Security: validation, auth, sensitive data handling
+   • Performance: efficiency, resource usage
+   • Pattern Consistency: aligns with codebase conventions
+
+3. [Reviewer] Identify issues by severity:
+   • Critical: security vulnerabilities, data loss risks, breaking changes
+   • High: performance issues, major logic errors, missing critical tests
+   • Medium: code smells, moderate improvements, minor bugs
+   • Low: style inconsistencies, minor optimizations, naming
+
+4. [Reviewer] Provide actionable feedback per finding:
+   • Location (file:line)
+   • Clear description and impact
+   • Concrete recommendation
+   • Code examples (if applicable)
+
+5. [Reviewer] Summarize findings:
+   • Overall assessment (approve/request changes/comment)
+   • Count by severity
+   • Priority recommendations
+   • Blocking vs non-blocking items
+
+## Review Focus
+
+**Prioritize:**
+- Correctness and security
+- Maintainability impact
+- Changed code (not unchanged)
+
+**Provide:**
+- Specific, actionable feedback
+- Explain "why" behind suggestions
+- Acknowledge good practices
+- Timely feedback

package/.ai-prompt-guide/workflows/spec-external.md

@@ -0,0 +1,50 @@
+---
+title: "Spec External"
+description: "📋 SPEC: Document 3rd party APIs/components from official sources"
+whenToUse: "Integrating SDKs, webhooks, auth flows, or documenting external service contracts"
+---
+
+# Workflow: Document External API Specification
+
+1. [Agent] Identify authoritative sources:
+   • Official documentation, API references, RFCs
+   • Versions relevant to runtime/environment
+   • Verify current and accurate (not third-party tutorials)
+
+2. [Agent] Extract complete API contract:
+   • Capabilities: supported features, limitations
+   • Invariants: must-hold conditions
+   • Limits: rate limits, size limits, timeouts
+   • Error semantics: codes, formats, retry policies
+   • Version gates: feature availability per version
+   • Authentication/authorization requirements
+
+3. [Agent] Use create_document to create specification document
+
+4. [Agent] Use section tool to add specification sections:
+   • Endpoints/methods with full signatures
+   • Request/response formats with examples
+   • Error conditions and handling
+   • Rate limits and quotas
+   • Authentication flows
+   • Version compatibility matrix
+
+5. [Agent] Document integration acceptance criteria:
+   • Happy path: normal expected behavior
+   • Edge cases: boundaries, limits, unusual inputs
+   • Error handling: all specified error conditions
+   • Performance boundaries: latency/throughput requirements
+
+## Specification Principles
+
+**Correctness Priority:**
+- Official documentation is source of truth
+- Spec compliance before simplicity
+- Test against specification, not assumptions
+- Verify examples from official docs
+
+**Documentation Quality:**
+- Complete API surface coverage
+- Clear examples for common use cases
+- Comprehensive error documentation
+- Version-specific notes where applicable

package/.ai-prompt-guide/workflows/spec-feature.md

@@ -0,0 +1,74 @@
+---
+title: "Spec Feature"
+description: "📋 SPEC: Document internal feature specification"
+whenToUse: "Defining requirements, API contracts, or acceptance criteria for new internal features"
+---
+
+# Workflow: Document Internal Feature Specification
+
+1. [Agent] Gather initial requirements from user:
+   • Feature purpose and goals
+   • User-facing behavior expectations
+   • Key use cases
+   • Priorities
+
+2. [Agent] Analyze requirements for gaps and ambiguities:
+   • Unclear user flows or interactions
+   • Missing UX details (inputs, outputs, feedback)
+   • Undefined edge cases or error scenarios
+   • Ambiguous feature scope or boundaries
+
+**LOOP: While gaps or ambiguities exist**
+├─ 3. [Agent] Ask user clarifying questions:
+│  • UX details: How should users interact with this?
+│  • Requirements: What happens when X occurs?
+│  • Edge cases: How should system handle Y?
+│  • Priorities: Which aspects are most critical?
+├─ 4. [Agent] Use decide workflow for technical decisions:
+│  • Implementation approach
+│  • Data structures and storage
+│  • Integration patterns
+│  • Performance and security requirements
+│  • Technical trade-offs
+├─ 5. [Agent] Update requirements understanding
+└─ 6. IF gaps remain: GOTO step 3
+
+7. [Agent] Use create_document to create specification document
+
+8. [Agent] Use section tool to add complete specification:
+   • Feature overview and rationale
+   • Detailed functionality description
+   • API endpoints/methods with signatures
+   • Request/response formats with examples
+   • Error conditions and messages
+   • Edge cases and boundary conditions
+   • Performance and security requirements
+   • Add @references to external API specs (if integrating third-party services)
+     Format: @/docs/specs/external-api-name or @/docs/specs/external-api#endpoint
+
+9. [Agent] Document acceptance criteria:
+   • Happy path: normal expected behavior
+   • Edge cases: boundaries, limits, unusual inputs
+   • Error handling: all error conditions
+   • Performance boundaries: latency/throughput requirements
+   • Security requirements: authentication, authorization, validation
+
+10. [Agent] Document selected implementation approach from decide workflow
+
+## Specification Principles
+
+**Gap Analysis:**
+- Identify unclear or missing requirements early
+- Ask questions to avoid assumptions
+- Clarify UX and user expectations with user
+- Make technical decisions independently using decide workflow
+
+**User vs Agent Decisions:**
+- User decides: UX, feature scope, priorities, business rules
+- Agent decides: Implementation, data structures, patterns, performance, security, technical trade-offs
+
+**Clarity:**
+- Clear, unambiguous requirements
+- Complete coverage of functionality
+- Specific, measurable acceptance criteria
+- No assumptions without validation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-prompt-guide-mcp",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "MCP server for markdown CRUD operations on specification documents",
   "type": "module",
   "main": "dist/index.js",
@@ -45,6 +45,8 @@
   },
   "files": [
     "dist",
+    ".ai-prompt-guide/workflows",
+    ".ai-prompt-guide/guides",
     "README.md",
     "LICENSE",
     "package.json"