Skip to content

Commit ada4e8b

Browse files
MariusStorhaugMariusStorhaug
committed
🩹 [Patch]: Update prompts and templates for feature specification and implementation processes
1 parent 7e38e21 commit ada4e8b

File tree

7 files changed

+278
-48
lines changed

7 files changed

+278
-48
lines changed

‎.github/prompts/implement.prompt.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,4 +55,40 @@ $ARGUMENTS
5555
- Confirm the implementation follows the technical plan
5656
- Report final status with summary of completed work
5757

58+
8. Create or update Pull Request:
59+
- **Target branch**: The PR must be against the default branch
60+
- **PR status**: The PR must not be draft, it should be ready for review
61+
- **Determine PR type and icon** based on the changes:
62+
63+
| Type of change | Icon | Label |
64+
|-|-|-|
65+
| Docs | 📖 | Docs |
66+
| Fix | 🪲 | Fix, Patch |
67+
| Security fix | ⚠️ | Fix |
68+
| Patch | 🩹 | Patch |
69+
| Feature | 🚀 | Minor |
70+
| Breaking change | 🌟 | Major |
71+
72+
- **PR title format**: `<Icon> [Type of change]: <Short description>`
73+
- **PR description structure**:
74+
* Start with a summary paragraph describing the key outcome and changes for user
75+
* DO NOT add a title before the leading paragraph
76+
* At the end of the PR paragraph, add a "- Fixes #<issue-number>" line to link the PR to the issue
77+
* Follow with additional details answering Why, How, and What
78+
* Avoid superfluous headers or sections
79+
* We do not need details, we need to add what changes for the user of the code
80+
- **Apply appropriate label(s)** based on the type of change
81+
- **Link the PR** to the associated issue
82+
83+
9. Update issue labels:
84+
- Remove 'plan' label from the linked issue
85+
- Add 'implement' label to the linked issue
86+
87+
10. Update the constitution:
88+
- Read the [Constitution](../../.specify/memory/constitution.md) file.
89+
- Read the [constitution prompt](./constitution.prompt.md) for guidance on how to update the constitution.
90+
- Update the constitution file with details on what has been implemented in this PR
91+
- Document the functionality that was added or changed, remove the sections that are no longer relevant
92+
- Ensure the constitution reflects the current state of the codebase
93+
5894
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.

‎.github/prompts/plan.prompt.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,40 @@ Given the implementation details provided as an argument, do this:
4040
- Ensure all required artifacts were generated
4141
- Confirm no ERROR states in execution
4242

43-
6. Report results with branch name, file paths, and generated artifacts.
43+
6. Commit and push the changes:
44+
- Stage all generated artifacts and modified files
45+
- Create a commit with a descriptive message summarizing the plan
46+
- Push the branch (BRANCH) to remote
47+
48+
7. Create or update a Pull Request:
49+
- The PR must be against the default branch.
50+
- The PR must be opened as a draft.
51+
- Determine the PR type and icon based on the changes:
52+
53+
| Type of change | Icon | Label |
54+
|-|-|-|
55+
| Docs | 📖 | Docs |
56+
| Fix | 🪲 | Fix, Patch |
57+
| Security fix | ⚠️ | Fix |
58+
| Patch | 🩹 | Patch |
59+
| Feature | 🚀 | Minor |
60+
| Breaking change | 🌟 | Major |
61+
62+
- Create PR title: `<Icon> [Type of change]: <Short description>`
63+
- Create PR description:
64+
* Start with a summary paragraph describing the key outcome and changes for user
65+
* DO NOT add a title before the leading paragraph
66+
* At the end of the PR paragraph, add a "- Fixes #<issue-number>" line to link the PR to the issue
67+
* Follow with additional details answering Why, How, and What
68+
* Avoid superfluous headers or sections
69+
* We do not need details, we need to add what changes for the user of the code
70+
- Apply appropriate label(s) based on the type of change
71+
- Link the PR to the associated issue
72+
73+
8. Update issue labels:
74+
- Remove 'specification' label from the linked issue
75+
- Add 'plan' label to the linked issue
76+
77+
9. Report results with branch name, PR URL, file paths, and generated artifacts.
4478

