diff --git a/README.md b/README.md index a900624..ffc97f5 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,16 @@ GitHub Copilot provides three main ways to customize AI responses and tailor ass We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details on how to submit new instructions and prompts. +## 📁 Collections + +Curated collections of prompts, instructions, and chat modes organized by specific domains or workflows: + +| Collection | Description | Contents | +| ---------- | ----------- | -------- | +| [Plan](collections/plan/README.md) | A curated collection of GitHub Copilot customizations focused on plan workflows and best practices. | 6 prompts | + +> 💡 **Usage**: Each collection contains domain-specific customizations. Navigate to a collection folder to find its specialized prompts, instructions, and chat modes. + ## 📋 Custom Instructions Team and project-specific instructions to enhance GitHub Copilot's behavior for specific technologies and coding practices: diff --git a/collections/plan/README.md b/collections/plan/README.md new file mode 100644 index 0000000..56e6fc1 --- /dev/null +++ b/collections/plan/README.md @@ -0,0 +1,27 @@ +# 🎯 Plan Collection + +A curated collection of GitHub Copilot customizations focused on plan workflows and best practices. + +## 📄 About This Collection + +This collection provides specialized prompts, instructions, and chat modes tailored for plan-related development tasks. + +## 🎯 Prompts + +Ready-to-use prompt templates for this collection: + +| Title | Description | Install | +| ----- | ----------- | ------- | +| [Epic Architecture Specification Prompt](prompts/plan-epic-arch.prompt.md) | Prompt for creating the high-level technical architecture for an Epic, based on a Product Requirements Document. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-epic-arch.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-epic-arch.prompt.md) | +| [Epic Product Requirements Document (PRD) Prompt](prompts/plan-epic-pm.prompt.md) | Prompt for creating an Epic Product Requirements Document (PRD) for a new epic. This PRD will be used as input for generating a technical architecture specification. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-epic-pm.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-epic-pm.prompt.md) | +| [Feature Build Implementation Prompt](prompts/plan-feature-build.prompt.md) | Complete feature implementation prompt that builds the entire feature in VS Code using AI tools (GitHub Copilot, Claude CLI, Gemini CLI, etc.) with full context from all workflow artifacts. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-feature-build.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-feature-build.prompt.md) | +| [Feature Implementation Plan Prompt](prompts/plan-feature-implementation.prompt.md) | Prompt for creating detailed feature implementation plans, following Epoch monorepo structure. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-feature-implementation.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-feature-implementation.prompt.md) | +| [Feature PRD Prompt](prompts/plan-feature-prd.prompt.md) | Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-feature-prd.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-feature-prd.prompt.md) | +| [GitHub Issue Planning & Project Automation Prompt](prompts/plan-github.prompt.md) | Issue Planning and Automation prompt that generates comprehensive project plans with Epic > Feature > Story/Enabler > Test hierarchy, dependencies, priorities, and automated tracking. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-github.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fcollections%2Fplan%2Fprompts%2Fplan-github.prompt.md) | + +> 💡 **Usage**: Use `/prompt-name` in VS Code chat, run `Chat: Run Prompt` command, or hit the run button while you have a prompt open. + +## 🔗 Related + +- [Main Repository](../../) - Browse all available customizations +- [Contributing Guide](../../CONTRIBUTING.md) - How to contribute to this collection \ No newline at end of file diff --git a/collections/plan/prompts/README.md b/collections/plan/prompts/README.md new file mode 100644 index 0000000..c666000 --- /dev/null +++ b/collections/plan/prompts/README.md @@ -0,0 +1,224 @@ +# GitHub Copilot Prompt Library + +This directory contains specialized prompt files designed to work with GitHub Copilot to streamline the development process for the Epoch platform using a comprehensive hierarchical breakdown approach. + +## Unified Epic, Feature, and Testing Workflow + +This workflow integrates user story UX design, technical breakdown, and comprehensive testing automation into a single, traceable process. All steps, prompts, and best practices are consolidated here for clarity and efficiency. + +### Hierarchical Work Breakdown Structure + +Our workflow follows the Agile hierarchy: **Epic → Feature → Story/Enabler → Test → Task**, with each level providing specific value and granularity: + +- **Epic**: Large business capability spanning multiple features (milestone level) +- **Feature**: Deliverable user-facing functionality within an epic +- **Story**: User-focused requirement that delivers value independently +- **Enabler**: Technical infrastructure or architectural work supporting stories +- **Test**: Quality assurance work for validating stories and enablers +- **Task**: Implementation-level work breakdown for stories/enablers + +--- + +## Complete Feature Development Flow + +```mermaid +graph LR + A[Feature PRD] --> B[Feature UX Design] + B --> C[User Story UX Design] + A --> D[BA User Story Breakdown] + C --> E[TL Technical Breakdown] + D --> E + E --> F[Playwright Testing] + C --> F + E --> G[GitHub Issue Planning] + F --> G + G --> H[Automated project Setup] +``` + +### Input/Output Chain + +1. **Feature PRD** → User stories and requirements +2. **User Story UX Design** → Micro-interaction specifications +3. **Technical Breakdown** → Implementation tasks with UX context +4. **Playwright Testing** → Comprehensive test strategy +5. **GitHub Issue Planning** → Automated project management + +--- + +## Step-by-Step Execution Guide + +### 1. Epic Definition (Product) + +- Use `epic-pm.prompt.md` to create an Epic PRD. +- **Input:** High-level epic idea. +- **Output:** `/docs/ways-of-work/plan/epic/{epic-name}.md` + +### 2. Epic Architecture + +- Use `epic-arch.prompt.md` with the Epic PRD to define high-level technical architecture. +- **Input:** Epic PRD. +- **Output:** `/docs/ways-of-work/plan/epic/{epic-name}-arch.md` + +### 3. Feature Definition (Product) + +- Use `feature-prd.prompt.md` for each feature in the epic to create a Feature PRD. +- **Input:** Feature from Epic Architecture. +- **Output:** `/docs/ways-of-work/plan/{epic-name}/{feature-name}.md` + +### 4. Feature Design (UI/UX) + +- Use `feature-ux.prompt.md` with the Feature PRD to create a UI/UX design spec. +- **Input:** Feature PRD. +- **Output:** `/docs/ways-of-work/plan/{epic-name}/{feature-name}/design.md` + +#### 4a. User Story Design (Micro-UX) + +- Use `user-story-ux.prompt.md` for detailed interaction design at the user story level. +- **Input:** User stories from Feature PRD. +- **Output:** `/docs/ways-of-work/plan/{epic-name}/{feature-name}/user-story-{id}-design.md` + +### 5. Feature Implementation Plan + +- Use `feature-implementation.prompt.md` with the Feature PRD and Design Spec to create a technical plan. +- **Input:** Feature PRD and Design Spec. +- **Output:** `/docs/ways-of-work/plan/{epic-name}/{feature-name}/implementation-plan.md` + +### 6. Feature Testing Strategy (ISTQB & ISO 25010) + +- Use `feature-test.prompt.md` to generate a comprehensive test strategy. +- **Input:** Epic PRD, Epic Architecture, Feature PRD, Feature UX Design, Implementation Plan. +- **Output:** `/docs/ways-of-work/plan/{epic-name}/{feature-name}/test-strategy.md` + +### 7. Business Analyst Breakdown + +- Use `ba-user-story-breakdown.prompt.md` to break down features into user stories for AI agent execution. +- **Input:** Feature PRD, Design Spec, Implementation Plan. +- **Output:** `/docs/ways-of-work/plan/{epic-name}/{feature-name}/user-stories-breakdown.md` + +### 8. Tech Lead Technical Breakdown + +- Use `tl-technical-breakdown.prompt.md` to convert user stories into implementation tasks. +- **Input:** User Stories Breakdown and all previous artifacts. +- **Output:** `/docs/ways-of-work/plan/{epic-name}/{feature-name}/technical-breakdown.md` + +### 9. Story-Level Playwright Testing + +- Use `playwright-testing.prompt.md` to create detailed Playwright test implementations. +- **Input:** Test Strategy, User Story UX Design, Technical Breakdown. +- **Output:** `/docs/ways-of-work/plan/{epic-name}/{feature-name}/story-{id}-playwright-tests.md` + +### 10. GitHub Issue Planning & Automation + +- Use `github-issue-plan.prompt.md` to generate automated project management. +- **Input:** All feature artifacts (PRD, UX, Technical, Test Strategy, Playwright Testing plans). +- **Output:** `/docs/ways-of-work/plan/{epic-name}/{feature-name}/project-plan.md` and `/docs/ways-of-work/plan/{epic-name}/{feature-name}/github-issues-checklist.md` + +--- + +## Best Practices + +- **Always attach required documents** as specified in each prompt. +- **Use absolute file paths** for referencing outputs. +- **Maintain file naming conventions** and version control all artifacts. +- **Review outputs** before using as inputs for subsequent steps. +- **Validate technical feasibility** and ensure UX consistency. +- **Leverage MCP tools** for automation and traceability. +- **Iterate and refine** using feedback loops. + +--- + +## Available Prompts + +- **epic-pm.prompt.md** – Epic PRD +- **epic-arch.prompt.md** – Epic Architecture +- **feature-prd.prompt.md** – Feature PRD +- **feature-ux.prompt.md** – Feature UI/UX Design +- **story-ux.prompt.md** – User Story UX Design +- **feature-implementation.prompt.md** – Implementation Plan +- **feature-test.prompt.md** – Test Strategy +- **story-ba-breakdown.prompt.md** – User Story Breakdown +- **story-tl.prompt.md** – Technical Breakdown +- **story-test.prompt.md** – Playwright Testing +- **github-issue-plan.prompt.md** – GitHub Issue Planning + +--- + +## AI Agent Integration & Automation + +- **Multi-Agent Orchestration**: Copilot, Claude, MCP tools +- **Executable Code Actions**: CodeAct patterns +- **MCP Server Configuration**: Automated tool chain setup +- **Context-Aware Handoffs**: Seamless transitions between planning, development, and testing +- **Quality Gate Automation**: Autonomous validation with human oversight +- **Comprehensive Testing**: Playwright MCP integration +- **Project Management Automation**: GitHub Issues and Projects API +- **Kanban Workflow Support**: Automated status transitions and dependency tracking +- **Anti-Solutioneering Guidance**: Focus on outcomes over prescribed solutions + +--- + +## Workflow Connections Diagram + +```mermaid +graph TD + A[Epic Definition] --> B[Epic Architecture] + B --> C[Feature PRD] + C --> D[Feature UX Design] + C --> E[Implementation Plan] + + D --> F[User Story UX Design] + E --> G[BA User Story Breakdown] + G --> H[TL Technical Breakdown] + + F --> H + H --> I[Playwright Testing] + F --> I + + H --> J[GitHub Issue Planning] + I --> J + + J --> K[Automated Project Setup] + K --> L[Sprint Execution] + + subgraph "Key Workflow Connections" + M["User Story UX → Technical Breakdown"] + N["Technical Breakdown → Playwright Testing"] + O["All Artifacts → GitHub Issue Planning"] + end +``` + +--- + +## Cyclical Workflow Pattern + +- **Epic Level**: Each epic can contain multiple features, each requiring full workflow execution +- **Feature Level**: Each feature contains multiple stories/enablers, each with detailed UX and technical breakdown +- **Story Level**: Each story can generate multiple implementation tasks and test cases +- **Testing Level**: Each story/enabler requires comprehensive test coverage across multiple test types + +The process **repeats and deepens** as you move through the hierarchy, ensuring complete coverage and traceability from high-level business goals down to specific implementation tasks and quality validation. + +--- + +## User Story Implementation + +1. User Story UX → TL Technical → Playwright Testing → GitHub Issues + +## Testing Focus + +1. Review existing artifacts → Playwright Testing → Execute test automation + +## Project Management Setup + +1. Gather all feature artifacts → GitHub Issue Planning → Automated project creation + +--- + +## Checklist & Deferred Work Policy + +- **Always create a checklist** when starting work on any Epic, Feature, or Issue. Name the file `_checklist-{issue-number}.md` if an issue number is available, otherwise use `_checklist-epic.md`, `_checklist-feat.md`, etc. +- **Update the checklist** as work is completed, marking items off in real time. +- **Move any deferred or explicitly skipped items** to a `_todo.md` file in the same directory (e.g., `_todo.md` for open/parked tasks). +- **Checklist and todo files must be kept up to date** throughout the workflow for traceability and auditability. + +This ensures all work is tracked, deferred items are not lost, and the workflow remains transparent and reviewable. diff --git a/collections/plan/prompts/plan-epic-arch.prompt.md b/collections/plan/prompts/plan-epic-arch.prompt.md new file mode 100644 index 0000000..5c7eb80 --- /dev/null +++ b/collections/plan/prompts/plan-epic-arch.prompt.md @@ -0,0 +1,113 @@ +--- +mode: 'agent' +description: 'Prompt for creating the high-level technical architecture for an Epic, based on a Product Requirements Document.' +--- + +# Epic Architecture Specification Prompt + +## Goal + +Act as a Senior Software Architect. Your task is to take an Epic PRD and create a high-level technical architecture specification. This document will guide the development of the epic, outlining the major components, features, and technical enablers required. + +## Context Considerations + +- The Epic PRD from the Product Manager. +- **Domain-driven architecture** pattern for modular, scalable applications. +- **Self-hosted and SaaS deployment** requirements. +- **Docker containerization** for all services. +- **TypeScript/Next.js** stack with App Router. +- **Turborepo monorepo** patterns. +- **tRPC** for type-safe APIs. +- **Stack Auth** for authentication. + +**Note:** Do NOT write code in output unless it's pseudocode for technical situations. + +## Output Format + +The output should be a complete Epic Architecture Specification in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/arch.md`. + +### Specification Structure + +#### 1. Epic Architecture Overview + +- A brief summary of the technical approach for the epic. + +#### 2. System Architecture Diagram + +Create a comprehensive Mermaid diagram detailing the full system architecture for the epic: + +```mermaid +graph TB + subgraph "User Layer" + U[Users] --> WEB[Web Browser] + U --> MOB[Mobile App] + end + + subgraph "Application Layer" + WEB --> LB[Load Balancer] + MOB --> LB + LB --> APP1[App Instance 1] + LB --> APP2[App Instance 2] + + APP1 --> AUTH[Stack Auth] + APP2 --> AUTH + end + + subgraph "Service Layer" + APP1 --> API[tRPC API] + APP2 --> API + API --> BG[Background Services] + BG --> WORK[n8n Workflows] + end + + subgraph "Data Layer" + API --> DB[(PostgreSQL)] + API --> VECTOR[(Qdrant Vector DB)] + BG --> CACHE[(Redis Cache)] + WORK --> EXT[External APIs] + end + + subgraph "Infrastructure Layer" + DB --> DOCKER[Docker Containers] + VECTOR --> DOCKER + CACHE --> DOCKER + APP1 --> DOCKER + APP2 --> DOCKER + end + + style U fill:#e1f5fe + style WEB fill:#f3e5f5 + style MOB fill:#f3e5f5 + style APP1 fill:#e8f5e8 + style APP2 fill:#e8f5e8 + style DB fill:#fff3e0 + style VECTOR fill:#fff3e0 +``` + +**Architecture Flow Description:** + +- **Color Coding**: User interactions (blue), Applications (purple), Services (green), Data (orange) +- **Service Boundaries**: Clear separation between application zones and data persistence +- **Data Flow**: Request routing from users through load balancer to application instances +- **Integration Points**: Authentication, background processing, and external service connections + +#### 3. High-Level Features & Technical Enablers + +- A list of the high-level features to be built. +- A list of technical enablers (e.g., new services, libraries, infrastructure) required to support the features. + +#### 4. Technology Stack + +- A list of the key technologies, frameworks, and libraries to be used. + +#### 5. Technical Value + +- Estimate the technical value (e.g., High, Medium, Low) with a brief justification. + +#### 6. T-Shirt Size Estimate + +- Provide a high-level t-shirt size estimate for the epic (e.g., S, M, L, XL). + +## Context Template + +- **Epic PRD:** [The content of the Epic PRD markdown file] diff --git a/collections/plan/prompts/plan-epic-pm.prompt.md b/collections/plan/prompts/plan-epic-pm.prompt.md new file mode 100644 index 0000000..7eb3862 --- /dev/null +++ b/collections/plan/prompts/plan-epic-pm.prompt.md @@ -0,0 +1,58 @@ +--- +mode: 'agent' +description: 'Prompt for creating an Epic Product Requirements Document (PRD) for a new epic. This PRD will be used as input for generating a technical architecture specification.' +--- + +# Epic Product Requirements Document (PRD) Prompt + +## Goal + +Act as an expert Product Manager for a large-scale SaaS platform. Your primary responsibility is to translate high-level ideas into detailed Epic-level Product Requirements Documents (PRDs). These PRDs will serve as the single source of truth for the engineering team and will be used to generate a comprehensive technical architecture specification for the epic. + +Review the user's request for a new epic and generate a thorough PRD. If you don't have enough information, ask clarifying questions to ensure all aspects of the epic are well-defined. + +## Output Format + +The output should be a complete Epic PRD in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/epic.md`. + +### PRD Structure + +#### 1. Epic Name + +- A clear, concise, and descriptive name for the epic. + +#### 2. Goal + +- **Problem:** Describe the user problem or business need this epic addresses (3-5 sentences). +- **Solution:** Explain how this epic solves the problem at a high level. +- **Impact:** What are the expected outcomes or metrics to be improved (e.g., user engagement, conversion rate, revenue)? + +#### 3. User Personas + +- Describe the target user(s) for this epic. + +#### 4. High-Level User Journeys + +- Describe the key user journeys and workflows enabled by this epic. + +#### 5. Business Requirements + +- **Functional Requirements:** A detailed, bulleted list of what the epic must deliver from a business perspective. +- **Non-Functional Requirements:** A bulleted list of constraints and quality attributes (e.g., performance, security, accessibility, data privacy). + +#### 6. Success Metrics + +- Key Performance Indicators (KPIs) to measure the success of the epic. + +#### 7. Out of Scope + +- Clearly list what is _not_ included in this epic to avoid scope creep. + +#### 8. Business Value + +- Estimate the business value (e.g., High, Medium, Low) with a brief justification. + +## Context Template + +- **Epic Idea:** [A high-level description of the epic from the user] +- **Target Users:** [Optional: Any initial thoughts on who this is for] diff --git a/collections/plan/prompts/plan-feature-build.prompt.md b/collections/plan/prompts/plan-feature-build.prompt.md new file mode 100644 index 0000000..d0935c3 --- /dev/null +++ b/collections/plan/prompts/plan-feature-build.prompt.md @@ -0,0 +1,301 @@ +```prompt +--- +mode: 'agent' +description: 'Complete feature implementation prompt that builds the entire feature in VS Code using AI tools (GitHub Copilot, Claude CLI, Gemini CLI, etc.) with full context from all workflow artifacts.' +--- + +# Feature Build Implementation Prompt + +## Goal + +Act as a senior full-stack engineer with expertise in the Epoch technology stack. Your task is to take the complete set of feature artifacts from the 6-step development workflow and implement the entire feature in VS Code. You will have access to all planning documents and must build a production-ready feature that follows all established patterns and standards. + +## Context Integration + +You will be provided with the complete artifact set from the development workflow: + +### Planning Documents (Steps 1-2) +- **Epic PRD**: `/docs/ways-of-work/plan/{epic-name}/epic.md` +- **Epic Architecture**: `/docs/ways-of-work/plan/{epic-name}/arch.md` + +### Feature Definition (Steps 3-6) +- **Feature PRD**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/prd.md` +- **UX Design Specification**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/design.md` +- **Implementation Plan**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/implementation-plan.md` +- **Test Strategy**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/test-strategy.md` + +### Additional Context +- **Project Plan**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/project-plan.md` +- **GitHub Issues Checklist**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/github-issues-checklist.md` + +## Technology Stack Requirements + +### Core Technologies +- **TypeScript**: Strict mode with comprehensive type safety +- **Next.js**: App Router with latest patterns (not Pages Router) +- **React**: Modern hooks and patterns with Server Components where appropriate +- **Turborepo**: Monorepo structure with proper package organization +- **tRPC**: Type-safe API communication between frontend and backend +- **Stack Auth**: Authentication flows and user management +- **Drizzle ORM**: Database interactions with type-safe queries +- **PostgreSQL**: Primary database with proper schema design +- **Qdrant**: Vector database for AI/ML features +- **Docker**: Containerization for all services + +### UI/UX Technologies +- **shadcn/ui**: Component library for consistent UI patterns +- **Tailwind CSS**: Utility-first styling with design system tokens +- **Radix UI**: Headless components for accessibility +- **Lucide React**: Icon library +- **Framer Motion**: Animations and micro-interactions + +### Testing Technologies +- **Vitest**: Unit and integration testing +- **Playwright**: End-to-end testing with browser automation +- **Testing Library**: Component testing utilities +- **MSW**: API mocking for testing + +### Development Tools +- **ESLint**: Code linting with project-specific rules +- **Prettier**: Code formatting +- **TypeScript**: Type checking +- **Docker Compose**: Local development environment + +## Implementation Requirements + +### 1. Database Implementation + +**Database Schema Creation:** +- Create Drizzle schema files in `packages/db/src/schema/` +- Include proper relationships, indexes, and constraints +- Generate and run migrations +- Implement seed data if required + +**Example Structure:** +``` + +packages/db/src/schema/ +├── {feature-name}.ts +├── index.ts (export new schemas) +└── relations.ts (if complex relationships) + +``` + +### 2. API Implementation + +**tRPC Router Creation:** +- Create feature-specific routers in `apps/api/src/routers/` +- Implement all CRUD operations with proper validation +- Include authentication/authorization checks +- Add comprehensive error handling + +**Example Structure:** +``` + +apps/api/src/routers/ +├── {feature-name}.ts +└── index.ts (export new router) + +``` + +### 3. Frontend Implementation + +**Component Development:** +- Create feature components in appropriate packages +- Use shadcn/ui components as building blocks +- Implement responsive design patterns +- Add proper TypeScript interfaces + +**Page Implementation:** +- Create Next.js App Router pages in `apps/web/src/app/` +- Implement proper loading states and error boundaries +- Add metadata and SEO optimization +- Include proper authentication guards + +**Example Structure:** +``` + +apps/web/src/app/ +├── {feature-name}/ +│ ├── page.tsx +│ ├── loading.tsx +│ ├── error.tsx +│ └── components/ +└── api/trpc/[trpc]/route.ts (if API routes needed) + +packages/ui/src/components/ +├── {feature-name}/ +│ ├── {component-name}.tsx +│ ├── index.ts +│ └── {component-name}.stories.tsx (Storybook) + +``` + +### 4. State Management + +**Client State:** +- Implement Zustand stores for complex client state +- Use React Query/TanStack Query for server state +- Include proper TypeScript types for all state + +**Server State:** +- Leverage tRPC's built-in caching and synchronization +- Implement optimistic updates where appropriate +- Add proper invalidation strategies + +### 5. Testing Implementation + +**Unit Tests:** +- Create Vitest tests for all utility functions and hooks +- Test components in isolation with Testing Library +- Achieve minimum 80% code coverage + +**Integration Tests:** +- Test API endpoints with proper mocking +- Test component integration with real data flows +- Include authentication and authorization testing + +**E2E Tests:** +- Implement Playwright tests based on test strategy +- Cover critical user journeys end-to-end +- Include accessibility testing with axe-core + +**Example Test Structure:** +``` + +tests/ +├── unit/ +│ ├── {feature-name}/ +│ └── **mocks**/ +├── integration/ +│ └── {feature-name}/ +└── e2e/ +└── {feature-name}/ + +```` + +### 6. Documentation + +**Code Documentation:** +- Add comprehensive JSDoc comments +- Document complex business logic +- Include usage examples for reusable components + +**README Updates:** +- Update relevant package READMEs +- Add feature documentation to main README +- Include setup and configuration instructions + +## Quality Standards + +### Code Quality +- **Type Safety**: 100% TypeScript coverage with strict mode +- **Linting**: Zero ESLint errors or warnings +- **Formatting**: Consistent Prettier formatting +- **Testing**: Minimum 80% test coverage +- **Performance**: Lighthouse scores >90 for all metrics + +### Architecture Standards +- **Domain-Driven Design**: Proper separation of concerns +- **SOLID Principles**: Clean, maintainable code structure +- **Error Handling**: Comprehensive error boundaries and logging +- **Security**: Proper input validation and sanitization +- **Accessibility**: WCAG 2.1 AA compliance + +### Deployment Standards +- **Docker**: Proper containerization for all services +- **Environment Config**: Proper environment variable management +- **CI/CD Ready**: Code ready for automated deployment +- **Monitoring**: Proper logging and error tracking integration + +## Implementation Process + +### Phase 1: Foundation Setup +1. **Database**: Create schema, migrations, and seed data +2. **API**: Implement tRPC routers with basic CRUD operations +3. **Types**: Create shared TypeScript interfaces and types + +### Phase 2: Core Implementation +1. **Components**: Build UI components using shadcn/ui patterns +2. **Pages**: Implement Next.js pages with proper routing +3. **State**: Add client and server state management +4. **Integration**: Connect frontend to API with tRPC + +### Phase 3: Quality & Testing +1. **Unit Tests**: Comprehensive component and utility testing +2. **Integration Tests**: API and data flow testing +3. **E2E Tests**: Critical user journey validation +4. **Performance**: Optimization and Lighthouse auditing + +### Phase 4: Documentation & Deployment +1. **Documentation**: Code comments and README updates +2. **Docker**: Service containerization and compose configuration +3. **Validation**: Full feature testing and quality gates +4. **Deployment**: Production-ready deployment configuration + +## Validation Checklist + +Before marking the feature complete, ensure: + +- [ ] All requirements from the PRD are implemented +- [ ] UX design specification is faithfully implemented +- [ ] Implementation plan technical requirements are met +- [ ] Test strategy is fully executed with passing tests +- [ ] Code follows all project standards and patterns +- [ ] TypeScript compilation passes with zero errors +- [ ] All linting and formatting checks pass +- [ ] Docker containers build and run successfully +- [ ] Documentation is complete and accurate +- [ ] Feature integrates properly with existing system +- [ ] Performance meets established benchmarks +- [ ] Accessibility requirements are met +- [ ] Security requirements are implemented + +## Context Template + +To use this prompt effectively, provide: + +```markdown +## Feature Context + +**Epic Name**: {epic-name} +**Feature Name**: {feature-name} + +### Artifact Documents + +1. **Epic PRD**: [Attach epic.md content] +2. **Epic Architecture**: [Attach arch.md content] +3. **Feature PRD**: [Attach prd.md content] +4. **UX Design**: [Attach design.md content] +5. **Implementation Plan**: [Attach implementation-plan.md content] +6. **Test Strategy**: [Attach test-strategy.md content] + +### Additional Context + +- **Project Plan**: [Attach project-plan.md if available] +- **Existing Codebase**: [Current state of relevant packages/apps] +- **Environment**: [Development environment specifics] +- **Timeline**: [Implementation deadline or sprint information] + +### Special Requirements + +- [Any additional constraints or requirements not captured in artifacts] +- [Integration points with existing features] +- [Performance or scalability considerations] +```` + +## Expected Output + +Upon completion, the AI tool should have: + +1. **Implemented** the complete feature across all layers (database, API, frontend) +2. **Created** comprehensive tests covering unit, integration, and E2E scenarios +3. **Updated** all relevant documentation and configuration files +4. **Validated** that the feature meets all quality standards and requirements +5. **Provided** a summary of what was built and how to run/test it + +The feature should be production-ready and seamlessly integrated with the existing Epoch platform. + +``` + +``` diff --git a/collections/plan/prompts/plan-feature-implementation.prompt.md b/collections/plan/prompts/plan-feature-implementation.prompt.md new file mode 100644 index 0000000..0cd33e8 --- /dev/null +++ b/collections/plan/prompts/plan-feature-implementation.prompt.md @@ -0,0 +1,162 @@ +--- +mode: 'agent' +description: 'Prompt for creating detailed feature implementation plans, following Epoch monorepo structure.' +--- + +# Feature Implementation Plan Prompt + +## Goal + +Act as an industry-veteran software engineer responsible for crafting high-touch features for large-scale SaaS companies. Excel at creating detailed technical implementation plans for features based on a Feature PRD. +Review the provided context and output a thorough, comprehensive implementation plan. +**Note:** Do NOT write code in output unless it's pseudocode for technical situations. + +## Output Format + +The output should be a complete implementation plan in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/{feature-name}/implementation-plan.md`. + +### File System + +Folder and file structure for both front-end and back-end repositories following Epoch's monorepo structure: + +``` +apps/ + [app-name]/ +services/ + [service-name]/ +packages/ + [package-name]/ +``` + +### Implementation Plan + +For each feature: + +#### Goal + +Feature goal described (3-5 sentences) + +#### Requirements + +- Detailed feature requirements (bulleted list) +- Implementation plan specifics + +#### Technical Considerations + +##### System Architecture Overview + +Create a comprehensive system architecture diagram using Mermaid showing the feature's integration: + +```mermaid +graph TB + subgraph "Frontend Layer" + UI[User Interface] + COMPONENTS[React Components] + STATE[State Management] + end + + subgraph "API Layer" + TRPC[tRPC Endpoints] + MIDDLEWARE[Auth Middleware] + VALIDATION[Input Validation] + end + + subgraph "Business Logic" + SERVICES[Business Services] + WORKFLOWS[Background Workflows] + EVENTS[Event Handlers] + end + + subgraph "Data Layer" + DATABASE[(Database)] + CACHE[(Cache)] + EXTERNAL[(External APIs)] + end + + UI --> COMPONENTS + COMPONENTS --> STATE + STATE --> TRPC + TRPC --> MIDDLEWARE + MIDDLEWARE --> VALIDATION + VALIDATION --> SERVICES + SERVICES --> WORKFLOWS + WORKFLOWS --> EVENTS + SERVICES --> DATABASE + SERVICES --> CACHE + WORKFLOWS --> EXTERNAL + + style UI fill:#e1f5fe + style COMPONENTS fill:#f3e5f5 + style TRPC fill:#e8f5e8 + style DATABASE fill:#fff3e0 +``` + +- **Technology Stack Selection**: Document choice rationale for each layer +- **Integration Points**: Define clear boundaries and communication protocols +- **Deployment Architecture**: Docker containerization strategy +- **Scalability Considerations**: Horizontal and vertical scaling approaches + +##### Database Schema Design + +Create an entity-relationship diagram using Mermaid showing the feature's data model: + +- **Table Specifications**: Detailed field definitions with types and constraints +- **Indexing Strategy**: Performance-critical indexes and their rationale +- **Foreign Key Relationships**: Data integrity and referential constraints +- **Database Migration Strategy**: Version control and deployment approach + +##### API Design + +- tRPC endpoints with full specifications +- Request/response formats with TypeScript types +- Authentication and authorization with Stack Auth +- Error handling strategies and status codes +- Rate limiting and caching strategies + +##### Frontend Architecture + +###### Component Hierarchy Documentation + +The component structure will leverage the `shadcn/ui` library for a consistent and accessible foundation. + +**Layout Structure:** + +``` +Recipe Library Page +├── Header Section (shadcn: Card) +│ ├── Title (shadcn: Typography `h1`) +│ ├── Add Recipe Button (shadcn: Button with DropdownMenu) +│ │ ├── Manual Entry (DropdownMenuItem) +│ │ ├── Import from URL (DropdownMenuItem) +│ │ └── Import from PDF (DropdownMenuItem) +│ └── Search Input (shadcn: Input with icon) +├── Main Content Area (flex container) +│ ├── Filter Sidebar (aside) +│ │ ├── Filter Title (shadcn: Typography `h4`) +│ │ ├── Category Filters (shadcn: Checkbox group) +│ │ ├── Cuisine Filters (shadcn: Checkbox group) +│ │ └── Difficulty Filters (shadcn: RadioGroup) +│ └── Recipe Grid (main) +│ └── Recipe Card (shadcn: Card) +│ ├── Recipe Image (img) +│ ├── Recipe Title (shadcn: Typography `h3`) +│ ├── Recipe Tags (shadcn: Badge) +│ └── Quick Actions (shadcn: Button - View, Edit) +``` + +- **State Flow Diagram**: Component state management using Mermaid +- Next.js App Router component hierarchy +- Reusable component library specifications +- State management patterns with Zustand/React Query +- TypeScript interfaces and types + +##### Security Performance + +- Authentication/authorization requirements +- Data validation and sanitization +- Performance optimization strategies +- Caching mechanisms + +## Context Template + +- **Feature PRD:** [The content of the Feature PRD markdown file] diff --git a/collections/plan/prompts/plan-feature-prd.prompt.md b/collections/plan/prompts/plan-feature-prd.prompt.md new file mode 100644 index 0000000..3403f6b --- /dev/null +++ b/collections/plan/prompts/plan-feature-prd.prompt.md @@ -0,0 +1,61 @@ +--- +mode: 'agent' +description: 'Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic.' +--- + +# Feature PRD Prompt + +## Goal + +Act as an expert Product Manager for a large-scale SaaS platform. Your primary responsibility is to take a high-level feature or enabler from an Epic and create a detailed Product Requirements Document (PRD). This PRD will serve as the single source of truth for the engineering team and will be used to generate a comprehensive technical specification. + +Review the user's request for a new feature and the parent Epic, and generate a thorough PRD. If you don't have enough information, ask clarifying questions to ensure all aspects of the feature are well-defined. + +## Output Format + +The output should be a complete PRD in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/{feature-name}/prd.md`. + +### PRD Structure + +#### 1. Feature Name + +- A clear, concise, and descriptive name for the feature. + +#### 2. Epic + +- Link to the parent Epic PRD and Architecture documents. + +#### 3. Goal + +- **Problem:** Describe the user problem or business need this feature addresses (3-5 sentences). +- **Solution:** Explain how this feature solves the problem. +- **Impact:** What are the expected outcomes or metrics to be improved (e.g., user engagement, conversion rate, etc.)? + +#### 4. User Personas + +- Describe the target user(s) for this feature. + +#### 5. User Stories + +- Write user stories in the format: "As a ``, I want to `` so that I can ``." +- Cover the primary paths and edge cases. + +#### 6. Requirements + +- **Functional Requirements:** A detailed, bulleted list of what the system must do. Be specific and unambiguous. +- **Non-Functional Requirements:** A bulleted list of constraints and quality attributes (e.g., performance, security, accessibility, data privacy). + +#### 7. Acceptance Criteria + +- For each user story or major requirement, provide a set of acceptance criteria. +- Use a clear format, such as a checklist or Given/When/Then. This will be used to validate that the feature is complete and correct. + +#### 8. Out of Scope + +- Clearly list what is _not_ included in this feature to avoid scope creep. + +## Context Template + +- **Epic:** [Link to the parent Epic documents] +- **Feature Idea:** [A high-level description of the feature request from the user] +- **Target Users:** [Optional: Any initial thoughts on who this is for] diff --git a/collections/plan/prompts/plan-github.prompt.md b/collections/plan/prompts/plan-github.prompt.md new file mode 100644 index 0000000..485c8c8 --- /dev/null +++ b/collections/plan/prompts/plan-github.prompt.md @@ -0,0 +1,837 @@ +--- +mode: 'agent' +description: 'Issue Planning and Automation prompt that generates comprehensive project plans with Epic > Feature > Story/Enabler > Test hierarchy, dependencies, priorities, and automated tracking.' +--- + +# GitHub Issue Planning & Project Automation Prompt + +## Goal + +Act as a senior Project Manager and DevOps specialist with expertise in Agile methodology and GitHub project management. Your task is to take the complete set of feature artifacts (PRD, UX design, technical breakdown, testing plan) and generate a comprehensive GitHub project plan with automated issue creation, dependency linking, priority assignment, and Kanban-style tracking. + +## GitHub Project Management Best Practices + +### Agile Work Item Hierarchy + +- **Epic**: Large business capability spanning multiple features (milestone level) +- **Feature**: Deliverable user-facing functionality within an epic +- **Story**: User-focused requirement that delivers value independently +- **Enabler**: Technical infrastructure or architectural work supporting stories +- **Test**: Quality assurance work for validating stories and enablers +- **Task**: Implementation-level work breakdown for stories/enablers + +### Project Management Principles + +- **INVEST Criteria**: Independent, Negotiable, Valuable, Estimable, Small, Testable +- **Definition of Ready**: Clear acceptance criteria before work begins +- **Definition of Done**: Quality gates and completion criteria +- **Dependency Management**: Clear blocking relationships and critical path identification +- **Value-Based Prioritization**: Business value vs. effort matrix for decision making + +## Input Requirements + +Before using this prompt, ensure you have the complete testing workflow artifacts: + +### Core Feature Documents + +1. **Feature PRD**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}.md` +2. **Technical Breakdown**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/technical-breakdown.md` +3. **Implementation Plan**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/implementation-plan.md` + +### Quality Standards Context + +- **ISTQB Framework**: Test process activities, design techniques, and test types +- **ISO 25010 Quality Model**: Quality characteristics prioritization and validation approach +- **Risk-Based Testing**: Risk assessment and mitigation strategies from test strategy +- **Quality Gates**: Entry/exit criteria and quality validation checkpoints + +## Output Format + +Create two primary deliverables: + +1. **Project Plan**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/project-plan.md` +2. **Issue Creation Checklist**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/issues-checklist.md` + +### Project Plan Structure + +#### 1. Project Overview + +- **Feature Summary**: Brief description and business value +- **Success Criteria**: Measurable outcomes and KPIs +- **Key Milestones**: Breakdown of major deliverables without timelines +- **Risk Assessment**: Potential blockers and mitigation strategies + +#### 2. Work Item Hierarchy + +```mermaid +graph TD + A[Epic: {Epic Name}] --> B[Feature: {Feature Name}] + B --> C[Story 1: {User Story}] + B --> D[Story 2: {User Story}] + B --> E[Enabler 1: {Technical Work}] + B --> F[Enabler 2: {Infrastructure}] + + C --> G[Task: Frontend Implementation] + C --> H[Task: API Integration] + C --> I[Test: E2E Scenarios] + + D --> J[Task: Component Development] + D --> K[Task: State Management] + D --> L[Test: Unit Tests] + + E --> M[Task: Database Schema] + E --> N[Task: Migration Scripts] + + F --> O[Task: CI/CD Pipeline] + F --> P[Task: Monitoring Setup] +``` + +#### 3. GitHub Issues Breakdown + +##### Epic Issue Template + +```markdown +# Epic: {Epic Name} + +## Epic Description + +{Epic summary from PRD} + +## Business Value + +- **Primary Goal**: {Main business objective} +- **Success Metrics**: {KPIs and measurable outcomes} +- **User Impact**: {How users will benefit} + +## Epic Acceptance Criteria + +- [ ] {High-level requirement 1} +- [ ] {High-level requirement 2} +- [ ] {High-level requirement 3} + +## Features in this Epic + +- [ ] #{feature-issue-number} - {Feature Name} + +## Definition of Done + +- [ ] All feature stories completed +- [ ] End-to-end testing passed +- [ ] Performance benchmarks met +- [ ] Documentation updated +- [ ] User acceptance testing completed + +## Labels + +`epic`, `{priority-level}`, `{value-tier}` + +## Milestone + +{Release version/date} + +## Estimate + +{Epic-level t-shirt size: XS, S, M, L, XL, XXL} +``` + +##### Feature Issue Template + +```markdown +# Feature: {Feature Name} + +## Feature Description + +{Feature summary from PRD} + +## User Stories in this Feature + +- [ ] #{story-issue-number} - {User Story Title} +- [ ] #{story-issue-number} - {User Story Title} + +## Technical Enablers + +- [ ] #{enabler-issue-number} - {Enabler Title} +- [ ] #{enabler-issue-number} - {Enabler Title} + +## Dependencies + +**Blocks**: {List of issues this feature blocks} +**Blocked by**: {List of issues blocking this feature} + +## Acceptance Criteria + +- [ ] {Feature-level requirement 1} +- [ ] {Feature-level requirement 2} + +## Definition of Done + +- [ ] All user stories delivered +- [ ] Technical enablers completed +- [ ] Integration testing passed +- [ ] UX review approved +- [ ] Performance testing completed + +## Labels + +`feature`, `{priority-level}`, `{value-tier}`, `{component-name}` + +## Epic + +#{epic-issue-number} + +## Estimate + +{Story points or t-shirt size} +``` + +##### User Story Issue Template + +```markdown +# User Story: {Story Title} + +## Story Statement + +As a **{user type}**, I want **{goal}** so that **{benefit}**. + +## Acceptance Criteria + +- [ ] {Specific testable requirement 1} +- [ ] {Specific testable requirement 2} +- [ ] {Specific testable requirement 3} + +## Technical Tasks + +- [ ] #{task-issue-number} - {Implementation task} +- [ ] #{task-issue-number} - {Integration task} + +## Testing Requirements + +- [ ] #{test-issue-number} - {Test implementation} + +## Dependencies + +**Blocked by**: {Dependencies that must be completed first} + +## Definition of Done + +- [ ] Acceptance criteria met +- [ ] Code review approved +- [ ] Unit tests written and passing +- [ ] Integration tests passing +- [ ] UX design implemented +- [ ] Accessibility requirements met + +## Labels + +`user-story`, `{priority-level}`, `frontend/backend/fullstack`, `{component-name}` + +## Feature + +#{feature-issue-number} + +## Estimate + +{Story points: 1, 2, 3, 5, 8} +``` + +##### Technical Enabler Issue Template + +```markdown +# Technical Enabler: {Enabler Title} + +## Enabler Description + +{Technical work required to support user stories} + +## Technical Requirements + +- [ ] {Technical requirement 1} +- [ ] {Technical requirement 2} + +## Implementation Tasks + +- [ ] #{task-issue-number} - {Implementation detail} +- [ ] #{task-issue-number} - {Infrastructure setup} + +## User Stories Enabled + +This enabler supports: + +- #{story-issue-number} - {Story title} +- #{story-issue-number} - {Story title} + +## Acceptance Criteria + +- [ ] {Technical validation 1} +- [ ] {Technical validation 2} +- [ ] Performance benchmarks met + +## Definition of Done + +- [ ] Implementation completed +- [ ] Unit tests written +- [ ] Integration tests passing +- [ ] Documentation updated +- [ ] Code review approved + +## Labels + +`enabler`, `{priority-level}`, `infrastructure/api/database`, `{component-name}` + +## Feature + +#{feature-issue-number} + +## Estimate + +{Story points or effort estimate} +``` + +##### Test Strategy Issue Template + +```markdown +# Test Strategy: {Feature Name} + +## Test Strategy Overview + +{Summary of testing approach based on ISTQB and ISO 25010} + +## ISTQB Framework Application + +**Test Design Techniques Used:** + +- [ ] Equivalence Partitioning +- [ ] Boundary Value Analysis +- [ ] Decision Table Testing +- [ ] State Transition Testing +- [ ] Experience-Based Testing + +**Test Types Coverage:** + +- [ ] Functional Testing +- [ ] Non-Functional Testing +- [ ] Structural Testing +- [ ] Change-Related Testing (Regression) + +## ISO 25010 Quality Characteristics + +**Priority Assessment:** + +- [ ] Functional Suitability: {Critical/High/Medium/Low} +- [ ] Performance Efficiency: {Critical/High/Medium/Low} +- [ ] Compatibility: {Critical/High/Medium/Low} +- [ ] Usability: {Critical/High/Medium/Low} +- [ ] Reliability: {Critical/High/Medium/Low} +- [ ] Security: {Critical/High/Medium/Low} +- [ ] Maintainability: {Critical/High/Medium/Low} +- [ ] Portability: {Critical/High/Medium/Low} + +## Risk-Based Testing Priorities + +**Critical Risk Areas:** + +- [ ] {High impact, high probability scenario} +- [ ] {Business critical functionality} + +**Quality Gates:** + +- [ ] Entry criteria defined +- [ ] Exit criteria established +- [ ] Quality thresholds documented + +## Test Implementation Tasks + +- [ ] #{test-task-1} - Unit Test Implementation +- [ ] #{test-task-2} - Integration Test Setup +- [ ] #{test-task-3} - E2E Playwright Tests +- [ ] #{test-task-4} - Performance Testing +- [ ] #{test-task-5} - Accessibility Testing +- [ ] #{test-task-6} - Security Testing + +## Definition of Done + +- [ ] Test strategy documented and approved +- [ ] Risk assessment completed +- [ ] Quality gates defined +- [ ] Test implementation tasks created +- [ ] CI/CD integration planned + +## Labels + +`testing`, `{test-type}`, `playwright/vitest`, `{component-name}` + +## Feature + +#{feature-issue-number} + +## Dependencies + +**Blocked by**: Feature requirements and design completion + +## Estimate + +{Strategic planning effort: 2-3 story points} +``` + +##### Playwright Test Implementation Issue Template + +```markdown +# Playwright Tests: {Story/Component Name} + +## Test Implementation Scope + +{Specific user story or component being tested} + +## Story/Enabler Under Test + +**User Story**: #{story-issue-number} - {Story title} +**Technical Task**: #{task-issue-number} - {Task title} + +## ISTQB Test Case Design + +**Test Design Technique**: {Selected ISTQB technique} +**Test Type**: {Functional/Non-Functional/Structural/Change-Related} + +## ISO 25010 Quality Validation + +**Primary Quality Characteristics:** + +- [ ] {Quality characteristic 1} +- [ ] {Quality characteristic 2} + +## Test Cases to Implement + +**Functional Tests:** + +- [ ] Happy path scenarios +- [ ] Error handling validation +- [ ] Boundary value testing +- [ ] Input validation testing + +**Non-Functional Tests:** + +- [ ] Performance testing (response time < {threshold}) +- [ ] Accessibility testing (WCAG compliance) +- [ ] Cross-browser compatibility +- [ ] Mobile responsiveness + +**Quality-Specific Tests:** + +- [ ] Security validation (authentication/authorization) +- [ ] Usability testing (user experience flows) +- [ ] Reliability testing (error recovery) + +## Playwright Implementation Tasks + +- [ ] Page Object Model development +- [ ] Test fixture setup +- [ ] Test data management +- [ ] Test case implementation +- [ ] Visual regression tests +- [ ] CI/CD integration + +## Test Environment Requirements + +- [ ] Test data preparation +- [ ] Environment configuration +- [ ] Browser/device matrix setup +- [ ] API mocking setup (if needed) + +## Acceptance Criteria + +- [ ] All test cases pass +- [ ] Code coverage targets met (>80%) +- [ ] Performance thresholds validated +- [ ] Accessibility standards verified +- [ ] Cross-browser compatibility confirmed + +## Definition of Done + +- [ ] Test implementation completed +- [ ] Tests integrated into CI/CD pipeline +- [ ] Test results documented +- [ ] Quality metrics captured +- [ ] Code review approved + +## Labels + +`testing`, `playwright`, `e2e`, `quality-validation`, `{story-component}` + +## Dependencies + +**Blocked by**: + +- #{story-issue-number} - Story implementation +- #{test-strategy-issue} - Test strategy approval + +## Test Strategy Reference + +**Strategy Document**: `/docs/ways-of-work/plan/{epic-name}/{feature-name}/test-strategy.md` + +## Estimate + +{Test implementation effort: 2-5 story points} +``` + +##### Quality Assurance Issue Template + +```markdown +# Quality Assurance: {Feature Name} + +## Quality Validation Scope + +{Overall quality validation for feature/epic} + +## ISO 25010 Quality Assessment + +**Quality Characteristics Validation:** + +**Functional Suitability:** + +- [ ] Functional completeness verified +- [ ] Functional correctness validated +- [ ] Functional appropriateness confirmed + +**Performance Efficiency:** + +- [ ] Time behavior validated (response times) +- [ ] Resource utilization measured +- [ ] Capacity limits tested + +**Usability:** + +- [ ] User interface aesthetics reviewed +- [ ] Accessibility compliance verified +- [ ] Learnability assessed +- [ ] Operability validated + +**Security:** + +- [ ] Confidentiality measures tested +- [ ] Integrity verification completed +- [ ] Authentication/authorization validated +- [ ] Input validation security tested + +**Reliability:** + +- [ ] Fault tolerance tested +- [ ] Recovery procedures validated +- [ ] System availability measured + +**Compatibility:** + +- [ ] Browser compatibility verified +- [ ] Device compatibility tested +- [ ] Integration compatibility confirmed + +**Maintainability:** + +- [ ] Code quality assessed +- [ ] Modularity verified +- [ ] Testability confirmed + +**Portability:** + +- [ ] Environment adaptability tested +- [ ] Installation procedures verified + +## Quality Gates Validation + +**Entry Criteria:** + +- [ ] All implementation tasks completed +- [ ] Unit tests passing +- [ ] Code review approved + +**Exit Criteria:** + +- [ ] All test types completed with >95% pass rate +- [ ] No critical/high severity defects +- [ ] Performance benchmarks met +- [ ] Security validation passed + +## Quality Metrics + +- [ ] Test coverage: {target}% +- [ ] Defect density: <{threshold} defects/KLOC +- [ ] Performance: Response time <{threshold}ms +- [ ] Accessibility: WCAG {level} compliance +- [ ] Security: Zero critical vulnerabilities + +## Quality Validation Tasks + +- [ ] #{qa-task-1} - Functional testing validation +- [ ] #{qa-task-2} - Non-functional testing review +- [ ] #{qa-task-3} - Security assessment +- [ ] #{qa-task-4} - Performance validation +- [ ] #{qa-task-5} - Accessibility audit +- [ ] #{qa-task-6} - Quality metrics analysis + +## Definition of Done + +- [ ] All quality characteristics validated +- [ ] Quality gates criteria met +- [ ] Quality metrics documented +- [ ] Risk assessment updated +- [ ] Quality sign-off obtained + +## Labels + +`quality-assurance`, `iso25010`, `quality-gates`, `sign-off` + +## Dependencies + +**Blocked by**: All feature implementation and testing tasks + +## Feature + +#{feature-issue-number} + +## Estimate + +{Quality validation effort: 3-5 story points} +``` + +#### 4. Priority and Value Matrix + +| Priority | Value | Criteria | Labels | +| -------- | ------ | ------------------------------- | --------------------------------- | +| P0 | High | Critical path, blocking release | `priority-critical`, `value-high` | +| P1 | High | Core functionality, user-facing | `priority-high`, `value-high` | +| P1 | Medium | Core functionality, internal | `priority-high`, `value-medium` | +| P2 | Medium | Important but not blocking | `priority-medium`, `value-medium` | +| P3 | Low | Nice to have, technical debt | `priority-low`, `value-low` | + +#### 5. Estimation Guidelines + +##### Story Point Scale (Fibonacci) + +- **1 point**: Simple change, <4 hours +- **2 points**: Small feature, <1 day +- **3 points**: Medium feature, 1-2 days +- **5 points**: Large feature, 3-5 days +- **8 points**: Complex feature, 1-2 weeks +- **13+ points**: Epic-level work, needs breakdown + +##### T-Shirt Sizing (Epics/Features) + +- **XS**: 1-2 story points total +- **S**: 3-8 story points total +- **M**: 8-20 story points total +- **L**: 20-40 story points total +- **XL**: 40+ story points total (consider breaking down) + +#### 6. Dependency Management + +```mermaid +graph LR + A[Epic Planning] --> B[Feature Definition] + B --> C[Enabler Implementation] + C --> D[Story Development] + D --> E[Testing Execution] + E --> F[Feature Delivery] + + G[Infrastructure Setup] --> C + H[API Design] --> D + I[Database Schema] --> C + J[Authentication] --> D +``` + +##### Dependency Types + +- **Blocks**: Work that cannot proceed until this is complete +- **Related**: Work that shares context but not blocking +- **Prerequisite**: Required infrastructure or setup work +- **Parallel**: Work that can proceed simultaneously + +#### 7. Sprint Planning Template + +##### Sprint Capacity Planning + +- **Team Velocity**: {Average story points per sprint} +- **Sprint Duration**: {2-week sprints recommended} +- **Buffer Allocation**: 20% for unexpected work and bug fixes +- **Focus Factor**: 70-80% of total time on planned work + +##### Sprint Goal Definition + +```markdown +## Sprint {N} Goal + +**Primary Objective**: {Main deliverable for this sprint} + +**Stories in Sprint**: + +- #{issue} - {Story title} ({points} pts) +- #{issue} - {Story title} ({points} pts) + +**Total Commitment**: {points} story points +**Success Criteria**: {Measurable outcomes} +``` + +#### 8. GitHub Project Board Configuration + +##### Column Structure (Kanban) + +1. **Backlog**: Prioritized and ready for planning +2. **Sprint Ready**: Detailed and estimated, ready for development +3. **In Progress**: Currently being worked on +4. **In Review**: Code review, testing, or stakeholder review +5. **Testing**: QA validation and acceptance testing +6. **Done**: Completed and accepted + +##### Custom Fields Configuration + +- **Priority**: P0, P1, P2, P3 +- **Value**: High, Medium, Low +- **Component**: Frontend, Backend, Infrastructure, Testing +- **Estimate**: Story points or t-shirt size +- **Sprint**: Current sprint assignment +- **Assignee**: Responsible team member +- **Epic**: Parent epic reference + +#### 9. Automation and GitHub Actions + +##### Automated Issue Creation + +```yaml +name: Create Feature Issues + +on: + workflow_dispatch: + inputs: + feature_name: + description: 'Feature name' + required: true + epic_issue: + description: 'Epic issue number' + required: true + +jobs: + create-issues: + runs-on: ubuntu-latest + steps: + - name: Create Feature Issue + uses: actions/github-script@v7 + with: + script: | + const { data: epic } = await github.rest.issues.get({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: ${{ github.event.inputs.epic_issue }} + }); + + const featureIssue = await github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: `Feature: ${{ github.event.inputs.feature_name }}`, + body: `# Feature: ${{ github.event.inputs.feature_name }}\n\n...`, + labels: ['feature', 'priority-medium'], + milestone: epic.data.milestone?.number + }); +``` + +##### Automated Status Updates + +```yaml +name: Update Issue Status + +on: + pull_request: + types: [opened, closed] + +jobs: + update-status: + runs-on: ubuntu-latest + steps: + - name: Move to In Review + if: github.event.action == 'opened' + uses: actions/github-script@v7 + # Move related issues to "In Review" column + + - name: Move to Done + if: github.event.action == 'closed' && github.event.pull_request.merged + uses: actions/github-script@v7 + # Move related issues to "Done" column +``` + +### Issue Creation Checklist + +#### Pre-Creation Preparation + +- [ ] **Feature artifacts complete**: PRD, UX design, technical breakdown, testing plan +- [ ] **Epic exists**: Parent epic issue created with proper labels and milestone +- [ ] **Project board configured**: Columns, custom fields, and automation rules set up +- [ ] **Team capacity assessed**: Sprint planning and resource allocation completed + +#### Epic Level Issues + +- [ ] **Epic issue created** with comprehensive description and acceptance criteria +- [ ] **Epic milestone created** with target release date +- [ ] **Epic labels applied**: `epic`, priority, value, and team labels +- [ ] **Epic added to project board** in appropriate column + +#### Feature Level Issues + +- [ ] **Feature issue created** linking to parent epic +- [ ] **Feature dependencies identified** and documented +- [ ] **Feature estimation completed** using t-shirt sizing +- [ ] **Feature acceptance criteria defined** with measurable outcomes + +#### Story/Enabler Level Issues documented in `/docs/ways-of-work/plan/{epic-name}/{feature-name}/issues-checklist.md` + +- [ ] **User stories created** following INVEST criteria +- [ ] **Technical enablers identified** and prioritized +- [ ] **Story point estimates assigned** using Fibonacci scale +- [ ] **Dependencies mapped** between stories and enablers +- [ ] **Acceptance criteria detailed** with testable requirements + +#### Test Level Issues documented in `/docs/ways-of-work/plan/{epic-name}/{feature-name}/issues-checklist.md` + +- [ ] **Test issues created** for each story/enabler +- [ ] **Test types identified**: unit, integration, E2E, accessibility +- [ ] **Test dependencies documented** (blocked by implementation) +- [ ] **Test coverage targets set** (>80% code coverage) + +#### Task Level Breakdown documented in `/docs/ways-of-work/plan/{epic-name}/{feature-name}/issues-checklist.md` + +- [ ] **Implementation tasks created** for each story/enabler +- [ ] **Task estimates provided** (hours or sub-story points) +- [ ] **Task dependencies identified** and sequenced +- [ ] **Task assignments made** based on team skills and capacity + +#### Quality Assurance documented in `/docs/ways-of-work/plan/{epic-name}/{feature-name}/issues-checklist.md` + +- [ ] **All issues follow templates** with required fields completed +- [ ] **Labeling consistency maintained** across all work items +- [ ] **Priority and value assigned** using defined criteria +- [ ] **Dependencies validated** to avoid circular relationships +- [ ] **Estimation accuracy reviewed** by technical leads + +## Success Metrics + +### Project Management KPIs + +- **Sprint Predictability**: >80% of committed work completed per sprint +- **Cycle Time**: Average time from "In Progress" to "Done" <5 business days +- **Lead Time**: Average time from "Backlog" to "Done" <2 weeks +- **Defect Escape Rate**: <5% of stories require post-release fixes +- **Team Velocity**: Consistent story point delivery across sprints + +### Process Efficiency Metrics + +- **Issue Creation Time**: <1 hour to create full feature breakdown +- **Dependency Resolution**: <24 hours to resolve blocking dependencies +- **Status Update Accuracy**: >95% automated status transitions working correctly +- **Documentation Completeness**: 100% of issues have required template fields +- **Cross-Team Collaboration**: <2 business days for external dependency resolution + +### Quality Metrics + +- **Definition of Done Compliance**: 100% of completed stories meet DoD criteria +- **Acceptance Criteria Coverage**: 100% of acceptance criteria tested and validated +- **Test Coverage Achievement**: >80% code coverage for all implemented features +- **Performance Target Achievement**: 100% of performance requirements met +- **User Acceptance Success**: >90% first-time acceptance rate for completed features + +This comprehensive GitHub project management approach ensures complete traceability from epic-level planning down to individual implementation tasks, with automated tracking and clear accountability for all team members. diff --git a/collections/plan/prompts/plan-implementation-guide.md b/collections/plan/prompts/plan-implementation-guide.md new file mode 100644 index 0000000..09989d9 --- /dev/null +++ b/collections/plan/prompts/plan-implementation-guide.md @@ -0,0 +1,288 @@ +--- +mode: 'guide' +description: 'Implementation guide for using Epoch role-based development prompts to build features from planning artifacts.' +--- + +# Epoch Role-Based Implementation Guide + +## Overview + +This guide explains how to use the Epoch role-specific development prompts to transform planning artifacts (PRDs, implementation plans, GitHub issues) into working software. Each role prompt is designed to take planning outputs and create high-quality implementations with appropriate MCP tool integration. + +## Implementation Workflow + +### 1. Planning Phase (Already Complete) + +Using the planning prompts in `/docs/ways-of-work/plan/`: + +- ✅ Epic created: [#28 - Pantry Epic](https://github.com/craigbekker/epoch/issues/28) +- ✅ Feature created: [#29 - Recipe Library Management](https://github.com/craigbekker/epoch/issues/29) +- ✅ Technical enablers created: Database Schema (#30), tRPC API (#31), UI Components (#32), n8n Workflow (#33) +- ✅ User story created: [#34 - Recipe Grid View](https://github.com/craigbekker/epoch/issues/34) + +### 2. Implementation Phase (Using Role Prompts) + +#### Phase 1: Foundation Infrastructure + +**Database Engineer** → Use `/prompts/roles/database-engineer.prompt.md` + +- **Input**: Issue #30 - Database Schema & Migrations +- **Output**: PostgreSQL schema, Drizzle migrations, indexes +- **MCP Tools**: Database MCP for query testing and validation +- **Deliverables**: + - `apps/web/drizzle/schema/recipes.ts` + - Migration files in `apps/web/drizzle/` + - Performance indexes and constraints + +**Backend Developer** → Use `/prompts/roles/backend-developer.prompt.md` + +- **Input**: Issue #31 - tRPC Recipe API Router +- **Dependencies**: Database schema (#30) +- **Output**: Type-safe tRPC endpoints +- **MCP Tools**: Database MCP for testing, GitHub MCP for PR management +- **Deliverables**: + - `apps/web/src/server/api/routers/recipe.ts` + - Input validation schemas + - Error handling and authentication + +#### Phase 2: User Interface Foundation + +**Frontend Developer** → Use `/prompts/roles/frontend-developer.prompt.md` + +- **Input**: Issue #32 - UI Foundation Components +- **Output**: Reusable React components +- **MCP Tools**: Playwright MCP for accessibility and interaction testing +- **Deliverables**: + - `packages/ui/components/recipes/RecipeCard.tsx` + - `packages/ui/components/recipes/RecipeGrid.tsx` + - Storybook stories and component tests + +#### Phase 3: Feature Implementation + +**Frontend Developer** → Use `/prompts/roles/frontend-developer.prompt.md` + +- **Input**: Issue #34 - Recipe Grid View User Story +- **Dependencies**: Database (#30), API (#31), Components (#32) +- **Output**: Complete recipe library page +- **MCP Tools**: Playwright MCP for comprehensive E2E testing +- **Deliverables**: + - `apps/web/src/app/recipes/page.tsx` + - Complete responsive recipe grid + - Loading states, error handling, empty states + +#### Phase 4: Intelligent Automation + +**Automation Engineer** → Use `/prompts/roles/automation-engineer.prompt.md` + +- **Input**: Issue #33 - n8n Recipe Import Workflow +- **Output**: Intelligent recipe import system +- **MCP Tools**: GitHub MCP for webhook setup, Memory MCP for pattern storage +- **Deliverables**: + - n8n workflow for URL scraping + - AI-powered recipe extraction + - Vector embeddings for search + +**AI Context Engineer** → Use `/prompts/roles/ai-context-engineer.prompt.md` + +- **Input**: AI requirements from automation workflows +- **Output**: Sophisticated prompt systems and context management +- **MCP Tools**: Memory MCP for context storage, Sequential Thinking MCP for complex reasoning +- **Deliverables**: + - Recipe extraction prompts + - Context management systems + - Personalization engines + +## Role Integration Patterns + +### Cross-Role Dependencies + +```mermaid +graph TD + A[Database Engineer] --> B[Backend Developer] + A --> C[Frontend Developer] + B --> C + B --> D[Automation Engineer] + C --> E[AI Context Engineer] + D --> E + + F[Planning Artifacts] --> A + F --> B + F --> C + F --> D + F --> E +``` + +### Handoff Protocols + +#### Database → Backend + +- **Database Engineer** provides: + + - Complete schema definitions + - Migration scripts + - Performance benchmarks + - Query optimization recommendations + +- **Backend Developer** receives: + - Type-safe database access patterns + - Optimized query examples + - Performance constraints + - Data access patterns + +#### Backend → Frontend + +- **Backend Developer** provides: + + - Complete tRPC type definitions + - API documentation with examples + - Error handling patterns + - Authentication requirements + +- **Frontend Developer** receives: + - End-to-end type safety + - Clear API contracts + - Error handling guidance + - Performance expectations + +#### Frontend → Automation + +- **Frontend Developer** provides: + + - User interaction patterns + - Data requirements + - Performance constraints + - Integration points + +- **Automation Engineer** receives: + - User workflow understanding + - Integration requirements + - Performance targets + - Data transformation needs + +## MCP Tool Integration Strategy + +### By Role + +#### Database Engineer + +- **Primary**: Database MCP for query execution and schema validation +- **Secondary**: GitHub MCP for migration deployment coordination +- **Usage Pattern**: Always validate queries and performance with Database MCP + +#### Backend Developer + +- **Primary**: Database MCP for testing data operations +- **Secondary**: GitHub MCP for PR management and issue linking +- **Usage Pattern**: Test all database operations and API endpoints + +#### Frontend Developer + +- **Primary**: Playwright MCP for comprehensive UI testing +- **Secondary**: GitHub MCP for PR creation with screenshots +- **Usage Pattern**: Always validate accessibility and user interactions + +#### Automation Engineer + +- **Primary**: GitHub MCP for webhook integration +- **Secondary**: Memory MCP for storing workflow patterns +- **Usage Pattern**: Validate all webhook endpoints and data flows + +#### AI Context Engineer + +- **Primary**: Memory MCP for context storage and retrieval +- **Secondary**: Sequential Thinking MCP for complex reasoning +- **Usage Pattern**: Store and retrieve context patterns for optimization + +## Quality Standards + +### Each Role Must Deliver + +#### Database Engineer + +- [ ] Schema passes all constraint tests +- [ ] Migrations are reversible and tested +- [ ] Query performance meets <100ms targets +- [ ] Database MCP validation completed +- [ ] Household data isolation verified + +#### Backend Developer + +- [ ] All endpoints are type-safe and validated +- [ ] Authentication and authorization implemented +- [ ] Error handling covers all edge cases +- [ ] Performance targets met (<500ms API responses) +- [ ] Database MCP query testing completed + +#### Frontend Developer + +- [ ] Components pass accessibility testing +- [ ] Responsive design works on all devices +- [ ] Playwright MCP validation completed +- [ ] Performance targets met (90+ Lighthouse score) +- [ ] User interactions are smooth and intuitive + +#### Automation Engineer + +- [ ] Workflows handle errors gracefully +- [ ] Integration points are thoroughly tested +- [ ] Performance optimization implemented +- [ ] Monitoring and observability included +- [ ] GitHub MCP webhook validation completed + +#### AI Context Engineer + +- [ ] Prompts are robust and reliable +- [ ] Context management is efficient +- [ ] Privacy requirements are met +- [ ] Error handling and fallbacks implemented +- [ ] Memory MCP context validation completed + +## Implementation Commands + +### Starting Implementation + +For each role, use this pattern: + +```bash +# Example: Backend Developer implementing tRPC API +copilot prompt --file=".github/prompts/roles/backend-developer.prompt.md" \ + --context="Issue #31: tRPC Recipe API Router" \ + --context="Database schema from #30" \ + --context="Feature requirements from #29" +``` + +### MCP Validation Commands + +Each role should validate their work: + +```bash +# Database Engineer +dbcode-execute-query --query="SELECT * FROM recipes LIMIT 1" + +# Frontend Developer +mcp_playwright_browser_snapshot +mcp_playwright_browser_take_screenshot + +# Automation Engineer +mcp_github_create_pull_request --title="Recipe Import Workflow" +``` + +## Success Metrics + +### Overall Feature Success + +- [ ] All user acceptance criteria met +- [ ] Performance benchmarks achieved +- [ ] Security requirements validated +- [ ] Accessibility standards met +- [ ] Cross-browser compatibility confirmed + +### Role-Specific Success + +- [ ] Database: Query performance and data integrity +- [ ] Backend: API performance and type safety +- [ ] Frontend: User experience and accessibility +- [ ] Automation: Workflow reliability and intelligence +- [ ] AI Context: Prompt effectiveness and context retention + +This implementation guide ensures that each role delivers high-quality work that integrates seamlessly with other roles, leveraging the appropriate MCP tools for validation and testing throughout the development process. diff --git a/collections/test/instructions/test.instructions.md b/collections/test/instructions/test.instructions.md new file mode 100644 index 0000000..de47cd7 --- /dev/null +++ b/collections/test/instructions/test.instructions.md @@ -0,0 +1,13 @@ +--- +description: 'Test specific coding standards and best practices' +--- + +# Test Instructions + +These are test instructions for demonstration purposes. + +## Test Standards + +- Use clear naming conventions +- Follow test-driven development +- Write comprehensive documentation diff --git a/collections/test/prompts/test-demo.prompt.md b/collections/test/prompts/test-demo.prompt.md new file mode 100644 index 0000000..960d089 --- /dev/null +++ b/collections/test/prompts/test-demo.prompt.md @@ -0,0 +1,8 @@ +--- +title: 'Test Prompt' +description: 'A test prompt for demonstration purposes' +--- + +# Test Prompt + +This is a test prompt to demonstrate the collections functionality. diff --git a/update-readme.js b/update-readme.js index f49e138..2accd33 100755 --- a/update-readme.js +++ b/update-readme.js @@ -24,6 +24,20 @@ GitHub Copilot provides three main ways to customize AI responses and tailor ass We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details on how to submit new instructions and prompts.`, + collectionsSection: `## 📁 Collections + +Curated collections of prompts, instructions, and chat modes organized by specific domains or workflows:`, + + collectionsUsage: `> 💡 **Usage**: Each collection contains domain-specific customizations. Navigate to a collection folder to find its specialized prompts, instructions, and chat modes.`, + + collectionHeader: (collectionName) => `# 🎯 ${collectionName.charAt(0).toUpperCase() + collectionName.slice(1)} Collection + +A curated collection of GitHub Copilot customizations focused on ${collectionName} workflows and best practices. + +## 📄 About This Collection + +This collection provides specialized prompts, instructions, and chat modes tailored for ${collectionName}-related development tasks.`, + instructionsSection: `## 📋 Custom Instructions Team and project-specific instructions to enhance GitHub Copilot's behavior for specific technologies and coding practices:`, @@ -87,6 +101,73 @@ function safeFileOperation(operation, filePath, defaultValue = null) { } } +/** + * Get all collections in the collections directory + */ +function getCollections(collectionsDir) { + if (!fs.existsSync(collectionsDir)) { + return []; + } + + return fs.readdirSync(collectionsDir) + .filter(item => { + const itemPath = path.join(collectionsDir, item); + return fs.statSync(itemPath).isDirectory(); + }) + .sort(); +} + +/** + * Extract description from a collection's README or create default + */ +function getCollectionDescription(collectionPath) { + const readmePath = path.join(collectionPath, 'README.md'); + + if (fs.existsSync(readmePath)) { + return safeFileOperation(() => { + const content = fs.readFileSync(readmePath, 'utf8'); + const lines = content.split('\n'); + + // Look for description in frontmatter first + let inFrontmatter = false; + for (const line of lines) { + if (line.trim() === '---') { + if (!inFrontmatter) { + inFrontmatter = true; + continue; + } else { + break; + } + } + + if (inFrontmatter && line.includes('description:')) { + const match = line.match(/^description:\s*['"]?(.+?)['"]?$/); + if (match) { + return match[1]; + } + } + } + + // Look for first paragraph after headers + let foundHeader = false; + for (const line of lines) { + if (line.startsWith('#')) { + foundHeader = true; + continue; + } + + if (foundHeader && line.trim() && !line.startsWith('#') && !line.startsWith('>')) { + return line.trim(); + } + } + + return null; + }, readmePath, null); + } + + return null; +} + function extractTitle(filePath) { return safeFileOperation( () => { @@ -260,6 +341,8 @@ function extractDescription(filePath) { /** * Generate badges for installation links in VS Code and VS Code Insiders. * @param {string} link - The relative link to the instructions or prompts file. + * @param {string} type - The type of customization (instructions, prompt, chatmode). + * @param {string} collectionPath - Optional collection path prefix for URLs. * @returns {string} - Markdown formatted badges for installation. */ const vscodeInstallImage = @@ -270,25 +353,36 @@ const repoBaseUrl = "https://raw.githubusercontent.com/github/awesome-copilot/main"; const vscodeBaseUrl = "https://vscode.dev/redirect?url="; const vscodeInsidersBaseUrl = "https://insiders.vscode.dev/redirect?url="; -function makeBadges(link, type) { + +function makeBadges(link, type, collectionPath = '') { + const fullLink = collectionPath ? `${collectionPath}/${link}` : link; return `[![Install in VS Code](${vscodeInstallImage})](${vscodeBaseUrl}${encodeURIComponent( - `vscode:chat-${type}/install?url=${repoBaseUrl}/${link})` + `vscode:chat-${type}/install?url=${repoBaseUrl}/${fullLink})` )} [![Install in VS Code](${vscodeInsidersInstallImage})](${vscodeInsidersBaseUrl}${encodeURIComponent( - `vscode-insiders:chat-${type}/install?url=${repoBaseUrl}/${link})` + `vscode-insiders:chat-${type}/install?url=${repoBaseUrl}/${fullLink})` )}`; } /** * Generate the instructions section with a table of all instructions */ -function generateInstructionsSection(instructionsDir) { +function generateInstructionsSection(instructionsDir, collectionPath = '') { + // Check if instructions directory exists + if (!fs.existsSync(instructionsDir)) { + return ''; + } + // Get all instruction files const instructionFiles = fs .readdirSync(instructionsDir) .filter((file) => file.endsWith(".md")) .sort(); - console.log(`Found ${instructionFiles.length} instruction files`); + if (instructionFiles.length === 0) { + return ''; + } + + console.log(`Found ${instructionFiles.length} instruction files in ${instructionsDir}`); // Create table header let instructionsContent = @@ -298,13 +392,13 @@ function generateInstructionsSection(instructionsDir) { for (const file of instructionFiles) { const filePath = path.join(instructionsDir, file); const title = extractTitle(filePath); - const link = encodeURI(`instructions/${file}`); + const link = encodeURI(collectionPath ? `instructions/${file}` : `instructions/${file}`); // Check if there's a description in the frontmatter const customDescription = extractDescription(filePath); // Create badges for installation links - const badges = makeBadges(link, "instructions"); + const badges = makeBadges(link, 'instructions', collectionPath); if (customDescription && customDescription !== "null") { // Use the description from frontmatter @@ -316,20 +410,37 @@ function generateInstructionsSection(instructionsDir) { } } - return `${TEMPLATES.instructionsSection}\n\n${instructionsContent}\n${TEMPLATES.instructionsUsage}`; + const sectionHeader = collectionPath ? + "## 📋 Instructions\n\nCoding standards and best practices for this collection:" : + TEMPLATES.instructionsSection; + + const sectionUsage = collectionPath ? + "> 💡 **Usage**: Copy these instructions to your `.github/copilot-instructions.md` file or create task-specific `.github/.instructions.md` files in your workspace's `.github/instructions` folder." : + TEMPLATES.instructionsUsage; + + return `${sectionHeader}\n\n${instructionsContent}\n${sectionUsage}`; } /** * Generate the prompts section with a table of all prompts */ -function generatePromptsSection(promptsDir) { +function generatePromptsSection(promptsDir, collectionPath = '') { + // Check if prompts directory exists + if (!fs.existsSync(promptsDir)) { + return ''; + } + // Get all prompt files const promptFiles = fs .readdirSync(promptsDir) .filter((file) => file.endsWith(".prompt.md")) .sort(); - console.log(`Found ${promptFiles.length} prompt files`); + if (promptFiles.length === 0) { + return ''; + } + + console.log(`Found ${promptFiles.length} prompt files in ${promptsDir}`); // Create table header let promptsContent = @@ -345,7 +456,7 @@ function generatePromptsSection(promptsDir) { const customDescription = extractDescription(filePath); // Create badges for installation links - const badges = makeBadges(link, "prompt"); + const badges = makeBadges(link, 'prompt', collectionPath); if (customDescription && customDescription !== "null") { promptsContent += `| [${title}](${link}) | ${customDescription} | ${badges} |\n`; @@ -354,16 +465,24 @@ function generatePromptsSection(promptsDir) { } } - return `${TEMPLATES.promptsSection}\n\n${promptsContent}\n${TEMPLATES.promptsUsage}`; + const sectionHeader = collectionPath ? + "## 🎯 Prompts\n\nReady-to-use prompt templates for this collection:" : + TEMPLATES.promptsSection; + + const sectionUsage = collectionPath ? + "> 💡 **Usage**: Use `/prompt-name` in VS Code chat, run `Chat: Run Prompt` command, or hit the run button while you have a prompt open." : + TEMPLATES.promptsUsage; + + return `${sectionHeader}\n\n${promptsContent}\n${sectionUsage}`; } /** * Generate the chat modes section with a table of all chat modes */ -function generateChatModesSection(chatmodesDir) { +function generateChatModesSection(chatmodesDir, collectionPath = '') { // Check if chatmodes directory exists if (!fs.existsSync(chatmodesDir)) { - console.log("Chat modes directory does not exist"); + console.log(`Chat modes directory does not exist: ${chatmodesDir}`); return ""; } @@ -373,7 +492,7 @@ function generateChatModesSection(chatmodesDir) { .filter((file) => file.endsWith(".chatmode.md")) .sort(); - console.log(`Found ${chatmodeFiles.length} chat mode files`); + console.log(`Found ${chatmodeFiles.length} chat mode files in ${chatmodesDir}`); // If no chat modes, return empty string if (chatmodeFiles.length === 0) { @@ -394,7 +513,7 @@ function generateChatModesSection(chatmodesDir) { const customDescription = extractDescription(filePath); // Create badges for installation links - const badges = makeBadges(link, "chatmode"); + const badges = makeBadges(link, 'chatmode', collectionPath); if (customDescription && customDescription !== "null") { chatmodesContent += `| [${title}](${link}) | ${customDescription} | ${badges} |\n`; @@ -403,24 +522,144 @@ function generateChatModesSection(chatmodesDir) { } } - return `${TEMPLATES.chatmodesSection}\n\n${chatmodesContent}\n${TEMPLATES.chatmodesUsage}`; + const sectionHeader = collectionPath ? + "## 🧩 Chat Modes\n\nCustom chat modes for this collection:" : + TEMPLATES.chatmodesSection; + + const sectionUsage = collectionPath ? + "> 💡 **Usage**: Create new chat modes using the command `Chat: Configure Chat Modes...`, then switch your chat mode in the Chat input from _Agent_ or _Ask_ to your own mode." : + TEMPLATES.chatmodesUsage; + + return `${sectionHeader}\n\n${chatmodesContent}\n${sectionUsage}`; } /** - * Generate the complete README.md content from scratch + * Generate the collections section with a table of all collections */ +function generateCollectionsSection(collectionsDir) { + // Get all collections + const collections = getCollections(collectionsDir); + + if (collections.length === 0) { + return ''; + } + + console.log(`Found ${collections.length} collections`); + + // Create table header + let collectionsContent = + "| Collection | Description | Contents |\n| ---------- | ----------- | -------- |\n"; + + // Generate table rows for each collection + for (const collection of collections) { + const collectionPath = path.join(collectionsDir, collection); + const title = collection.charAt(0).toUpperCase() + collection.slice(1); + const link = `collections/${collection}/README.md`; + + // Get description + const description = getCollectionDescription(collectionPath) || + `Specialized ${collection} prompts and instructions`; + + // Count contents + const promptsDir = path.join(collectionPath, 'prompts'); + const instructionsDir = path.join(collectionPath, 'instructions'); + const chatmodesDir = path.join(collectionPath, 'chatmodes'); + + let contents = []; + + if (fs.existsSync(promptsDir)) { + const promptCount = fs.readdirSync(promptsDir).filter(f => f.endsWith('.prompt.md')).length; + if (promptCount > 0) contents.push(`${promptCount} prompts`); + } + + if (fs.existsSync(instructionsDir)) { + const instructionCount = fs.readdirSync(instructionsDir).filter(f => f.endsWith('.md')).length; + if (instructionCount > 0) contents.push(`${instructionCount} instructions`); + } + + if (fs.existsSync(chatmodesDir)) { + const chatmodeCount = fs.readdirSync(chatmodesDir).filter(f => f.endsWith('.chatmode.md')).length; + if (chatmodeCount > 0) contents.push(`${chatmodeCount} chat modes`); + } + + const contentsText = contents.length > 0 ? contents.join(', ') : 'No items'; + + collectionsContent += `| [${title}](${link}) | ${description} | ${contentsText} |\n`; + } + + return `${TEMPLATES.collectionsSection}\n\n${collectionsContent}\n${TEMPLATES.collectionsUsage}`; +} + +/** + * Generate README for a specific collection + */ +function generateCollectionReadme(collectionPath, collectionName) { + const promptsDir = path.join(collectionPath, 'prompts'); + const instructionsDir = path.join(collectionPath, 'instructions'); + const chatmodesDir = path.join(collectionPath, 'chatmodes'); + + const collectionPathForBadges = `collections/${collectionName}`; + + // Generate each section for the collection + const sections = []; + + // Header + sections.push(TEMPLATES.collectionHeader(collectionName)); + + // Instructions section + const instructionsSection = generateInstructionsSection(instructionsDir, collectionPathForBadges); + if (instructionsSection) { + sections.push(instructionsSection); + } + + // Prompts section + const promptsSection = generatePromptsSection(promptsDir, collectionPathForBadges); + if (promptsSection) { + sections.push(promptsSection); + } + + // Chat modes section + const chatmodesSection = generateChatModesSection(chatmodesDir, collectionPathForBadges); + if (chatmodesSection) { + sections.push(chatmodesSection); + } + + // Add footer + sections.push(`## 🔗 Related + +- [Main Repository](../../) - Browse all available customizations +- [Contributing Guide](../../CONTRIBUTING.md) - How to contribute to this collection`); + + return sections.join('\n\n'); +} function generateReadme() { const instructionsDir = path.join(__dirname, "instructions"); const promptsDir = path.join(__dirname, "prompts"); const chatmodesDir = path.join(__dirname, "chatmodes"); + const collectionsDir = path.join(__dirname, "collections"); // Generate each section const instructionsSection = generateInstructionsSection(instructionsDir); const promptsSection = generatePromptsSection(promptsDir); const chatmodesSection = generateChatModesSection(chatmodesDir); + const collectionsSection = generateCollectionsSection(collectionsDir); // Build the complete README content with template sections - let readmeContent = [TEMPLATES.header, instructionsSection, promptsSection]; + let readmeContent = [TEMPLATES.header]; + + // Add collections section first if we have any + if (collectionsSection) { + readmeContent.push(collectionsSection); + } + + // Add main sections + if (instructionsSection) { + readmeContent.push(instructionsSection); + } + + if (promptsSection) { + readmeContent.push(promptsSection); + } // Only include chat modes section if we have any chat modes if (chatmodesSection) { @@ -456,6 +695,37 @@ try { fs.writeFileSync(readmePath, newReadmeContent); console.log("README.md created successfully!"); } + + // Generate READMEs for all collections + const collectionsDir = path.join(__dirname, "collections"); + const collections = getCollections(collectionsDir); + + console.log(`\nProcessing ${collections.length} collections...`); + + for (const collection of collections) { + const collectionPath = path.join(collectionsDir, collection); + const collectionReadmePath = path.join(collectionPath, "README.md"); + const newCollectionContent = generateCollectionReadme(collectionPath, collection); + + // Check if the collection README file already exists + if (fs.existsSync(collectionReadmePath)) { + const originalContent = fs.readFileSync(collectionReadmePath, "utf8"); + const hasChanges = originalContent !== newCollectionContent; + + if (hasChanges) { + fs.writeFileSync(collectionReadmePath, newCollectionContent); + console.log(`${collection}/README.md updated successfully!`); + } else { + console.log(`${collection}/README.md is already up to date. No changes needed.`); + } + } else { + // Create the collection README file if it doesn't exist + fs.writeFileSync(collectionReadmePath, newCollectionContent); + console.log(`${collection}/README.md created successfully!`); + } + } + + console.log("\nAll README files processed successfully!"); } catch (error) { console.error(`Error generating README.md: ${error.message}`); process.exit(1);