Skip to content

Commit 2dfe6ad

Browse files
MariusStorhaugMariusStorhaug
committed
feat: Add prompts for project management workflows including constitution, planning, implementation, tasks, and PR creation
- Introduced new prompt files for managing project workflows: - PSModule.constitution.prompt.md: Create or update project constitution. - PSModule.plan.prompt.md: Execute implementation planning workflow. - PSModule.implement.prompt.md: Execute implementation plan and manage tasks. - PSModule.tasks.prompt.md: Generate actionable tasks based on design artifacts. - PSModule.pr.prompt.md: Create or update pull requests with structured descriptions. - Updated VSCode settings to recommend new prompt files and enable auto-approval for script execution.
1 parent 2b3ebbc commit 2dfe6ad

9 files changed

+1181
-0
lines changed

‎.github/prompts/PSModule.analyze.prompt.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
3+
---
4+
5+
# Analyze
6+
7+
The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
8+
9+
User input:
10+
11+
$ARGUMENTS
12+
13+
Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
14+
15+
STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
16+
17+
Constitution Authority: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
18+
19+
Execution steps:
20+
21+
1. Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
22+
- SPEC = FEATURE_DIR/spec.md
23+
- PLAN = FEATURE_DIR/plan.md
24+
- TASKS = FEATURE_DIR/tasks.md
25+
Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
26+
27+
2. Load artifacts:
28+
- Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present).
29+
- Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints.
30+
- Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths.
31+
- Load constitution `.specify/memory/constitution.md` for principle validation.
32+
33+
3. Build internal semantic models:
34+
- Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`).
35+
- User story/action inventory.
36+
- Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases).
37+
- Constitution rule set: Extract principle names and any MUST/SHOULD normative statements.
38+
39+
4. Detection passes:
40+
A. Duplication detection:
41+
- Identify near-duplicate requirements. Mark lower-quality phrasing for consolidation.
42+
B. Ambiguity detection:
43+
- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria.
44+
- Flag unresolved placeholders (TODO, TKTK, ???, <placeholder>, etc.).
45+
C. Underspecification:
46+
- Requirements with verbs but missing object or measurable outcome.
47+
- User stories missing acceptance criteria alignment.
48+
- Tasks referencing files or components not defined in spec/plan.
49+
D. Constitution alignment:
50+
- Any requirement or plan element conflicting with a MUST principle.
51+
- Missing mandated sections or quality gates from constitution.
52+
E. Coverage gaps:
53+
- Requirements with zero associated tasks.
54+
- Tasks with no mapped requirement/story.
55+
- Non-functional requirements not reflected in tasks (e.g., performance, security).
56+
F. Inconsistency:
57+
- Terminology drift (same concept named differently across files).
58+
- Data entities referenced in plan but absent in spec (or vice versa).
59+
- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note).
60+
- Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework).
61+
62+
5. Severity assignment heuristic:
63+
- CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality.
64+
- HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, or untestable acceptance criterion.
65+
- MEDIUM: Terminology drift, missing non-functional task coverage, or underspecified edge case.
66+
- LOW: Style/wording improvements, or minor redundancy not affecting execution order.
67+
68+
6. Produce a Markdown report (no file writes) with sections:
69+
70+
```markdown
71+
### Specification Analysis Report
72+
73+
| ID | Category | Severity | Location(s) | Summary | Recommendation |
74+
|----|----------|----------|-------------|---------|----------------|
75+
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
76+
(Add one row per finding; generate stable IDs prefixed by category initial.)
77+
```
78+
79+
Additional subsections:
80+
- Coverage Summary Table:
81+
82+
```markdown
83+
| Requirement Key | Has Task? | Task IDs | Notes |
84+
|-----------------|-----------|----------|-------|
85+
```
86+
87+
- Constitution Alignment Issues (if any)
88+
- Unmapped Tasks (if any)
89+
- Metrics:
90+
* Total Requirements
91+
* Total Tasks
92+
* Coverage % (requirements with >=1 task)
93+
* Ambiguity Count
94+
* Duplication Count
95+
* Critical Issues Count
96+
97+
7. **Post issue comment** with analysis results organized by severity:
98+
- Post a comment to the GitHub issue with the analysis findings
99+
- Format the comment with separate tables for each severity level (only include levels that have findings):
100+
```markdown
101+
## Analysis Report
102+
103+
### Summary
104+
- Total Requirements: X
105+
- Total Tasks: Y
106+
- Coverage: Z%
107+
- Issues Found: N (A critical, B high, C medium, D low)
108+
109+
### Critical Issues
110+
| ID | Category | Location(s) | Summary | Recommendation |
111+
|----|----------|-------------|---------|----------------|
112+
| C1 | ... | ... | ... | ... |
113+
114+
### High Priority Issues
115+
| ID | Category | Location(s) | Summary | Recommendation |
116+
|----|----------|-------------|---------|----------------|
117+
| H1 | ... | ... | ... | ... |
118+
119+
### Medium Priority Issues
120+
| ID | Category | Location(s) | Summary | Recommendation |
121+
|----|----------|-------------|---------|----------------|
122+
| M1 | ... | ... | ... | ... |
123+
124+
### Low Priority Issues
125+
| ID | Category | Location(s) | Summary | Recommendation |
126+
|----|----------|-------------|---------|----------------|
127+
| L1 | ... | ... | ... | ... |
128+
129+
### Next Actions
130+
- [Recommendation based on findings]
131+
```
132+
- Keep tables concise, limit to 20 findings per severity level
133+
- If more than 20 findings in a category, add a note: "_(Additional N issues not shown - see full report)_"
134+
- Include the complete "Next Actions" block with specific recommendations
135+
136+
8. At end of report, output a concise Next Actions block:
137+
- If CRITICAL issues exist: Recommend resolving them before `/implement`.
138+
- If only LOW/MEDIUM issues: User may proceed, but provide improvement suggestions.
139+
- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", or "Manually edit tasks.md to add coverage for 'performance-metrics'".
140+
141+
8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
142+
143+
Behavior rules:
144+
- NEVER modify files.
145+
- NEVER hallucinate missing sections—if absent, report them.
146+
- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts.
147+
- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note.
148+
- If zero issues found, emit a success report with coverage statistics and proceed recommendation.
149+
150+
Context: $ARGUMENTS

‎.github/prompts/PSModule.clarify.prompt.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
3+
---
4+
5+
# Clarify
6+
7+
The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
8+
9+
User input:
10+
11+
$ARGUMENTS
12+
13+
Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
14+
15+
Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
16+
17+
Execution steps:
18+
19+
1. Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
20+
- `FEATURE_DIR`
21+
- `FEATURE_SPEC`
22+
- (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
23+
- If JSON parsing fails, abort and instruct user to re-run `/specify` or verify feature branch environment.
24+
25+
2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
26+
27+
Functional Scope & Behavior:
28+
- Core user goals & success criteria
29+
- Explicit out-of-scope declarations
30+
- User roles / personas differentiation
31+
32+
Domain & Data Model:
33+
- Entities, attributes, relationships
34+
- Identity & uniqueness rules
35+
- Lifecycle/state transitions
36+
- Data volume / scale assumptions
37+
38+
Interaction & UX Flow:
39+
- Critical user journeys / sequences
40+
- Error/empty/loading states
41+
- Accessibility or localization notes
42+
43+
Non-Functional Quality Attributes:
44+
- Performance (latency, throughput targets)
45+
- Scalability (horizontal/vertical, limits)
46+
- Reliability & availability (uptime, recovery expectations)
47+
- Observability (logging, metrics, tracing signals)
48+
- Security & privacy (authN/Z, data protection, threat assumptions)
49+
- Compliance / regulatory constraints (if any)
50+
51+
Integration & External Dependencies:
52+
- External services/APIs and failure modes
53+
- Data import/export formats
54+
- Protocol/versioning assumptions
55+
56+
Edge Cases & Failure Handling:
57+
- Negative scenarios
58+
- Rate limiting / throttling
59+
- Conflict resolution (e.g., concurrent edits)
60+
61+
Constraints & Tradeoffs:
62+
- Technical constraints (language, storage, hosting)
63+
- Explicit tradeoffs or rejected alternatives
64+
65+
Terminology & Consistency:
66+
- Canonical glossary terms
67+
- Avoided synonyms / deprecated terms
68+
69+
Completion Signals:
70+
- Acceptance criteria testability
71+
- Measurable Definition of Done style indicators
72+
73+
Misc / Placeholders:
74+
- TODO markers / unresolved decisions
75+
- Ambiguous adjectives ("robust", "intuitive") lacking quantification
76+
77+
For each category with Partial or Missing status, add a candidate question opportunity unless:
78+
- Clarification would not materially change implementation or validation strategy
79+
- Information is better deferred to planning phase (note internally)
80+
81+
3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
82+
- Maximum of 5 total questions across the entire session.
83+
- Each question must be answerable with EITHER:
84+
* A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
85+
* A one-word / short‑phrase answer (explicitly constrain: "Answer in ≤5 words").
86+
- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
87+
- Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
88+
- Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
89+
- Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
90+
- If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
91+
92+
4. Sequential questioning loop (interactive):
93+
- Present EXACTLY ONE question at a time.
94+
- For multiple‑choice questions render options as a Markdown table:
95+
96+
```markdown
97+
| Option | Description |
98+
|--------|-------------|
99+
| A | <Option A description> |
100+
| B | <Option B description> |
101+
| C | <Option C description> (add D/E as needed up to 5) |
102+
| Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
103+
```
104+
105+
- For short‑answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (≤5 words)`.
106+
- After the user answers:
107+
* Validate the answer maps to one option or fits the ≤5 word constraint.
108+
* If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
109+
* Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
110+
- Stop asking further questions when:
111+
* All critical ambiguities resolved early (remaining queued items become unnecessary), OR
112+
* User signals completion ("done", "good", "no more"), OR
113+
* You reach 5 asked questions.
114+
- Never reveal future queued questions in advance.
115+
- If no valid questions exist at start, immediately report no critical ambiguities.
116+
117+
5. Integration after EACH accepted answer (incremental update approach):
118+
- Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
119+
- For the first integrated answer in this session:
120+
* Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
121+
* Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
122+
- Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
123+
- Then immediately apply the clarification to the most appropriate section(s):
124+
* Functional ambiguity → Update or add a bullet in Functional Requirements.
125+
* User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
126+
* Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
127+
* Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
128+
* Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
129+
* Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
130+
- If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
131+
- Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
132+
- Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
133+
- Keep each inserted clarification minimal and testable (avoid narrative drift).
134+
135+
6. Validation (performed after EACH write plus final pass):
136+
- Clarifications session contains exactly one bullet per accepted answer (no duplicates).
137+
- Total asked (accepted) questions ≤ 5.
138+
- Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
139+
- No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
140+
- Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
141+
- Terminology consistency: same canonical term used across all updated sections.
142+
143+
7. Write the updated spec back to `FEATURE_SPEC`.
144+
145+
8. **Post issue comment** with clarification summary (only if questions were asked and answered):
146+
- Post a comment to the GitHub issue summarizing the clarifications
147+
- Format the comment as:
148+
```markdown
149+
## Clarification Session (YYYY-MM-DD)
150+
151+
| # | Question | Answer |
152+
|---|----------|--------|
153+
| 1 | <question text> | <answer text> |
154+
| 2 | <question text> | <answer text> |
155+
| ... | ... | ... |
156+
157+
_All clarifications have been integrated into the specification._
158+
```
159+
- Keep the table concise and readable
160+
- Include all questions asked and answers received during this session (up to 5)
161+
162+
9. Report completion (after questioning loop ends or early termination):
163+
- Number of questions asked & answered.
164+
- Path to updated spec.
165+
- Sections touched (list names).
166+
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
167+
- If any Outstanding or Deferred remain, recommend whether to proceed to `/plan` or run `/clarify` again later post-plan.
168+
- Suggested next command.
169+
170+
Behavior rules:
171+
172+
- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
173+
- If spec file missing, instruct user to run `/specify` first (do not create a new spec here).
174+
- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
175+
- Avoid speculative tech stack questions unless the absence blocks functional clarity.
176+
- Respect user early termination signals ("stop", "done", "proceed").
177+
- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
178+
- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
179+
180+
Context for prioritization: $ARGUMENTS

0 commit comments

Comments
 (0)