4579
Use absolute paths with the repository root for all file operations to avoid path issues.

‎.github/prompts/specify.prompt.md‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,25 @@ The text the user typed after `/specify` in the triggering message **is** the fe
1414

1515
Given that feature description, do this:
1616

17-
1. Run the script `.specify/scripts/powershell/create-new-feature.ps1 -Json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
17+
1. Analyze the feature description and generate a concise, descriptive branch name:
18+
- Extract the core concept/action from the description (2-4 words maximum)
19+
- Use kebab-case format (lowercase, hyphen-separated)
20+
- Focus on the primary change or feature being implemented
21+
- Examples: "user-authentication", "merge-workflows", "api-rate-limiting", "fix-memory-leak"
22+
2. Run the script `.specify/scripts/powershell/create-new-feature.ps1 -Json "$ARGUMENTS" -BranchName "<your-generated-name>"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
1823
**IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for.
19-
2. Load `.specify/templates/spec-template.md` to understand required sections.
20-
3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
21-
4. Report completion with branch name, spec file path, and readiness for the next phase.
24+
**NOTE** The script will prepend an auto-incremented feature number (e.g., `003-`) to your branch name.
25+
3. Load `.specify/templates/spec-template.md` to understand required sections.
26+
4. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
27+
5. Create a GitHub issue for this feature with:
28+
- Title: Format as `<Icon> [Type]: <Feature name>` where:
29+
- Icon: 📖 (Docs), 🪲 (Fix), ⚠️ (Security fix), 🩹 (Patch), 🚀 (Feature/Minor), 🌟 (Breaking change/Major)
30+
- Type: Docs, Fix, Patch, Feature, or Breaking change
31+
- Feature name: Short description from the spec
32+
- Body: The complete content of the SPEC_FILE (spec.md)
33+
- Labels:
34+
- `Specification` (always - indicates current phase)
35+
- Type-based label: `Docs`, `Fix`, `Patch`, `Minor`, or `Major` based on the type of change
36+
6. Report completion with branch name, spec file path, issue number, and readiness for the next phase.
2237

2338
Note: The script creates and checks out the new branch and initializes the spec file before writing.

‎.specify/scripts/powershell/create-new-feature.ps1‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44
param(
55
[switch]$Json,
66
[Parameter(ValueFromRemainingArguments = $true)]
7-
[string[]]$FeatureDescription
7+
[string[]]$FeatureDescription,
8+
[Parameter()]
9+
[string]$BranchName
810
)
911
$ErrorActionPreference = 'Stop'
1012

