diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3b5a54b5..5fc163a9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -26,4 +26,27 @@ PowerShell 7.4+ (GitHub Actions composite actions): Follow standard conventions - 001-building-on-this: Added PowerShell 7.4+ (GitHub Actions composite actions) + PSModule/GitHub-Script@v1, PSModule/Install-PSModuleHelpers@v1 + +## Terminal Commands + +When executing terminal commands (using `run_in_terminal` or similar tools): +- **ALWAYS** prefix shell commands with `pwsh` unless it's a GitHub MCP call +- This applies to all PowerShell scripts, git commands, and other shell operations +- Exception: GitHub MCP Server calls should use their native format without `pwsh` prefix + +Examples: +```bash +# Correct - PowerShell script +pwsh -Command "& './.specify/scripts/powershell/setup-plan.ps1' -Json" + +# Correct - Git command +pwsh -Command "git status" + +# Correct - Any shell command +pwsh -Command "ls -Recurse" + +# Exception - GitHub MCP calls (no pwsh prefix) +gh issue create --title "Feature" --body "Description" +``` + diff --git a/.github/instructions/md.instructions.md b/.github/instructions/md.instructions.md index 2608f82f..3b41f789 100644 --- a/.github/instructions/md.instructions.md +++ b/.github/instructions/md.instructions.md @@ -163,6 +163,32 @@ Using list when table is better: - Feature C: Partial - Beta feature ``` +## Requirement Number Formatting + +When writing or referencing requirement numbers (NFR and FR) in documentation: +- **Always use bold formatting** for requirement numbers +- **Replace hyphens with non-breaking hyphens** (`‑`) between letters and numbers +- This prevents line breaks within requirement numbers and ensures consistent formatting +- This applies to all specification documents, plans, and tables + +Examples: +```markdown +# Correct formatting +**NFR‑001**: The system must respond within 200ms +**FR‑042**: User authentication shall support OAuth 2.0 + +# In tables +| ID | Description | +|----|-------------| +| **NFR‑001** | Performance requirement | +| **FR‑042** | Authentication feature | + +# Incorrect formatting (do not use) +NFR-001: Without bold or non-breaking hyphen +**NFR-001**: Bold but with regular hyphen (can break across lines) +NFR‑001: Non-breaking hyphen but not bold +``` + ## Emphasis - Use `*` or `_` for emphasis (italic), `**` or `__` for strong emphasis (bold) diff --git a/.github/prompts/implement.prompt.md b/.github/prompts/implement.prompt.md index c06f4b43..7c3bd8f5 100644 --- a/.github/prompts/implement.prompt.md +++ b/.github/prompts/implement.prompt.md @@ -16,9 +16,27 @@ $ARGUMENTS **Iteration Support**: This command supports iterative implementation - you can run it multiple times to complete remaining tasks, fix issues, or add refinements. Task completion state is tracked in tasks.md with [X] markers. -1. Run [`.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks`](../../.specify/scripts/powershell/check-prerequisites.ps1) from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. +1. **Set Implementing label immediately**: + - **Determine target repository**: + - Check if `.fork-info.json` exists in the feature directory + - If it exists: + - Validate required fields: `is_fork` (true), `upstream_owner` (non-empty), `upstream_repo` (non-empty) + - Use `upstream_owner/upstream_repo` for all GitHub operations + - If it doesn't exist, use the current repository (origin) + - Get the issue number associated with the current feature branch + - **Add 'Implementing' label** to the issue and PR immediately in the target repository + - **Remove 'Planning' label** from the issue and PR + + **GitHub Integration**: If GitHub tools are available, update labels automatically in the target repository. If not available, use: + ```bash + # If fork: gh issue edit --repo / --remove-label "Planning" --add-label "Implementing" + # If local: gh issue edit --remove-label "Planning" --add-label "Implementing" + gh issue edit --remove-label "Planning" --add-label "Implementing" + ``` + +2. Run [`.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks`](../../.specify/scripts/powershell/check-prerequisites.ps1) from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. -2. Load and analyze the implementation context: +3. Load and analyze the implementation context: - **REQUIRED**: Read tasks.md for the complete task list and execution plan - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure - **IF EXISTS**: Read data-model.md for entities and relationships @@ -26,7 +44,7 @@ $ARGUMENTS - **IF EXISTS**: Read research.md for technical decisions and constraints - **IF EXISTS**: Read quickstart.md for integration scenarios -3. Parse tasks.md structure and extract: +4. Parse tasks.md structure and extract: - **Detect iteration state**: Check task completion markers - Tasks marked [X] are complete - skip unless user requests changes - Tasks marked [ ] are pending - these need implementation @@ -36,7 +54,7 @@ $ARGUMENTS - **Task details**: ID, description, file paths, parallel markers [P] - **Execution flow**: Order and dependency requirements -4. Execute implementation following the task plan: +5. Execute implementation following the task plan: - **Skip completed tasks**: Don't re-implement tasks marked [X] unless explicitly requested - **Resume from last incomplete task**: Start with first [ ] task found - **Phase-by-phase execution**: Complete each phase before moving to the next @@ -45,14 +63,14 @@ $ARGUMENTS - **File-based coordination**: Tasks affecting the same files must run sequentially - **Validation checkpoints**: Verify each phase completion before proceeding -5. Implementation execution rules: +6. Implementation execution rules: - **Setup first**: Initialize project structure, dependencies, and configuration - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios - **Core development**: Implement models, services, CLI commands, and endpoints - **Integration work**: Database connections, middleware, logging, and external services - **Polish and validation**: Unit tests, performance optimization, and documentation -6. Progress tracking and error handling: +7. Progress tracking and error handling: - Report progress after each completed task - Halt execution if any non-parallel task fails - For parallel tasks [P], continue with successful tasks and report failed ones @@ -60,14 +78,53 @@ $ARGUMENTS - Suggest next steps if implementation cannot proceed - **IMPORTANT**: For completed tasks, make sure to mark the task as [X] in the tasks file. -7. Completion validation: +8. Completion validation: - Verify all required tasks are completed - Check that implemented features match the original specification - Validate that tests pass and coverage meets requirements - Confirm the implementation follows the technical plan - Report final status with summary of completed work -8. Create or update Pull Request: +9. Update the constitution: + - Read the [Constitution](../../.specify/memory/constitution.md) file. + - Read the [constitution prompt](./constitution.prompt.md) for guidance on how to update the constitution. + - Update the constitution file with details on what has been implemented in this PR + - Document the functionality that was added or changed, remove the sections that are no longer relevant + - Ensure the constitution reflects the current state of the codebase + +10. Update the CHANGELOG: + - **Locate or create CHANGELOG.md** in the repository root + - **Add a new entry** for this feature/change following the Keep a Changelog format + - **Structure the entry** with: + * Version header (use `[Unreleased]` if version isn't determined yet) + * Date (current date) + * Category sections as applicable: + - `### Added` - for new features + - `### Changed` - for changes in existing functionality + - `### Deprecated` - for soon-to-be removed features + - `### Removed` - for now removed features + - `### Fixed` - for any bug fixes + - `### Security` - for vulnerability fixes + * Write entries from the user's perspective, focusing on what changed and why it matters + * Include brief usage examples where helpful + * Link to the PR or issue: `[#]` + - **Keep it concise**: Focus on user-impacting changes, not internal refactoring details + +11. Final commit and push: + - **Stage all implemented changes** including: + * All source code files created or modified + * Updated tasks.md with completed task markers [X] + * Updated CHANGELOG.md + * Updated constitution.md + * Any configuration or documentation files + - **Create a descriptive commit message**: + * Use conventional commit format: `(): ` + * Types: feat, fix, docs, refactor, test, chore + * Include reference to issue: `Fixes #` + - **Push the branch** to remote + - Verify the push completed successfully + +12. Update PR description with release notes: - **Determine workflow mode and target repository**: - Check if `.fork-info.json` exists in the feature directory (same directory as spec.md) - **If exists** (fork mode): @@ -95,58 +152,71 @@ $ARGUMENTS | Breaking change | 🌟 | Major | - Fallback PR title format (if issue title unavailable): ` [Type of change]: ` - - **PR description structure** (formatted as a release note): - * Start with a user-focused summary paragraph describing what's new, improved, or fixed - * Write in past tense, focusing on capabilities and user benefits (e.g., "Added support for...", "Improved performance of...", "Fixed issue where...") - * DO NOT add a title or heading before the leading paragraph - * Keep the tone professional and concise - this will be read as a release note - * At the end of the summary paragraph, add "- Fixes #" to link the PR to the issue - * Follow with additional release-note style details: - - **What's Changed**: Brief bullet points of key changes from the user's perspective - - **Technical Details** (optional): Implementation notes if relevant for maintainers - - **Breaking Changes** (if applicable): Clear warning and migration guidance - - **Usage** (if applicable): Brief example or updated command syntax - * Avoid superfluous headers, verbose explanations, or internal implementation details - * Focus on what changes for the end user or developer using this code + - **Write PR description as a release note**: + * **Opening summary** (1-2 paragraphs): + - Start with what was accomplished in user-focused language + - Write in past tense: "Added...", "Improved...", "Fixed..." + - Focus on the "why" - what problem does this solve or what capability does it enable? + - Mention the user impact - who benefits and how? + - At the end, add: "Fixes #" + * **What's Changed** section: + - 3-5 bullet points highlighting key changes from the user's perspective + - Focus on capabilities, not implementation details + - Example: "✨ Added support for custom templates" not "Created new Template class" + * **Usage** section (if applicable): + - Brief example showing how to use the new functionality + - Keep it minimal - just enough to get started + - Use code blocks for commands or code snippets + * **Breaking Changes** section (if applicable): + - Clear warning about what breaks + - Migration guidance for users + - What they need to change in their code + * **Technical Notes** section (optional, for maintainers): + - Brief implementation notes if relevant for reviewers + - Dependencies added or updated + - Architecture decisions + * **Tone and style**: + - Professional and concise + - Avoid jargon and internal terminology + - Write for the end user, not just developers + - This description will be used in release notes - **Apply appropriate label(s)** based on the type of change - **Link the PR** to the associated issue - - **After PR updates**: Update `.fork-info.json` (if it exists) with the latest PR number (if not already present) + - **Update `.fork-info.json`** (if it exists) with the latest PR number (if not already present) - **GitHub Integration**: If GitHub tools or integrations are available (such as GitHub MCP Server or other GitHub integrations), use them to update the PR status and labels automatically in the target repository. If not available, provide these fallback commands with the correct repository: - ```bash - # Mark PR as ready for review - # If fork: gh pr ready --repo / - # If local: gh pr ready - gh pr ready - - # Update PR title to match issue (if needed) - gh pr edit --title "" - - # Update labels - gh pr edit --add-label "" - ``` - -9. Update issue labels: - - **Determine target repository** (same logic as step 8): - - Check if `.fork-info.json` exists in the feature directory - - If it exists and validated, use `upstream_owner/upstream_repo` - - If it doesn't exist, use the current repository (origin) - - Remove 'plan' label from the linked issue in the target repository - - Add 'implement' label to the linked issue - - **After updating labels**: Ensure `.fork-info.json` (if it exists) has the issue number stored - - **GitHub Integration**: If GitHub tools are available, update labels automatically in the target repository. If not available, use: + **GitHub Integration**: If GitHub tools or integrations are available (such as GitHub MCP Server or other GitHub integrations), use them to update the PR description in the target repository. If not available, provide this fallback command: ```bash - # If fork: gh issue edit --repo / ... - # If local: gh issue edit ... - gh issue edit --remove-label "Plan" --add-label "Implementation" + # Update PR description + # If fork: gh pr edit --repo / --body "" + # If local: gh pr edit --body "" + gh pr edit --body "" ``` -10. Update the constitution: - - Read the [Constitution](../../.specify/memory/constitution.md) file. - - Read the [constitution prompt](./constitution.prompt.md) for guidance on how to update the constitution. - - Update the constitution file with details on what has been implemented in this PR - - Document the functionality that was added or changed, remove the sections that are no longer relevant - - Ensure the constitution reflects the current state of the codebase +13. Mark PR as ready for review: + - **Determine target repository** (same logic as step 12): + - Check if `.fork-info.json` exists in the feature directory + - If it exists and validated, use `upstream_owner/upstream_repo` + - If it doesn't exist, use the current repository (origin) + - **Remove 'Implementing' label** from the linked issue and the PR in the target repository + - **Mark PR as ready for review** (no longer draft) + - **After updates**: Ensure `.fork-info.json` (if it exists) has both issue and PR numbers stored + + **GitHub Integration**: If GitHub tools are available, update labels and PR status automatically in the target repository. If not available, use: + ```bash + # Mark PR as ready for review + # If fork: gh pr ready --repo / + # If local: gh pr ready + gh pr ready + + # Remove Implementing label from issue + # If fork: gh issue edit --repo / --remove-label "Implementing" + # If local: gh issue edit --remove-label "Implementing" + gh issue edit --remove-label "Implementing" + + # Remove Implementing label from PR + # If fork: gh pr edit --repo / --remove-label "Implementing" + # If local: gh pr edit --remove-label "Implementing" + gh pr edit --remove-label "Implementing" + ``` Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list. diff --git a/.github/prompts/plan.prompt.md b/.github/prompts/plan.prompt.md index 20f7601c..803155e0 100644 --- a/.github/prompts/plan.prompt.md +++ b/.github/prompts/plan.prompt.md @@ -18,21 +18,39 @@ $ARGUMENTS Given the implementation details provided as an argument, do this: -1. Run [`.specify/scripts/powershell/setup-plan.ps1 -Json`](../../.specify/scripts/powershell/setup-plan.ps1) from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute. +1. **Set Planning label immediately**: + - **Determine target repository**: + - Check if `.fork-info.json` exists in the feature directory + - If it exists: + - Validate required fields: `is_fork` (true), `upstream_owner` (non-empty), `upstream_repo` (non-empty) + - Use `upstream_owner/upstream_repo` for all GitHub operations + - If it doesn't exist, use the current repository (origin) + - Get the issue number associated with the current feature branch + - **Add 'Planning' label** to the issue immediately in the target repository + - **Remove 'Specification' label** from the issue + + **GitHub Integration**: If GitHub tools are available, update labels automatically in the target repository. If not available, use: + ```bash + # If fork: gh issue edit --repo / --remove-label "Specification" --add-label "Planning" + # If local: gh issue edit --remove-label "Specification" --add-label "Planning" + gh issue edit --remove-label "Specification" --add-label "Planning" + ``` + +2. Run [`.specify/scripts/powershell/setup-plan.ps1 -Json`](../../.specify/scripts/powershell/setup-plan.ps1) from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute. - **Detect iteration mode**: Check if IMPL_PLAN (plan.md) already exists: - **If exists**: You are ITERATING on an existing plan. User input should guide refinements/additions to the existing plan content. - **If not exists**: You are CREATING a new plan from scratch. - BEFORE proceeding, inspect FEATURE_SPEC for a `## Clarifications` section with at least one `Session` subheading. If missing or clearly ambiguous areas remain (vague adjectives, unresolved critical choices), PAUSE and instruct the user to run `/clarify` first to reduce rework. Only continue if: (a) Clarifications exist OR (b) an explicit user override is provided (e.g., "proceed without clarification"). Do not attempt to fabricate clarifications yourself. -2. Read and analyze the feature specification to understand: +3. Read and analyze the feature specification to understand: - The feature requirements and user stories - Functional and non-functional requirements - Success criteria and acceptance criteria - Any technical constraints or dependencies mentioned -3. Read the constitution at [`.specify/memory/constitution.md`](../../.specify/memory/constitution.md) to understand constitutional requirements. +4. Read the constitution at [`.specify/memory/constitution.md`](../../.specify/memory/constitution.md) to understand constitutional requirements. -4. Execute the implementation plan template: +5. Execute the implementation plan template: - Load [`.specify/templates/plan-template.md`](../../.specify/templates/plan-template.md) (already copied to IMPL_PLAN path) - Set Input path to FEATURE_SPEC - **If ITERATING** (plan.md exists): @@ -52,17 +70,17 @@ Given the implementation details provided as an argument, do this: - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS - Update Progress Tracking as you complete each phase -5. Verify execution completed: +6. Verify execution completed: - Check Progress Tracking shows all phases complete - Ensure all required artifacts were generated - Confirm no ERROR states in execution -6. Commit and push the changes: +7. Commit and push the changes: - Stage all generated artifacts and modified files - Create a commit with a descriptive message summarizing the plan - Push the branch (BRANCH) to remote -7. Create or update a Pull Request: +8. Create or update a Pull Request: - **Determine workflow mode and target repository**: - Check if `.fork-info.json` exists in the feature directory (same directory as spec.md) - **If exists** (fork mode): @@ -97,7 +115,9 @@ Given the implementation details provided as an argument, do this: * Follow with additional details answering Why, How, and What * Avoid superfluous headers or sections * We do not need details, we need to add what changes for the user of the code - - Apply appropriate label(s) based on the type of change + - **Apply appropriate labels to the PR**: + * **Version/change level label**: Based on the type of change: `Major`, `Minor`, `Patch`, `Fix`, or `Docs` + * **Phase label**: `Planning` (to indicate current phase) - Link the PR to the associated issue - **After PR creation**: Update `.fork-info.json` (if it exists) with the PR number: ```json @@ -114,29 +134,13 @@ Given the implementation details provided as an argument, do this: **GitHub Integration**: If GitHub tools or integrations are available (such as GitHub MCP Server or other GitHub integrations), use them to create/update the PR and manage labels automatically in the target repository. If not available, provide these fallback commands with the correct repository: ```bash - # Create draft PR - # If fork: gh pr create --repo / --draft ... - # If local: gh pr create --draft ... - gh pr create --draft --title " [Type]: " --body "" --label "" + # Create draft PR with both version/change level label and Planning label + # If fork: gh pr create --repo / --draft --title " [Type]: " --body "" --label ",Planning" + # If local: gh pr create --draft --title " [Type]: " --body "" --label ",Planning" + gh pr create --draft --title " [Type]: " --body "" --label ",Planning" # Link to issue (if not using "Fixes #" in body) - gh pr edit --add-label "" - ``` - -8. Update issue labels: - - **Determine target repository** (same logic as step 7): - - Check if `.fork-info.json` exists in the feature directory - - If it exists and validated, use `upstream_owner/upstream_repo` - - If it doesn't exist, use the current repository (origin) - - Remove 'specification' label from the linked issue in the target repository - - Add 'plan' label to the linked issue - - **After updating labels**: Update `.fork-info.json` (if it exists) with the issue number if not already present - - **GitHub Integration**: If GitHub tools are available, update labels automatically in the target repository. If not available, use: - ```bash - # If fork: gh issue edit --repo / ... - # If local: gh issue edit ... - gh issue edit --remove-label "Specification" --add-label "Plan" + gh pr edit --add-label ",Planning" ``` 9. **Post final status comment**: "✅ Planning complete. Ready for task generation with `/tasks` or analysis with `/analyze`." diff --git a/.github/prompts/specify.prompt.md b/.github/prompts/specify.prompt.md index 016579d2..813bce62 100644 --- a/.github/prompts/specify.prompt.md +++ b/.github/prompts/specify.prompt.md @@ -118,6 +118,7 @@ Given that feature description, do this: - **If IS_EXISTING_BRANCH is true**: - Update the existing issue associated with this feature branch (if one exists) with the refined specification - **Evaluate if the title needs updating**: If the feature scope has changed significantly (e.g., from patch to feature, or major functionality changes), update the issue title. For minor refinements or clarifications, keep the existing title. + - **Ensure Specification label**: Verify the issue has the 'Specification' label (indicates current phase) - **If IS_EXISTING_BRANCH is false** (new branch): Create a new GitHub issue with: - Title: Use the generated title format above - Body: The complete content of the SPEC_FILE (spec.md). Remove the first H1 (#) header and the first H2 (##) header if they exist. We want the PR description to start with the "Primary user story" section. diff --git a/.github/prompts/tasks.prompt.md b/.github/prompts/tasks.prompt.md index b1a9e22c..8ed82218 100644 --- a/.github/prompts/tasks.prompt.md +++ b/.github/prompts/tasks.prompt.md @@ -76,6 +76,10 @@ $ARGUMENTS - Clear file paths for each task - Dependency notes - Parallel execution guidance + - **IMPORTANT**: After each task in the task list, add a sub-step to update the PR description: + * Add: "After completing this task, update the PR description to mark this task as complete by changing `- [ ] T###:` to `- [X] T###:` in the Implementation Tasks section" + * This ensures that the PR description stays synchronized with actual progress + * Each task should have this update step included in its description or as a final action item 8. Update the Pull Request description: - **Determine workflow mode and target repository**: