diff --git a/README.md b/README.md index f4261fc01..959ef1e20 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,45 @@ Building complex features with AI can sometimes feel like a black box. This work This structured approach helps ensure the AI stays on track, makes it easier to debug issues, and gives you confidence in the generated code. +## Multi-Language Support + +**AI Dev Tasks** now supports multiple programming languages! The workflow automatically adapts to your project's language, using the appropriate: + +- File extensions (`.py`, `.ts`, `.go`, etc.) +- Testing frameworks (pytest, Jest, go test, etc.) +- Directory structures and naming conventions +- Language-specific best practices + +### Supported Languages + +| Language | Configuration File | Testing Framework | +|----------|-------------------|-------------------| +| **TypeScript/JavaScript** | `lang/typescript.md` | Jest (or Vitest, Mocha) | +| **Python** | `lang/python.md` | pytest (or unittest) | +| **Go** | `lang/go.md` | Built-in `testing` package | + +Additional languages can be easily added by creating new configuration files in the `lang/` directory. + +### How It Works + +When generating tasks, the AI assistant will: + +1. **Auto-detect** your language from: + - Your explicit mention ("for my Python project") + - The PRD content + - File extensions in your repository + +2. **Load language configuration** automatically from `lang/[language].md` + +3. **Apply conventions** to the generated task list (file extensions, test commands, directory structure) + +**Example:** +```text +Use @generate-tasks.md to create tasks for my Python project from @MyFeature-PRD.md +``` + +The AI will automatically use Python conventions (`.py` files, `pytest`, `tests/` directory structure). + ## Workflow: From Idea to Implemented Feature Here's the step-by-step process using the `.md` files in this repository: @@ -84,18 +123,51 @@ If you'd like to see this in action, I demonstrated it on [Claire Vo's "How I AI [![Demonstration of AI Dev Tasks on How I AI Podcast](https://img.youtube.com/vi/fD4ktSkNCw4/maxresdefault.jpg)](https://www.youtube.com/watch?v=fD4ktSkNCw4). -## Files in this Repository +## Repository Structure -* **`create-prd.md`**: Guides the AI in generating a Product Requirement Document for your feature. -* **`generate-tasks.md`**: Takes a PRD markdown file as input and helps the AI break it down into a detailed, step-by-step implementation task list. +``` +/ +├── create-prd.md # PRD generation guide +├── generate-tasks.md # Task list generation (language-agnostic) +├── lang/ # Language-specific configurations +│ ├── README.md # Language index and contribution guide +│ ├── typescript.md # TypeScript/JavaScript conventions +│ ├── python.md # Python conventions +│ └── go.md # Go conventions +├── docs/ # Documentation +│ └── front-matter-schema.md # YAML front matter specification +├── README.md # This file +└── LICENSE +``` + +### Core Files + +* **`create-prd.md`**: Guides the AI in generating a Product Requirement Document (PRD) for your feature with structured metadata. +* **`generate-tasks.md`**: Takes a PRD and helps the AI break it down into a detailed, language-appropriate task list. + +### Language Configurations (`lang/`) + +Each language file defines: +- File extensions and naming conventions +- Testing frameworks and commands +- Directory structure patterns +- Language-specific best practices + +See `lang/README.md` for the full list of supported languages and how to add new ones. + +### Documentation (`docs/`) + +* **`front-matter-schema.md`**: Specification for YAML front matter metadata included in all generated documents (PRDs and task lists). Enables better organization, traceability, and version tracking. ## Benefits * **Structured Development:** Enforces a clear process from idea to code. +* **Multi-Language Support:** Works seamlessly with TypeScript, Python, Go, and more. Each language uses appropriate conventions and tooling. * **Step-by-Step Verification:** Allows you to review and approve AI-generated code at each small step, ensuring quality and control. * **Manages Complexity:** Breaks down large features into smaller, digestible tasks for the AI, reducing the chance of it getting lost or generating overly complex, incorrect code. * **Improved Reliability:** Offers a more dependable approach to leveraging AI for significant development work compared to single, large prompts. * **Clear Progress Tracking:** Provides a visual representation of completed tasks, making it easy to see how much has been done and what's next. +* **Document Metadata:** Generated PRDs and task lists include YAML front matter for better organization, versioning, and traceability. ## How to Use @@ -113,17 +185,38 @@ If you'd like to see this in action, I demonstrated it on [Claire Vo's "How I AI ## Tips for Success * **Be Specific:** The more context and clear instructions you provide (both in your initial feature description and any clarifications), the better the AI's output will be. +* **Specify Your Language:** Mention your programming language when generating tasks (e.g., "for my Python project"). The AI will auto-detect it, but explicit mentions ensure accuracy. * **Correct File Tagging:** Always ensure you're accurately tagging the PRD filename (e.g., `@MyFeature-PRD.md`) when generating tasks. * **Patience and Iteration:** AI is a powerful tool, but it's not magic. Be prepared to guide, correct, and iterate. This workflow is designed to make that iteration process smoother. +* **Language Fallback:** If the AI doesn't auto-detect your language, you can explicitly reference both files: `@generate-tasks.md @lang/python.md` ## Contributing Got ideas to improve these `.md` files or have new ones that fit this workflow? Contributions are welcome! +### Adding New Languages + +Want to add support for your favorite programming language? It's easy! + +1. Create a new file in `lang/` directory (e.g., `lang/rust.md`, `lang/java.md`) +2. Follow the structure of existing language files: + - File extensions + - Testing frameworks and commands + - Directory structure conventions + - Language-specific best practices + - Example task list entries +3. Update `lang/README.md` to include your new language +4. Submit a pull request! + +See `lang/README.md` for detailed contribution guidelines. + +### Other Contributions + Please feel free to: * Open an issue to discuss changes or suggest new features. * Submit a pull request with your enhancements. +* Improve documentation or fix typos. --- diff --git a/create-prd.md b/create-prd.md index c6e189e74..d65507ffc 100644 --- a/create-prd.md +++ b/create-prd.md @@ -52,7 +52,29 @@ Ask only the most critical questions needed to write a clear PRD. Focus on areas ## PRD Structure -The generated PRD should include the following sections: +The generated PRD should include YAML front matter at the top, followed by the content sections below. + +### Front Matter (Required) + +```yaml +--- +doc_type: "prd" +id: "prd-[YYYYMMDD]-[short-slug]" +slug: "[feature-name]" +version: "1.0.0" +created_at: "[ISO-8601-datetime]" +author: + name: "[User's name or 'User']" + ai_model: "[Your model name, e.g., 'Claude Sonnet 4.5']" +title: "[Human-readable feature title]" +description: "[Brief 1-2 sentence description]" +tags: ["feature", "[category]"] +--- +``` + +See `docs/front-matter-schema.md` for detailed field descriptions and optional fields. + +### Content Sections 1. **Introduction/Overview:** Briefly describe the feature and the problem it solves. State the goal. 2. **Goals:** List the specific, measurable objectives for this feature. @@ -70,12 +92,16 @@ Assume the primary reader of the PRD is a **junior developer**. Therefore, requi ## Output -* **Format:** Markdown (`.md`) +* **Format:** Markdown (`.md`) with YAML front matter * **Location:** `/tasks/` * **Filename:** `prd-[feature-name].md` +* **Structure:** Front matter (YAML) + Content sections (Markdown) ## Final instructions 1. Do NOT start implementing the PRD 2. Make sure to ask the user clarifying questions 3. Take the user's answers to the clarifying questions and improve the PRD +4. Include complete YAML front matter at the top of the generated PRD +5. Populate all required front matter fields with appropriate values (see `docs/front-matter-schema.md`) +6. Use current timestamp for `created_at` field in ISO 8601 format diff --git a/docs/front-matter-schema.md b/docs/front-matter-schema.md new file mode 100644 index 000000000..2b2857b8b --- /dev/null +++ b/docs/front-matter-schema.md @@ -0,0 +1,299 @@ +# Front Matter Schema + +This document defines the YAML front matter metadata schema for generated documents (PRDs and task lists) in the AI Dev Tasks workflow. + +## Purpose + +Front matter provides structured metadata that enables: +- **Traceability**: Track who created documents, when, and with which AI model +- **Versioning**: Document evolution over time with changelog +- **Organization**: Better searchability and categorization in tools like Obsidian +- **Standards**: Align with documentation best practices (e.g., Good Laboratory Practice) + +## Schema Definition + +### Required Fields + +All generated documents MUST include these fields: + +```yaml +--- +doc_type: string # "prd" or "task-list" +id: string # Unique identifier (e.g., "prd-20250115-user-auth") +slug: string # URL-friendly identifier matching filename +version: string # Semantic version (e.g., "1.0.0") +created_at: string # ISO 8601 datetime (e.g., "2025-01-15T10:30:00Z") +author: + name: string # Name of the person who created/requested the document + ai_model: string # AI model used (e.g., "Claude Sonnet 4.5") +--- +``` + +### Optional Fields + +Documents MAY include these fields for enhanced metadata: + +```yaml +--- +# ... required fields above ... + +title: string # Human-readable title +description: string # Brief description of the document +language: string # Programming language (e.g., "python", "typescript", "go") +project: string # Project name this document belongs to +tags: string[] # Array of tags for categorization +confidentiality: string # "public", "internal", or "confidential" +related_docs: # Links to related documentation + prd: string # Path to related PRD + tasks: string # Path to related task list + implementation: string # Path to implementation notes +contributors: object[] # Additional contributors + - name: string + role: string + email: string +changelog: object[] # Version history + - version: string + date: string # YYYY-MM-DD format + changes: string # Description of changes +--- +``` + +## Field Descriptions + +### Required Fields + +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `doc_type` | string | Type of document | `"prd"` or `"task-list"` | +| `id` | string | Unique identifier combining type, date, and slug | `"task-list-20250115-user-profile"` | +| `slug` | string | URL-friendly identifier, should match filename without extension | `"tasks-user-profile-editing"` | +| `version` | string | Semantic version following semver.org | `"1.0.0"`, `"1.2.3"` | +| `created_at` | string | ISO 8601 datetime in UTC | `"2025-01-15T10:30:00Z"` | +| `author.name` | string | Name of document creator/requester | `"Jane Developer"` | +| `author.ai_model` | string | AI model used for generation | `"Claude Sonnet 4.5"`, `"GPT-4"` | + +### Optional Fields + +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `title` | string | Human-readable title | `"User Profile Editing Feature"` | +| `description` | string | Brief summary (1-2 sentences) | `"Implementation tasks for user profile editing"` | +| `language` | string | Primary programming language | `"python"`, `"typescript"`, `"go"` | +| `project` | string | Project name | `"MyApp"`, `"E-commerce Platform"` | +| `tags` | array | Categorization tags | `["feature", "user-management", "frontend"]` | +| `confidentiality` | string | Access level | `"public"`, `"internal"`, `"confidential"` | +| `related_docs` | object | Links to related files | See examples below | +| `contributors` | array | Additional contributors | See examples below | +| `changelog` | array | Version history | See examples below | + +## Complete Examples + +### Example 1: PRD with Minimal Required Fields + +```yaml +--- +doc_type: "prd" +id: "prd-20250115-user-authentication" +slug: "prd-user-authentication" +version: "1.0.0" +created_at: "2025-01-15T10:30:00Z" +author: + name: "Jane Developer" + ai_model: "Claude Sonnet 4.5" +--- +``` + +### Example 2: Task List with Full Metadata + +```yaml +--- +doc_type: "task-list" +id: "task-list-20250115-user-profile-editing" +slug: "tasks-user-profile-editing" +version: "1.2.0" +created_at: "2025-01-15T10:30:00Z" +author: + name: "Jane Developer" + ai_model: "Claude Sonnet 4.5" +title: "User Profile Editing Implementation Tasks" +description: "Detailed task breakdown for implementing user profile editing feature with validation and image upload" +language: "python" +project: "MyApp Backend" +tags: ["feature", "user-management", "backend", "api"] +confidentiality: "internal" +related_docs: + prd: "/tasks/prd-user-profile-editing.md" + implementation: "/docs/user-profile-implementation.md" +contributors: + - name: "John Reviewer" + role: "Tech Lead" + email: "john@example.com" +changelog: + - version: "1.2.0" + date: "2025-01-16" + changes: "Added image upload validation tasks based on code review feedback" + - version: "1.1.0" + date: "2025-01-15" + changes: "Added API endpoint tasks for profile updates" + - version: "1.0.0" + date: "2025-01-15" + changes: "Initial task list created" +--- +``` + +### Example 3: PRD with Comprehensive Metadata + +```yaml +--- +doc_type: "prd" +id: "prd-20250115-payment-integration" +slug: "prd-payment-integration" +version: "2.0.0" +created_at: "2025-01-15T09:00:00Z" +author: + name: "Product Team" + ai_model: "Claude Sonnet 4.5" +title: "Third-Party Payment Gateway Integration" +description: "Requirements for integrating Stripe payment processing into the e-commerce platform" +language: "typescript" +project: "E-commerce Platform" +tags: ["feature", "payments", "integration", "security"] +confidentiality: "internal" +related_docs: + tasks: "/tasks/tasks-payment-integration.md" + implementation: "/docs/payment-gateway-design.md" +contributors: + - name: "Alice Security" + role: "Security Reviewer" + email: "alice@example.com" + - name: "Bob Finance" + role: "Finance Lead" + email: "bob@example.com" +changelog: + - version: "2.0.0" + date: "2025-01-15" + changes: "Updated to use Stripe Payment Intents API instead of deprecated Charges API" + - version: "1.1.0" + date: "2025-01-10" + changes: "Added security requirements based on security review" + - version: "1.0.0" + date: "2025-01-08" + changes: "Initial PRD created" +--- +``` + +## Best Practices + +### ID Generation + +Generate unique IDs using this pattern: +``` +[doc_type]-[YYYYMMDD]-[short-slug] +``` + +Examples: +- `prd-20250115-user-auth` +- `task-list-20250115-profile-edit` + +### Version Management + +Follow semantic versioning (semver.org): +- **Major** (x.0.0): Significant restructuring or scope changes +- **Minor** (0.x.0): Adding new sections or requirements +- **Patch** (0.0.x): Small corrections, typos, clarifications + +### Changelog Guidelines + +- Record all meaningful changes +- Use present tense: "Add feature X" not "Added feature X" +- Be specific about what changed +- Include date in YYYY-MM-DD format +- Most recent version at the top + +### Language Field Values + +Use lowercase, standardized language names: +- `"typescript"` (covers JavaScript too) +- `"python"` +- `"go"` +- `"java"` +- `"rust"` +- `"csharp"` +- `"ruby"` +- `"php"` + +### Tags Guidelines + +Use consistent, descriptive tags: +- Feature type: `feature`, `bugfix`, `refactor`, `enhancement` +- Domain: `frontend`, `backend`, `api`, `database`, `ui` +- Category: `user-management`, `payments`, `auth`, `reporting` +- Priority: `urgent`, `high-priority`, `nice-to-have` + +## Integration with AI Workflow + +### For AI Assistants + +When generating PRDs or task lists: + +1. **Always include front matter** at the very top of the document +2. **Populate all required fields** with appropriate values +3. **Use current timestamp** for `created_at` field +4. **Detect language** from context and include in optional `language` field +5. **Start with version 1.0.0** for new documents +6. **Ask user for name** to populate `author.name` if not in context + +### For Users + +When requesting document generation: + +- Provide your name for the `author.name` field +- Specify project name if you want it included +- Mention if document should be confidential or internal +- Request specific tags if you have a tagging system + +## Tools Integration + +### Obsidian + +Front matter enables: +- Search by tags, language, or project +- Filter by doc_type or confidentiality +- Create dataview queries for document management +- Build graphs of related documents + +### Other Tools + +Compatible with: +- Jekyll/Hugo static site generators +- Markdown processors that support YAML front matter +- Documentation management systems +- Knowledge base tools (Notion, Roam, etc.) + +## Validation + +### Required Field Check + +Before saving a document, verify: +- [ ] All required fields are present +- [ ] `doc_type` is either "prd" or "task-list" +- [ ] `version` follows semver format +- [ ] `created_at` is valid ISO 8601 datetime +- [ ] `slug` matches filename (without extension) + +### Optional Field Check + +If including optional fields: +- [ ] `language` matches supported language from `lang/` directory +- [ ] `tags` is an array, not a string +- [ ] `changelog` entries are in reverse chronological order +- [ ] Related document paths are valid + +## Future Extensions + +Potential additions to the schema: +- `status`: "draft", "review", "approved", "implemented" +- `priority`: "low", "medium", "high", "critical" +- `estimated_effort`: Time estimation for task completion +- `dependencies`: Links to prerequisite documents or tasks +- `assigned_to`: Person responsible for implementation diff --git a/generate-tasks.md b/generate-tasks.md index 643ca4502..aba5bbd74 100644 --- a/generate-tasks.md +++ b/generate-tasks.md @@ -1,5 +1,40 @@ # Rule: Generating a Task List from User Requirements +## 🎯 Language Configuration (AI Instructions) + +**CRITICAL - READ THIS FIRST:** + +Before generating tasks, you MUST: + +1. **Detect the programming language** from: + - Explicit mention in user's request ("for my Python project") + - Language specified in the PRD + - File extensions in the repository (`.py`, `.ts`, `.go`, etc.) + - Ask the user if unclear + +2. **Read the language configuration file**: + - TypeScript/JavaScript → `@lang/typescript.md` + - Python → `@lang/python.md` + - Go → `@lang/go.md` + - See `lang/README.md` for all supported languages + +3. **Confirm to the user** which language configuration you're using: + ``` + "I will generate tasks for [LANGUAGE] using these conventions: + - File extension: [extension] + - Test command: [command] + - Test location: [pattern]" + ``` + +This confirmation ensures you've loaded the correct language-specific conventions before proceeding. + +**Fallback**: If automatic detection fails, the user can explicitly reference both files: +``` +@generate-tasks.md @lang/python.md [their request] +``` + +--- + ## Goal To guide an AI assistant in creating a detailed, step-by-step task list in Markdown format based on user requirements, feature requests, or existing documentation. The task list should guide a developer through implementation. @@ -17,28 +52,47 @@ To guide an AI assistant in creating a detailed, step-by-step task list in Markd 3. **Phase 1: Generate Parent Tasks:** Based on the requirements analysis, create the file and generate the main, high-level tasks required to implement the feature. **IMPORTANT: Always include task 0.0 "Create feature branch" as the first task, unless the user specifically requests not to create a branch.** Use your judgement on how many additional high-level tasks to use. It's likely to be about 5. Present these tasks to the user in the specified format (without sub-tasks yet). Inform the user: "I have generated the high-level tasks based on your requirements. Ready to generate the sub-tasks? Respond with 'Go' to proceed." 4. **Wait for Confirmation:** Pause and wait for the user to respond with "Go". 5. **Phase 2: Generate Sub-Tasks:** Once the user confirms, break down each parent task into smaller, actionable sub-tasks necessary to complete the parent task. Ensure sub-tasks logically follow from the parent task and cover the implementation details implied by the requirements. -6. **Identify Relevant Files:** Based on the tasks and requirements, identify potential files that will need to be created or modified. List these under the `Relevant Files` section, including corresponding test files if applicable. +6. **Identify Relevant Files:** Based on the tasks and requirements, identify potential files that will need to be created or modified. List these under the `Relevant Files` section. **Use the file extensions, test file patterns, and directory structures from the language configuration file you loaded.** 7. **Generate Final Output:** Combine the parent tasks, sub-tasks, relevant files, and notes into the final Markdown structure. 8. **Save Task List:** Save the generated document in the `/tasks/` directory with the filename `tasks-[feature-name].md`, where `[feature-name]` describes the main feature or task being implemented (e.g., if the request was about user profile editing, the output is `tasks-user-profile-editing.md`). ## Output Format -The generated task list _must_ follow this structure: +The generated task list _must_ follow this structure, including YAML front matter at the top: + +````markdown +--- +doc_type: "task-list" +id: "task-list-[YYYYMMDD]-[short-slug]" +slug: "[feature-name]" +version: "1.0.0" +created_at: "[ISO-8601-datetime]" +author: + name: "[User's name or 'User']" + ai_model: "[Your model name, e.g., 'Claude Sonnet 4.5']" +title: "[Human-readable feature title]" +description: "[Brief 1-2 sentence description]" +language: "[Programming language from lang config]" +tags: ["feature", "[category]", "[domain]"] +--- + +# [Feature Name] - Implementation Tasks -```markdown ## Relevant Files -- `path/to/potential/file1.ts` - Brief description of why this file is relevant (e.g., Contains the main component for this feature). -- `path/to/file1.test.ts` - Unit tests for `file1.ts`. -- `path/to/another/file.tsx` - Brief description (e.g., API route handler for data submission). -- `path/to/another/file.test.tsx` - Unit tests for `another/file.tsx`. -- `lib/utils/helpers.ts` - Brief description (e.g., Utility functions needed for calculations). -- `lib/utils/helpers.test.ts` - Unit tests for `helpers.ts`. +- `path/to/file[.ext]` - Brief description of why this file is relevant (e.g., Contains the main component for this feature) +- `path/to/test_file[.ext]` - Unit tests for the file above +- `path/to/another/file[.ext]` - Brief description (e.g., API route handler for data submission) +- `path/to/another/test_file[.ext]` - Unit tests for the file above +- `lib/utils/helpers[.ext]` - Brief description (e.g., Utility functions needed for calculations) +- `lib/utils/test_helpers[.ext]` - Unit tests for helpers ### Notes -- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory). -- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration. +- **File Extensions**: Use the extensions from the language configuration (e.g., `.py`, `.ts`, `.go`) +- **Test File Location**: Follow the language's testing conventions (co-located, separate `tests/` directory, etc.) +- **Test Command**: Use `[test-command-from-lang-config] [optional/path/to/test/file]` to run tests +- **Front Matter**: See `docs/front-matter-schema.md` for detailed field descriptions and examples ## Instructions for Completing Tasks @@ -59,7 +113,7 @@ Update the file after completing each sub-task, not just after completing an ent - [ ] 2.0 Parent Task Title - [ ] 2.1 [Sub-task description 2.1] - [ ] 3.0 Parent Task Title (may not require sub-tasks if purely structural or configuration) -``` +```` ## Interaction Model @@ -68,3 +122,48 @@ The process explicitly requires a pause after generating parent tasks to get use ## Target Audience Assume the primary reader of the task list is a **junior developer** who will implement the feature. + +## Language-Specific Adaptations + +When generating the task list, apply these language-specific elements from the configuration file you loaded: + +1. **File Extensions**: Use correct extensions for source and test files +2. **Test Commands**: Reference the appropriate testing framework and commands +3. **Directory Structure**: Follow language conventions for file organization +4. **Testing Patterns**: Describe test setup following language best practices +5. **Naming Conventions**: Use language-appropriate naming (camelCase, snake_case, PascalCase, etc.) + +## Example: Language-Specific Task Variations + +**TypeScript Project:** +```markdown +- `src/components/UserProfile.tsx` - User profile component +- `src/components/UserProfile.test.tsx` - Unit tests +- Run tests: `npx jest src/components/UserProfile.test.tsx` +``` + +**Python Project:** +```markdown +- `src/components/user_profile.py` - User profile module +- `tests/components/test_user_profile.py` - Unit tests +- Run tests: `pytest tests/components/test_user_profile.py` +``` + +**Go Project:** +```markdown +- `internal/user/profile.go` - User profile business logic +- `internal/user/profile_test.go` - Unit tests +- Run tests: `go test ./internal/user` +``` + +--- + +## Summary Checklist + +Before generating tasks, ensure you have: +- [ ] Detected or asked about the programming language +- [ ] Read the corresponding `lang/[language].md` configuration file +- [ ] Confirmed to the user which language conventions you'll use +- [ ] Understood the feature requirements from the PRD or user description + +Then proceed with the standard workflow: Generate parent tasks → Wait for "Go" → Generate sub-tasks → Save file. diff --git a/lang/README.md b/lang/README.md new file mode 100644 index 000000000..c416182e6 --- /dev/null +++ b/lang/README.md @@ -0,0 +1,68 @@ +# Language Configurations + +This directory contains language-specific configurations for task generation. Each file defines the file extensions, testing conventions, and best practices for a particular programming language. + +## Supported Languages + +| Language | File | Description | +|----------|------|-------------| +| **TypeScript/JavaScript** | `typescript.md` | TypeScript, JavaScript, React, Node.js projects with Jest testing | +| **Python** | `python.md` | Python projects with pytest testing framework | +| **Go** | `go.md` | Go projects using built-in `testing` package | + +## How to Use + +When generating tasks with `generate-tasks.md`, the AI assistant will automatically read the appropriate language configuration based on: + +1. **Explicit specification**: "Generate tasks for my Python project" +2. **PRD context**: Language mentioned in the Product Requirements Document +3. **Repository detection**: File extensions found in your codebase + +## Adding a New Language + +To add support for a new language, create a new file following this template: + +```markdown +# [Language Name] Configuration + +## File Extensions +[List source and test file extensions] + +## Testing +[Primary testing framework and commands] + +## File Organization +[Directory structure patterns and conventions] + +## Conventions +[Language-specific best practices and standards] + +## Example Task List Entry +[Sample relevant files section] +``` + +**Languages we'd love to see:** +- Java (`java.md`) +- Rust (`rust.md`) +- C# (`csharp.md`) +- Ruby (`ruby.md`) +- PHP (`php.md`) +- Kotlin (`kotlin.md`) +- Swift (`swift.md`) + +## Contributing + +When adding a new language configuration: + +1. Follow the structure of existing language files +2. Include the most common testing framework as primary +3. Mention alternative frameworks if widely used +4. Provide realistic examples in the "Example Task List Entry" section +5. Update this README with the new language +6. Keep configurations focused on practical, actionable information + +## File Naming Convention + +- Use lowercase language names: `python.md`, not `Python.md` +- For languages with multiple names, use the most common: `typescript.md` (covers JavaScript too) +- For language variants, use hyphens: `typescript-react.md` (if needed in future) diff --git a/lang/go.md b/lang/go.md new file mode 100644 index 000000000..50138a692 --- /dev/null +++ b/lang/go.md @@ -0,0 +1,150 @@ +# Go Configuration + +## File Extensions + +**Source Files:** +- `.go` - Go source files + +**Test Files:** +- `*_test.go` - Test files (must end with `_test.go`) + +## Testing + +**Built-in Test Framework:** `testing` package + +**Test Command:** +```bash +go test ./... +``` + +**Common Options:** +- `go test -v ./...` - Verbose output showing all tests +- `go test -run TestName` - Run specific test by name +- `go test -cover` - Show coverage percentage +- `go test -coverprofile=coverage.out` - Generate coverage profile +- `go test -bench=.` - Run benchmarks +- `go test ./path/to/package` - Test specific package +- `go test -race` - Run with race detector + +**Coverage Visualization:** +```bash +go test -coverprofile=coverage.out +go tool cover -html=coverage.out +``` + +## File Organization + +**Test Location:** +- **Co-located** (standard): Test files alongside source files in same package + ``` + mypackage/ + user.go + user_test.go + profile.go + profile_test.go + ``` + +**Project Structure Patterns:** +- `cmd/` - Main applications for this project +- `pkg/` - Library code that's ok to use by external applications +- `internal/` - Private application and library code (not importable) +- `api/` - API definitions (OpenAPI/Swagger, protocol buffers) +- `web/` - Web application specific components +- `scripts/` - Build, install, analysis scripts +- `test/` - Additional external test apps and test data (integration tests) + +**Standard Layout Example:** +``` +project/ + cmd/ + myapp/ + main.go + internal/ + user/ + user.go + user_test.go + pkg/ + api/ + api.go + api_test.go +``` + +## Conventions + +- **Naming**: + - Use MixedCaps or mixedCaps (no underscores) + - Exported names start with capital letter + - Package names are lowercase, single word +- **Testing**: + - Test functions start with `Test` prefix: `func TestUserCreation(t *testing.T)` + - Benchmark functions start with `Benchmark` prefix + - Use table-driven tests for multiple test cases +- **Packages**: One package per directory +- **Imports**: Use `go mod` for dependency management +- **Configuration**: `go.mod`, `go.sum` +- **Formatting**: Use `gofmt` or `goimports` for automatic formatting + +## Example Task List Entry + +```markdown +## Relevant Files + +- `internal/user/profile.go` - User profile business logic +- `internal/user/profile_test.go` - Unit tests for user profile +- `pkg/api/users.go` - Public API client for user operations +- `pkg/api/users_test.go` - Unit tests for user API client +- `internal/utils/validation.go` - Input validation utilities +- `internal/utils/validation_test.go` - Unit tests for validation utilities +``` + +## Common Test Patterns + +**Basic Test:** +```go +func TestUserCreation(t *testing.T) { + user := NewUser("Test User", "test@example.com") + if user.Name != "Test User" { + t.Errorf("expected name %q, got %q", "Test User", user.Name) + } +} +``` + +**Table-Driven Test:** +```go +func TestDouble(t *testing.T) { + tests := []struct { + input int + expected int + }{ + {1, 2}, + {2, 4}, + {3, 6}, + } + + for _, tt := range tests { + result := Double(tt.input) + if result != tt.expected { + t.Errorf("Double(%d) = %d; want %d", tt.input, result, tt.expected) + } + } +} +``` + +**Subtests:** +```go +func TestUser(t *testing.T) { + t.Run("Creation", func(t *testing.T) { + user := NewUser("Test") + if user.Name != "Test" { + t.Error("unexpected name") + } + }) + + t.Run("Validation", func(t *testing.T) { + err := ValidateUser(User{}) + if err == nil { + t.Error("expected validation error") + } + }) +} +``` diff --git a/lang/python.md b/lang/python.md new file mode 100644 index 000000000..82f80936b --- /dev/null +++ b/lang/python.md @@ -0,0 +1,109 @@ +# Python Configuration + +## File Extensions + +**Source Files:** +- `.py` - Python source files + +**Test Files:** +- `test_*.py` - Test files (pytest convention) +- `*_test.py` - Alternative test naming convention + +## Testing + +**Primary Test Framework:** pytest + +**Test Command:** +```bash +pytest [optional/path/to/test_file.py] +``` + +**Common Options:** +- `pytest -v` - Verbose output with test names +- `pytest -s` - Show print statements +- `pytest --cov` - Generate coverage report +- `pytest --cov=src` - Coverage for specific directory +- `pytest -k "test_name"` - Run tests matching pattern +- `pytest --maxfail=1` - Stop after first failure + +**Alternative Frameworks:** +- unittest: `python -m unittest` +- nose2: `nose2` + +## File Organization + +**Test Location:** +- **Separate tests/ directory** (recommended): Mirror source structure in tests/ + ``` + project/ + src/ + mypackage/ + module.py + tests/ + mypackage/ + test_module.py + ``` +- **Co-located**: Tests alongside source in same directory + ``` + mypackage/ + module.py + test_module.py + ``` + +**Project Structure Patterns:** +- `src/` - Source code (src layout) +- `tests/` - Test files +- `docs/` - Documentation +- Package root layout (alternative): + ``` + mypackage/ + __init__.py + module.py + tests/ + test_module.py + ``` + +## Conventions + +- **Naming**: Use snake_case for functions, variables, and file names +- **Imports**: Use absolute imports from project root +- **Testing**: Use pytest fixtures for setup/teardown +- **Type Hints**: Use type annotations (Python 3.6+) +- **Virtual Environment**: `venv/`, `.venv/`, or `virtualenv/` +- **Dependencies**: `requirements.txt`, `setup.py`, or `pyproject.toml` +- **Code Style**: Follow PEP 8 style guide + +## Example Task List Entry + +```markdown +## Relevant Files + +- `src/mypackage/user_profile.py` - User profile module with business logic +- `tests/mypackage/test_user_profile.py` - Unit tests for user profile module +- `src/mypackage/api/users.py` - API client for user operations +- `tests/mypackage/api/test_users.py` - Unit tests for user API client +- `src/mypackage/utils/validation.py` - Input validation utilities +- `tests/mypackage/utils/test_validation.py` - Unit tests for validation utilities +``` + +## Common Test Patterns + +**Fixtures:** +```python +@pytest.fixture +def sample_user(): + return User(name="Test User", email="test@example.com") + +def test_user_creation(sample_user): + assert sample_user.name == "Test User" +``` + +**Parameterization:** +```python +@pytest.mark.parametrize("input,expected", [ + (1, 2), + (2, 4), +]) +def test_double(input, expected): + assert input * 2 == expected +``` diff --git a/lang/typescript.md b/lang/typescript.md new file mode 100644 index 000000000..9a62e7afd --- /dev/null +++ b/lang/typescript.md @@ -0,0 +1,83 @@ +# TypeScript/JavaScript Configuration + +## File Extensions + +**Source Files:** +- `.ts` - TypeScript source files +- `.tsx` - TypeScript with JSX (React components) +- `.js` - JavaScript source files +- `.jsx` - JavaScript with JSX + +**Test Files:** +- `.test.ts` - TypeScript unit tests +- `.test.tsx` - TypeScript component tests +- `.test.js` - JavaScript unit tests +- `.test.jsx` - JavaScript component tests +- `.spec.ts` - Alternative test naming convention +- `.spec.js` - Alternative test naming convention + +## Testing + +**Primary Test Framework:** Jest + +**Test Command:** +```bash +npx jest [optional/path/to/test/file] +``` + +**Common Options:** +- `npx jest --watch` - Run tests in watch mode +- `npx jest --coverage` - Generate coverage report +- `npx jest --verbose` - Verbose output +- `npx jest path/to/specific.test.ts` - Run specific test file + +**Alternative Frameworks:** +- Vitest: `npx vitest` +- Mocha: `npx mocha` + +## File Organization + +**Test Location:** +- **Co-located** (recommended): Place test files alongside the source files they test + ``` + src/ + components/ + Button.tsx + Button.test.tsx + ``` +- **Separate directory**: Tests in `__tests__/` directory + ``` + src/ + components/ + Button.tsx + __tests__/ + Button.test.tsx + ``` + +**Project Structure Patterns:** +- `src/` - Source code +- `tests/` or `__tests__/` - Test files (if not co-located) +- `lib/` or `utils/` - Utility functions +- `types/` - TypeScript type definitions +- `components/` - React/UI components (if applicable) + +## Conventions + +- **Naming**: Use PascalCase for classes/components, camelCase for functions/variables +- **Imports**: Use ES6 imports (`import/export`) +- **Testing**: Use `describe()` and `it()` or `test()` blocks +- **Type Safety**: Leverage TypeScript types for better code quality +- **Configuration**: `tsconfig.json`, `package.json`, `jest.config.js` + +## Example Task List Entry + +```markdown +## Relevant Files + +- `src/components/UserProfile.tsx` - Main user profile component +- `src/components/UserProfile.test.tsx` - Unit tests for UserProfile component +- `src/api/users.ts` - API client for user operations +- `src/api/users.test.ts` - Unit tests for user API client +- `lib/utils/validation.ts` - Input validation utilities +- `lib/utils/validation.test.ts` - Unit tests for validation utilities +```