Add specify! #195
Merged
Add specify! #195
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
… implementation processes
…dant files and simplifying repository configuration
…cy across documentation and scripts
- Updated implement.prompt.md to include workflow modes (Local and Fork) and iteration support for task completion tracking. - Enhanced plan.prompt.md with workflow modes, iteration detection, and refined task generation based on existing plans. - Improved specify.prompt.md to support fork contributions, detailed branch naming, and specification writing/updating processes. - Modified tasks.prompt.md to incorporate workflow modes, iteration detection, and task updating mechanisms. - Refined create-new-feature.ps1 script to manage branch creation based on current branch context and existing feature detection. - Added a new constitution-template.md for project governance and principles documentation. - Removed obsolete spec.md for the Merge CI and Main Workflows feature.
…consistency in technical and functional requirements
…nto 001-merge-workflows
Contributor
There was a problem hiding this comment.
Pull Request Overview
This pull request significantly enhances the documentation and workflow orchestration for the .specify project by restructuring templates, adding comprehensive style guidelines, and improving workflow automation. The changes focus on making the specification and implementation processes more robust, consistent, and maintainable.
Key changes:
- Restructured spec template with mandatory sections moved to the top for better visibility and completeness
- Enhanced workflow prompts with fork support, iteration capabilities, and automated GitHub integration
- Added comprehensive style guidelines for PowerShell and Markdown to ensure code and documentation consistency
Reviewed Changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
.specify/templates/spec-template.md |
Restructured template with requirements and user scenarios moved to top, improved table formatting for functional/non-functional requirements |
.specify/templates/plan-template.md |
Converted technical context from list to table format, updated constitution version reference |
.specify/templates/constitution-template.md |
New comprehensive template for project constitutions with placeholder structure |
.specify/scripts/powershell/create-new-feature.ps1 |
Enhanced branch management with existing feature detection and new BranchName parameter |
.github/prompts/tasks.prompt.md |
Added fork workflow support and iteration capabilities for task management |
.github/prompts/specify.prompt.md |
Major enhancements with fork detection, branch name generation, and GitHub integration |
.github/prompts/plan.prompt.md |
Added PR creation, issue management, and comprehensive workflow orchestration |
.github/prompts/implement.prompt.md |
Enhanced with iterative implementation, PR management, and constitution updates |
.github/prompts/constitution.prompt.md |
Comprehensive rewrite with creation/iteration modes and replacement analysis |
.github/instructions/pwsh.instructions.md |
New comprehensive PowerShell style guidelines covering all aspects of PS development |
.github/instructions/md.instructions.md |
New markdown style guidelines for consistent documentation formatting |
Comments suppressed due to low confidence (1)
.specify/templates/spec-template.md:1
- [nitpick] The NEEDS CLARIFICATION placeholders in the functional requirements table should be more specific about what information is needed. Consider using a more structured format like
[CLARIFY: <specific question>]to make it clearer what needs to be resolved."
# Feature Specification: [FEATURE NAME]
| $branchSuffix = $BranchName.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', '' | ||
| } else { | ||
| # Fallback: Generate from feature description (first 3 words) | ||
| $branchSuffix = $featureDesc.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', '' |
There was a problem hiding this comment.
This complex regex chain for sanitizing branch names is repeated multiple times in the script. Consider extracting it into a helper function like ConvertTo-SafeBranchName to reduce duplication and improve maintainability."
| - Focus on the primary change or feature being implemented | ||
| - Examples: "user-authentication", "merge-workflows", "api-rate-limiting", "fix-memory-leak" | ||
|
|
||
| 3. Run the script [`.specify/scripts/powershell/create-new-feature.ps1 -Json -FeatureDescription "$ARGUMENTS" -BranchName "<your-generated-name>"`](../../.specify/scripts/powershell/create-new-feature.ps1) from repo root and parse its JSON output for BRANCH_NAME, SPEC_FILE, and IS_EXISTING_BRANCH. All file paths must be absolute. |
There was a problem hiding this comment.
[nitpick] The instruction to use <your-generated-name> as a placeholder in the command is unclear. It should specify that this should be replaced with the actual generated branch name from step 2, or provide a more concrete example."
Suggested change
| 3. Run the script [`.specify/scripts/powershell/create-new-feature.ps1 -Json -FeatureDescription "$ARGUMENTS" -BranchName "<your-generated-name>"`](../../.specify/scripts/powershell/create-new-feature.ps1) from repo root and parse its JSON output for BRANCH_NAME, SPEC_FILE, and IS_EXISTING_BRANCH. All file paths must be absolute. | |
| 3. Run the script [`.specify/scripts/powershell/create-new-feature.ps1 -Json -FeatureDescription "$ARGUMENTS" -BranchName "<generated-branch-name-from-step-2>"`](../../.specify/scripts/powershell/create-new-feature.ps1) from repo root, replacing `<generated-branch-name-from-step-2>` with the branch name you generated in step 2. Parse its JSON output for BRANCH_NAME, SPEC_FILE, and IS_EXISTING_BRANCH. All file paths must be absolute. | |
| For example, if your generated branch name is `user-authentication`, the command would be: |
.specify/scripts/powershell/create-new-feature.ps1 -Json -FeatureDescription "$ARGUMENTS" -BranchName "user-authentication"
| ) | ||
| # Script-level variables | ||
| $ErrorActionPreference = 'Stop' |
There was a problem hiding this comment.
[nitpick] The examples show setting $ErrorActionPreference = 'Stop' at the script level, but this should include a warning about the impact on error handling throughout the script. Consider recommending setting this in specific scopes or functions rather than globally."
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This pull request makes significant improvements to the documentation and prompt instructions for project workflows, especially around constitution management and implementation processes. The changes clarify modes of operation, add detailed step-by-step instructions, and ensure consistency and traceability across related files and workflows.
Key changes:
Constitution Management Enhancements
.github/prompts/constitution.prompt.mdto support both initial creation and iterative updating of the constitution, with detailed operating modes, placeholder handling, and replacement analysis for overlapping principles or rules. Added a Replacement Analysis Table, heuristics for overlap detection, and clear handling for ambiguous or destructive changes. [1] [2].github/prompts/constitution.prompt.mdto clarify the iterative nature of constitution updates.Implementation Workflow Improvements
.github/prompts/implement.prompt.mdwith explicit support for both local and forked repository workflows, including detection of.fork-info.json, validation of fork configuration, and branch/PR management logic. [1] [2]tasks.md, skipping completed tasks, resuming from the last incomplete task, and supporting multiple runs for refinement.Documentation Consistency
.github/instructions/md.instructions.mdfile defining markdown style guidelines for consistent documentation across the repository, covering headings, lists, code blocks, links, tables, emphasis, whitespace, and more.These changes together provide clearer, more robust, and more maintainable workflows for both constitution management and implementation, ensuring consistency and traceability across documentation and project artifacts.
Type of change
Checklist