@@ -52,9 +54,18 @@ if (Test-Path $specsDir) {
5254
$next = $highest + 1
5355
$featureNum = ('{0:000}' -f $next)
5456

55-
$branchName = $featureDesc.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''
56-
$words = ($branchName -split '-') | Where-Object { $_ } | Select-Object -First 3
57-
$branchName = "$featureNum-$([string]::Join('-', $words))"
57+
# Use provided BranchName if available, otherwise generate from feature description
58+
if ($BranchName) {
59+
# Sanitize the provided branch name
60+
$branchSuffix = $BranchName.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''
61+
} else {
62+
# Fallback: Generate from feature description (first 3 words)
63+
$branchSuffix = $featureDesc.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''
64+
$words = ($branchSuffix -split '-') | Where-Object { $_ } | Select-Object -First 3
65+
$branchSuffix = [string]::Join('-', $words)
66+
}
67+
68+
$branchName = "$featureNum-$branchSuffix"
5869

5970
if ($hasGit) {
6071
try {

‎.specify/templates/plan-template.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -267,4 +267,4 @@ directories captured above]
267267
- [ ] Complexity deviations documented
268268

269269
---
270-
*Based on Constitution v1.3.0 - See `.specify/memory/constitution.md`*
270+
*Based on Constitution - See `.specify/memory/constitution.md`*

‎.specify/templates/spec-template.md‎

Lines changed: 38 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,43 @@
11
# Feature Specification: [FEATURE NAME]
22

3+
## User Scenarios & Testing *(mandatory)*
4+
5+
### Primary User Story
6+
7+
[Describe the main user journey in plain language]
8+
9+
### Acceptance Scenarios
10+
11+
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
12+
2. **Given** [initial state], **When** [action], **Then** [expected outcome]
13+
14+
### Edge Cases
15+
16+
- What happens when [boundary condition]?
17+
- How does system handle [error scenario]?
18+
19+
## Requirements *(mandatory)*
20+
21+
### Functional Requirements
22+
23+
- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
24+
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
25+
- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
26+
- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
27+
- **FR-005**: System MUST [behavior, e.g., "log all security events"]
28+
29+
Example of marking unclear requirements:
30+
31+
- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
32+
- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
33+
34+
### Key Entities *(include if feature involves data)*
35+
36+
- **[Entity 1]**: [What it represents, key attributes without implementation]
37+
- **[Entity 2]**: [What it represents, relationships to other entities]
38+
39+
---
40+
341
**Feature Branch**: `[###-feature-name]`
442
**Created**: [DATE]
543
**Status**: Draft
@@ -55,44 +93,6 @@ When creating this spec from a user prompt:
5593

5694
---
5795

58-
## User Scenarios & Testing *(mandatory)*
59-
60-
### Primary User Story
61-
62-
[Describe the main user journey in plain language]
63-
64-
### Acceptance Scenarios
65-
66-
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
67-
2. **Given** [initial state], **When** [action], **Then** [expected outcome]
68-
69-
### Edge Cases
70-
71-
- What happens when [boundary condition]?
72-
- How does system handle [error scenario]?
73-
74-
## Requirements *(mandatory)*
75-
76-
### Functional Requirements
77-
78-
- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
79-
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
80-
- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
81-
- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
82-
- **FR-005**: System MUST [behavior, e.g., "log all security events"]
83-
84-
Example of marking unclear requirements:
85-
86-
- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
87-
- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
88-
89-
### Key Entities *(include if feature involves data)*
90-
91-
- **[Entity 1]**: [What it represents, key attributes without implementation]
92-
- **[Entity 2]**: [What it represents, relationships to other entities]
93-
94-
---
95-
9696
## Review & Acceptance Checklist
9797

9898
*GATE: Automated checks run during main() execution*

‎specs/002-merge-ci-yml/spec.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Feature Specification: Merge CI.yml into Workflow.yml
2+
3+
## User Scenarios & Testing
4+
5+
### Primary User Story
6+
7+
As a PowerShell module maintainer using the Process-PSModule framework, I want a single reusable workflow file that intelligently handles pull requests (with optional preview publishing), merged releases (with full publishing), and scheduled/manual test runs (without publishing), so that my repository configuration is simpler with fewer workflow files to maintain and the Nightly-Run.yml workflow is no longer needed.
8+
9+
### Acceptance Scenarios
10+
11+
1. **Given** a pull request is opened, **When** the workflow runs, **Then** all build/test/lint jobs execute and publish jobs run but skip publishing unless the PR has a "preview" label
12+
2. **Given** a pull request with "preview" label is opened, **When** the workflow runs, **Then** the full pipeline executes including module and documentation publishing to preview environments
13+
3. **Given** a pull request is merged to main, **When** the workflow runs, **Then** the full pipeline executes including module publishing to PowerShell Gallery and documentation deployment to GitHub Pages
14+
4. **Given** the workflow is triggered by workflow_dispatch or schedule (nightly), **When** the workflow runs, **Then** all build/test/lint jobs execute but publish jobs (Publish-Site, Publish-Module) are skipped
15+
5. **Given** test jobs fail during execution, **When** the workflow continues, **Then** code coverage aggregation and test result summarization still complete successfully
16+
6. **Given** a repository currently uses both Process-PSModule.yml and Nightly-Run.yml, **When** migrated to the unified workflow, **Then** only Process-PSModule.yml is needed with workflow_dispatch and schedule triggers added
17+
18+
### Edge Cases
19+
20+
- What happens when a pull request is created? → Should run full pipeline including publish jobs, but publish jobs contain logic to skip unless PR has "preview" label
21+
- What happens when a pull request is merged to main? → Should run full pipeline including all publishing steps
22+
- How does the system handle test failures? → Should continue to completion, including code coverage and test result summarization (existing behavior)
23+
- What happens when triggered by workflow_dispatch or schedule (nightly run)? → Should run all build/test/lint jobs but skip publishing steps (replaces separate Nightly-Run.yml workflow)
24+
- What happens if a repository only needs CI functionality? → Not applicable - all repositories using Process-PSModule run the full workflow
25+
26+
---
27+
28+
## Requirements
29+
30+
### Functional Requirements
31+
32+
- **FR-001**: System MUST preserve all job definitions from CI.yml (Get-Settings, Build-Module, Build-Docs, Build-Site, Test-SourceCode, Lint-SourceCode, Test-Module, Test-ModuleLocal, BeforeAll-ModuleLocal, AfterAll-ModuleLocal, Get-TestResults, Get-CodeCoverage)
33+
- **FR-002**: System MUST preserve all job definitions from workflow.yml (all jobs from CI.yml plus Publish-Site and Publish-Module)
34+
- **FR-003**: System MUST maintain identical input parameters as defined in both workflows (Name, SettingsPath, Debug, Verbose, Version, Prerelease, WorkingDirectory)
35+
- **FR-004**: System MUST maintain identical secrets definitions as defined in both workflows (APIKey, TEST_APP_ENT_CLIENT_ID, TEST_APP_ENT_PRIVATE_KEY, TEST_APP_ORG_CLIENT_ID, TEST_APP_ORG_PRIVATE_KEY, TEST_USER_ORG_FG_PAT, TEST_USER_USER_FG_PAT, TEST_USER_PAT)
36+
- **FR-005**: System MUST support workflow_dispatch trigger to allow manual workflow execution
37+
- **FR-006**: System MUST support schedule trigger for nightly automated test runs
38+
- **FR-007**: Publish-Site job MUST execute when a pull request is merged to main and all prerequisite jobs succeed
39+
- **FR-008**: Publish-Module job MUST execute when a pull request is merged to main and all prerequisite jobs succeed
40+
- **FR-009**: Publish-Site job MUST execute when a pull request has the "preview" label and is not merged
41+
- **FR-010**: Publish-Module job MUST execute when a pull request has the "preview" label and is not merged (with preview/prerelease publishing logic)
42+
- **FR-011**: Publish-Site and Publish-Module jobs MUST be skipped when triggered via workflow_dispatch or schedule
43+
- **FR-012**: System MUST maintain all job dependencies and execution order as defined in the original workflows
44+
- **FR-013**: System MUST continue executing code coverage and test result jobs even when test jobs fail
45+
- **FR-014**: System MUST maintain all conditional logic for job execution (if conditions) from both workflows
46+
- **FR-015**: Repositories using Process-PSModule MUST be able to reference a single workflow file for all execution modes (PR, merge, scheduled, manual)
47+
- **FR-016**: CI.yml file MUST be removed after successful migration to prevent confusion
48+
- **FR-017**: Nightly-Run.yml workflow in module repositories MUST be removed as its functionality is absorbed into the unified workflow
49+
- **FR-018**: Unified workflow MUST use write permissions (contents: write, pull-requests: write, statuses: write, pages: write, id-token: write) to support all execution modes
50+
51+
### Key Entities
52+
53+
- **CI.yml Workflow**: GitHub Actions reusable workflow file that currently handles continuous integration tasks (build, test, lint) with read-only permissions, used by Nightly-Run.yml for scheduled testing
54+
- **workflow.yml Workflow**: GitHub Actions reusable workflow file that handles full pipeline including CI tasks plus publishing (site deployment, module publishing) with write permissions, used for pull request workflows
55+
- **Nightly-Run.yml**: Repository-level workflow in module repos that triggers CI.yml on a schedule or manual dispatch for testing without publishing
56+
- **Process-PSModule.yml**: Repository-level workflow in module repos that triggers workflow.yml for pull request and merge operations
57+
- **Job Definitions**: Reusable workflow jobs that perform specific operations (Get-Settings, Build-Module, Test-Module, etc.)
58+
- **Publish Jobs**: Publish-Site and Publish-Module jobs that deploy documentation and modules, with conditional execution based on trigger type and PR labels
59+
- **Trigger Types**: Different invocation methods (pull_request opened/synchronized, pull_request merged, workflow_dispatch, schedule) that determine which jobs execute
60+
- **Preview Label**: Pull request label that enables preview publishing for testing changes before merge
61+
- **Permissions**: GitHub Actions permission sets that control what the workflow can do (write permissions needed for all modes)
62+
63+
---
64+
65+
**Feature Branch**: `002-merge-ci-yml`
66+
**Created**: 2025-10-02
67+
**Status**: Draft
68+
**Input**: User description: "Merge ci.yml into workflow.yml, so that we can deduplicate and two workflows and have less workflows in the repos that use this process."
69+
70+
## Execution Flow (main)
71+
72+
1. Parse user description from Input
73+
→ Feature description is clear: consolidate two similar workflow files
74+
2. Extract key concepts from description
75+
→ Actors: PowerShell module maintainers, CI/CD pipeline
76+
→ Actions: Merge workflows, deduplicate configuration, reduce workflow count
77+
→ Data: Workflow YAML files, job definitions, permissions
78+
→ Constraints: Must maintain existing functionality
79+
3. For each unclear aspect:
80+
→ No major ambiguities; requirements are well-defined
81+
4. Fill User Scenarios & Testing section
82+
→ Primary user flow: Repository using Process-PSModule framework references a single workflow
83+
5. Generate Functional Requirements
84+
→ Requirements focus on workflow consolidation and preservation of functionality
85+
6. Identify Key Entities
86+
→ CI.yml workflow, workflow.yml, job definitions, permissions
87+
7. Run Review Checklist
88+
→ No implementation details included; focused on user value
89+
8. Return: SUCCESS (spec ready for planning)
90+
91+
---
92+
93+
## ⚡ Quick Guidelines
94+
95+
- ✅ Focus on WHAT users need and WHY
96+
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
97+
- 👥 Written for business stakeholders, not developers
98+
99+
### Section Requirements
100+
101+
- **Mandatory sections**: Must be completed for every feature
102+
- **Optional sections**: Include only when relevant to the feature
103+
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
104+
105+
---
106+
107+
## Review & Acceptance Checklist
108+
109+
### Content Quality
110+
111+
- [x] No implementation details (languages, frameworks, APIs)
112+
- [x] Focused on user value and business needs
113+
- [x] Written for non-technical stakeholders
114+
- [x] All mandatory sections completed
115+
116+
### Requirement Completeness
117+
118+
- [x] No [NEEDS CLARIFICATION] markers remain
119+
- [x] Requirements are testable and unambiguous
120+
- [x] Success criteria are measurable
121+
- [x] Scope is clearly bounded
122+
- [x] Dependencies and assumptions identified
123+
124+
---
125+
126+
## Execution Status
127+
128+
- [x] User description parsed
129+
- [x] Key concepts extracted
130+
- [x] Ambiguities marked (none identified)
131+
- [x] User scenarios defined
132+
- [x] Requirements generated
133+
- [x] Entities identified
134+
- [x] Review checklist passed

0 commit comments

Comments
 (0)