You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Description
This pull request updates and clarifies the workflow instructions for
planning and implementing features, with a strong focus on correct
GitHub label management, improved documentation standards, and enhanced
PR/release note formatting. The changes ensure that contributors follow
standardized processes for labeling, documentation, and communication,
making the workflow more consistent and user-friendly.
**Workflow and Label Management Improvements:**
* Both `.github/prompts/plan.prompt.md` and
`.github/prompts/implement.prompt.md` now require setting and updating
GitHub labels (like `Planning`, `Implementing`, `Specification`) at the
start of each workflow, with clear instructions for both forked and
local repositories. Fallback `gh` CLI commands are provided for manual
updates.
[[1]](diffhunk://#diff-68a2c56959d80cc612e224742a5036c1110c7d7242c7970cea384847a63d2f74L21-R53)
[[2]](diffhunk://#diff-68a2c56959d80cc612e224742a5036c1110c7d7242c7970cea384847a63d2f74L117-R143)
[[3]](diffhunk://#diff-c7d6853d6175b556ba7b64b7764e390cbbb6e49f9b76e9102e979225f4910d4dL19-R47)
[[4]](diffhunk://#diff-c7d6853d6175b556ba7b64b7764e390cbbb6e49f9b76e9102e979225f4910d4dL98-R220)
* The implementation workflow now includes immediate label transitions
(e.g., removing `Planning` and adding `Implementing`), and the planning
workflow adds/removes `Planning` and `Specification` as appropriate.
[[1]](diffhunk://#diff-c7d6853d6175b556ba7b64b7764e390cbbb6e49f9b76e9102e979225f4910d4dL19-R47)
[[2]](diffhunk://#diff-68a2c56959d80cc612e224742a5036c1110c7d7242c7970cea384847a63d2f74L21-R53)
**Documentation and Formatting Standards:**
* Added a new section in `.github/instructions/md.instructions.md`
specifying that all requirement numbers (e.g., NFR-001, FR-042) must be
formatted in bold and use non-breaking hyphens to prevent line breaks
and ensure consistency in all documentation.
* `.github/copilot-instructions.md` now mandates that all terminal
commands in documentation be prefixed with `pwsh` (except for GitHub MCP
calls), with examples provided for clarity.
**PR and Release Note Guidance:**
* The instructions for PR descriptions have been rewritten to require a
user-focused, release-note style summary, with explicit sections for
"What's Changed," "Usage," "Breaking Changes," and "Technical Notes."
Example command-line instructions for updating PR descriptions are
included.
* The planning workflow now requires PRs to include both a
version/change-level label (e.g., Major, Minor, Patch) and a phase label
(Planning), with fallback CLI commands for label management.
[[1]](diffhunk://#diff-68a2c56959d80cc612e224742a5036c1110c7d7242c7970cea384847a63d2f74L100-R120)
[[2]](diffhunk://#diff-68a2c56959d80cc612e224742a5036c1110c7d7242c7970cea384847a63d2f74L117-R143)
**Workflow Step Clarifications and Reordering:**
* Both planning and implementation prompts have been restructured and
renumbered for clarity, with explicit instructions for each step,
including constitution and changelog updates, commit message standards,
and final PR/issue updates.
[[1]](diffhunk://#diff-c7d6853d6175b556ba7b64b7764e390cbbb6e49f9b76e9102e979225f4910d4dL39-R57)
[[2]](diffhunk://#diff-c7d6853d6175b556ba7b64b7764e390cbbb6e49f9b76e9102e979225f4910d4dL48-R127)
[[3]](diffhunk://#diff-68a2c56959d80cc612e224742a5036c1110c7d7242c7970cea384847a63d2f74L55-R83)
**Changelog and Constitution Updates:**
* The implementation workflow now explicitly requires updating both the
constitution and the changelog with each feature or change, following
best practices for documentation and release management.
These changes collectively enforce best practices for workflow
automation, documentation, and communication in the repository,
improving clarity and consistency for all contributors.
## Type of change
<!-- Use the check-boxes [x] on the options that are relevant. -->
- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [x] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [ ] 🌟 [Breaking change]
## Checklist
<!-- Use the check-boxes [x] on the options that are relevant. -->
- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas
**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.
18
18
19
-
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.
19
+
1.**Set Implementing label immediately**:
20
+
-**Determine target repository**:
21
+
- Check if `.fork-info.json` exists in the feature directory
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.
20
38
21
-
2. Load and analyze the implementation context:
39
+
3. Load and analyze the implementation context:
22
40
-**REQUIRED**: Read tasks.md for the complete task list and execution plan
23
41
-**REQUIRED**: Read plan.md for tech stack, architecture, and file structure
24
42
-**IF EXISTS**: Read data-model.md for entities and relationships
25
43
-**IF EXISTS**: Read contracts/ for API specifications and test requirements
26
44
-**IF EXISTS**: Read research.md for technical decisions and constraints
27
45
-**IF EXISTS**: Read quickstart.md for integration scenarios
-**Resume from last incomplete task**: Start with first [] task found
42
60
-**Phase-by-phase execution**: Complete each phase before moving to the next
@@ -45,29 +63,68 @@ $ARGUMENTS
45
63
-**File-based coordination**: Tasks affecting the same files must run sequentially
46
64
-**Validation checkpoints**: Verify each phase completion before proceeding
47
65
48
-
5. Implementation execution rules:
66
+
6. Implementation execution rules:
49
67
-**Setup first**: Initialize project structure, dependencies, and configuration
50
68
-**Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
51
69
-**Core development**: Implement models, services, CLI commands, and endpoints
52
70
-**Integration work**: Database connections, middleware, logging, and external services
53
71
-**Polish and validation**: Unit tests, performance optimization, and documentation
54
72
55
-
6. Progress tracking and error handling:
73
+
7. Progress tracking and error handling:
56
74
- Report progress after each completed task
57
75
- Halt execution if any non-parallel task fails
58
76
- For parallel tasks [P], continue with successful tasks and report failed ones
59
77
- Provide clear error messages with context for debugging
60
78
- Suggest next steps if implementation cannot proceed
61
79
-**IMPORTANT**: For completed tasks, make sure to mark the task as [X] in the tasks file.
62
80
63
-
7. Completion validation:
81
+
8. Completion validation:
64
82
- Verify all required tasks are completed
65
83
- Check that implemented features match the original specification
66
84
- Validate that tests pass and coverage meets requirements
67
85
- Confirm the implementation follows the technical plan
68
86
- Report final status with summary of completed work
69
87
70
-
8. Create or update Pull Request:
88
+
9. Update the constitution:
89
+
- Read the [Constitution](../../.specify/memory/constitution.md) file.
90
+
- Read the [constitution prompt](./constitution.prompt.md) for guidance on how to update the constitution.
91
+
- Update the constitution file with details on what has been implemented in this PR
92
+
- Document the functionality that was added or changed, remove the sections that are no longer relevant
93
+
- Ensure the constitution reflects the current state of the codebase
94
+
95
+
10. Update the CHANGELOG:
96
+
-**Locate or create CHANGELOG.md** in the repository root
97
+
-**Add a new entry** for this feature/change following the Keep a Changelog format
98
+
-**Structure the entry** with:
99
+
* Version header (use `[Unreleased]` if version isn't determined yet)
100
+
* Date (current date)
101
+
* Category sections as applicable:
102
+
-`### Added` - for new features
103
+
-`### Changed` - for changes in existing functionality
104
+
-`### Deprecated` - for soon-to-be removed features
105
+
-`### Removed` - for now removed features
106
+
-`### Fixed` - for any bug fixes
107
+
-`### Security` - for vulnerability fixes
108
+
* Write entries from the user's perspective, focusing on what changed and why it matters
109
+
* Include brief usage examples where helpful
110
+
* Link to the PR or issue: `[#<issue-number>]`
111
+
-**Keep it concise**: Focus on user-impacting changes, not internal refactoring details
112
+
113
+
11. Final commit and push:
114
+
-**Stage all implemented changes** including:
115
+
* All source code files created or modified
116
+
* Updated tasks.md with completed task markers [X]
117
+
* Updated CHANGELOG.md
118
+
* Updated constitution.md
119
+
* Any configuration or documentation files
120
+
-**Create a descriptive commit message**:
121
+
* Use conventional commit format: `<type>(<scope>): <description>`
122
+
* Types: feat, fix, docs, refactor, test, chore
123
+
* Include reference to issue: `Fixes #<issue-number>`
124
+
-**Push the branch** to remote
125
+
- Verify the push completed successfully
126
+
127
+
12. Update PR description with release notes:
71
128
-**Determine workflow mode and target repository**:
72
129
- Check if `.fork-info.json` exists in the feature directory (same directory as spec.md)
73
130
-**If exists** (fork mode):
@@ -95,58 +152,71 @@ $ARGUMENTS
95
152
| Breaking change | 🌟 | Major |
96
153
97
154
- Fallback PR title format (if issue title unavailable): `<Icon> [Type of change]: <Short description>`
98
-
-**PR description structure** (formatted as a release note):
99
-
* Start with a user-focused summary paragraph describing what's new, improved, or fixed
100
-
* Write in past tense, focusing on capabilities and user benefits (e.g., "Added support for...", "Improved performance of...", "Fixed issue where...")
101
-
* DO NOT add a title or heading before the leading paragraph
102
-
* Keep the tone professional and concise - this will be read as a release note
103
-
* At the end of the summary paragraph, add "- Fixes #<issue-number>" to link the PR to the issue
104
-
* Follow with additional release-note style details:
105
-
-**What's Changed**: Brief bullet points of key changes from the user's perspective
106
-
-**Technical Details** (optional): Implementation notes if relevant for maintainers
107
-
-**Breaking Changes** (if applicable): Clear warning and migration guidance
108
-
-**Usage** (if applicable): Brief example or updated command syntax
109
-
* Avoid superfluous headers, verbose explanations, or internal implementation details
110
-
* Focus on what changes for the end user or developer using this code
155
+
-**Write PR description as a release note**:
156
+
***Opening summary** (1-2 paragraphs):
157
+
- Start with what was accomplished in user-focused language
158
+
- Write in past tense: "Added...", "Improved...", "Fixed..."
159
+
- Focus on the "why" - what problem does this solve or what capability does it enable?
160
+
- Mention the user impact - who benefits and how?
161
+
- At the end, add: "Fixes #<issue-number>"
162
+
***What's Changed** section:
163
+
- 3-5 bullet points highlighting key changes from the user's perspective
164
+
- Focus on capabilities, not implementation details
165
+
- Example: "✨ Added support for custom templates" not "Created new Template class"
166
+
***Usage** section (if applicable):
167
+
- Brief example showing how to use the new functionality
168
+
- Keep it minimal - just enough to get started
169
+
- Use code blocks for commands or code snippets
170
+
***Breaking Changes** section (if applicable):
171
+
- Clear warning about what breaks
172
+
- Migration guidance for users
173
+
- What they need to change in their code
174
+
***Technical Notes** section (optional, for maintainers):
175
+
- Brief implementation notes if relevant for reviewers
176
+
- Dependencies added or updated
177
+
- Architecture decisions
178
+
***Tone and style**:
179
+
- Professional and concise
180
+
- Avoid jargon and internal terminology
181
+
- Write for the end user, not just developers
182
+
- This description will be used in release notes
111
183
-**Apply appropriate label(s)** based on the type of change
112
184
-**Link the PR** to the associated issue
113
-
-**After PR updates**: Update `.fork-info.json` (if it exists) with the latest PR number (if not already present)
185
+
-**Update `.fork-info.json`** (if it exists) with the latest PR number (if not already present)
114
186
115
-
**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:
116
-
```bash
117
-
# Mark PR as ready for review
118
-
# If fork: gh pr ready <PR-number> --repo <upstream_owner>/<upstream_repo>
119
-
# If local: gh pr ready <PR-number>
120
-
gh pr ready <PR-number>
121
-
122
-
# Update PR title to match issue (if needed)
123
-
gh pr edit <PR-number> --title "<Issue title>"
124
-
125
-
# Update labels
126
-
gh pr edit <PR-number> --add-label "<Type>"
127
-
```
128
-
129
-
9. Update issue labels:
130
-
-**Determine target repository** (same logic as step 8):
131
-
- Check if `.fork-info.json` exists in the feature directory
132
-
- If it exists and validated, use `upstream_owner/upstream_repo`
133
-
- If it doesn't exist, use the current repository (origin)
134
-
- Remove 'plan' label from the linked issue in the target repository
135
-
- Add 'implement' label to the linked issue
136
-
-**After updating labels**: Ensure `.fork-info.json` (if it exists) has the issue number stored
137
-
138
-
**GitHub Integration**: If GitHub tools are available, update labels automatically in the target repository. If not available, use:
187
+
**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:
139
188
```bash
140
-
# If fork: gh issue edit <issue-number> --repo <upstream_owner>/<upstream_repo> ...
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.
0 commit comments