Skip to content

Commit 55f0460

Browse files
ryderstormryderstorm
committed
docs(prompts): add spec-driven prompts for spec, tasks, and task mgmt
- Add prompts/generate-spec.md to guide writing implementation-ready specs - Add prompts/generate-task-list-from-spec.md to derive structured tasks - Add prompts/manage-tasks.md to manage task execution and commits Establishes a repeatable workflow for planning, execution, and documentation.
1 parent fddfff7 commit 55f0460

File tree

3 files changed

+219
-0
lines changed

3 files changed

+219
-0
lines changed

‎prompts/generate-spec.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
description: generate a Specification (Spec) for a feature
3+
---
4+
5+
# Generating a Feature Specification (Spec)
6+
7+
## Goal
8+
9+
To guide an AI assistant in creating a detailed Specification (Spec) in Markdown format, based on an initial user prompt. The Spec should be clear, actionable, and suitable for a junior developer to understand and implement the feature.
10+
11+
## Process
12+
13+
1. **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality.
14+
2. **Ask Clarifying Questions:** Before writing the Spec, the AI *must* ask clarifying questions to gather sufficient detail. The goal is to understand the "what" and "why" of the feature, not necessarily the "how" (which the developer will figure out). Make sure to provide options in letter/number lists so I can respond easily with my selections.
15+
3. **Generate Spec:** Based on the initial prompt and the user's answers to the clarifying questions, generate a Spec using the structure outlined below.
16+
4. **Save Spec:** Save the generated document as `[n]-spec-[feature-name].md` inside the `/tasks` directory. (Where `n` is a zero-padded 4-digit sequence starting from 0001, e.g., `0001-spec-user-authentication.md`.)
17+
18+
## Clarifying Questions (Examples)
19+
20+
The AI should adapt its questions based on the prompt, but here are some common areas to explore:
21+
22+
* **Problem/Goal:** "What problem does this feature solve for the user?" or "What is the main goal we want to achieve with this feature?"
23+
* **Target User:** "Who is the primary user of this feature?"
24+
* **Core Functionality:** "Can you describe the key actions a user should be able to perform with this feature?"
25+
* **User Stories:** "Could you provide a few user stories? (e.g., As a [type of user], I want to [perform an action] so that [benefit].)"
26+
* **Acceptance Criteria:** "How will we know when this feature is successfully implemented? What are the key success criteria?"
27+
* **Scope/Boundaries:** "Are there any specific things this feature *should not* do (non-goals)?"
28+
* **Data Requirements:** "What kind of data does this feature need to display or manipulate?"
29+
* **Design/UI:** "Are there any existing design mockups or UI guidelines to follow?" or "Can you describe the desired look and feel?"
30+
* **Edge Cases:** "Are there any potential edge cases or error conditions we should consider?"
31+
* **Unit of Work:** "What is the smallest end-to-end slice we can ship that a user or stakeholder can experience, test, or demonstrate?"
32+
* **Demoability:** "For each stage, how will we show working value (e.g., URL, CLI output, screenshot, test run, short demo script)?"
33+
34+
## Spec Structure
35+
36+
The generated Spec should include the following sections:
37+
38+
1. **Introduction/Overview:** Briefly describe the feature and the problem it solves. State the goal.
39+
2. **Goals:** List the specific, measurable objectives for this feature.
40+
3. **User Stories:** Detail the user narratives describing feature usage and benefits.
41+
4. **Demoable Units of Work:** Define small, end-to-end vertical slices. For each slice capture: Purpose and users; Demo Criteria (what will be shown to verify value); Proof Artifact(s) (tangible evidence such as a URL, CLI command & expected output, test names, or screenshot).
42+
5. **Functional Requirements:** List the specific functionalities the feature must have. Use clear, concise language (e.g., "The system must allow users to upload a profile picture."). Number these requirements.
43+
6. **Non-Goals (Out of Scope):** Clearly state what this feature will *not* include to manage scope.
44+
7. **Design Considerations (Optional):** Link to mockups, describe UI/UX requirements, or mention relevant components/styles if applicable.
45+
8. **Technical Considerations (Optional):** Mention any known technical constraints, dependencies, or suggestions (e.g., "Should integrate with the existing Auth module").
46+
9. **Success Metrics:** How will the success of this feature be measured? (e.g., "Increase user engagement by 10%", "Reduce support tickets related to X").
47+
10. **Open Questions:** List any remaining questions or areas needing further clarification.
48+
49+
## Target Audience
50+
51+
Assume the primary reader of the Spec is a **junior developer**. Therefore, requirements should be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the feature's purpose and core logic.
52+
53+
## Output
54+
55+
* **Format:** Markdown (`.md`)
56+
* **Location:** `/tasks/`
57+
* **Filename:** `[n]-spec-[feature-name].md`
58+
59+
## Final instructions
60+
61+
1. Do NOT start implementing the Spec
62+
2. Make sure to ask the user clarifying questions
63+
3. Take the user's answers to the clarifying questions and improve the Spec
64+
4. Save the completed Spec to `/tasks/[n]-spec-[feature-name].md`
65+
5. Ask the user if they are satisfied with it and if they have any additional questions or clarifications
66+
6. Once the user is satisfied with the Spec, this workflow is complete and you should stop working

‎prompts/generate-task-list-from-spec.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
description: generate a task list from a Spec
3+
---
4+
5+
# Generating a Task List from a Spec
6+
7+
## Goal
8+
9+
To guide an AI assistant in creating a detailed, step-by-step task list in Markdown format based on an existing Specification (Spec). The task list should guide a developer through implementation.
10+
11+
## Output
12+
13+
- **Format:** Markdown (`.md`)
14+
- **Location:** `/tasks/`
15+
- **Filename:** `tasks-[spec-file-name].md` (e.g., if the Spec is `0001-spec-user-profile-editing.md`, save as `tasks-0001-spec-user-profile-editing.md`)
16+
17+
## Process
18+
19+
1. **Receive Spec Reference:** The user points the AI to a specific Spec file
20+
2. **Analyze Spec:** The AI reads and analyzes the functional requirements, user stories, and other sections of the specified Spec.
21+
3. **Define Demoable Units of Work:** Identify thin, end-to-end vertical slices from the Spec. Each parent task must correspond to a demoable unit of work.
22+
4. **Assess Current State:** Review the existing codebase to understand existing infrastructre, architectural patterns and conventions. Also, identify any existing components or features that already exist and could be relevant to the Spec requirements. Then, identify existing related files, components, and utilities that can be leveraged or need modification.
23+
5. **Phase 1: Generate Parent Tasks:** Based on the Spec analysis and current state assessment, create the file and generate the main, high-level tasks required to implement the feature. Use your judgement on how many high-level tasks to use. It's likely to be about five tasks.
24+
6. **Inform the user:** Present these tasks to the user in the specified format (without sub-tasks yet) For example, say "I have generated the high-level tasks based on the Spec. Ready to generate the sub-tasks? Respond with 'Generate sub tasks' to proceed." .
25+
7. **Wait for Confirmation:** Pause and wait for the user to respond with "Generate sub tasks".
26+
8. **Phase 2: Generate Sub-Tasks:** Once the user confirms, break down each parent task into smaller, actionable sub-tasks necessary to complete the parent task. Ensure sub-tasks logically follow from the parent task, cover the implementation details implied by the Spec, and consider existing codebase patterns where relevant without being constrained by them.
27+
9. **Identify Relevant Files:** Based on the tasks and Spec, identify potential files that will need to be created or modified. List these under the `Relevant Files` section, including corresponding test files if applicable.
28+
10. **Generate Final Output:** Combine the parent tasks, sub-tasks, relevant files, and notes into the final Markdown structure.
29+
11. **Save Task List:** Save the generated document in the `/tasks/` directory with the filename `tasks-[spec-file-name].md`, where `[spec-file-name]` matches the base name of the input Spec file (e.g., if the input was `0001-spec-user-profile-editing.md`, the output is `tasks-0001-spec-user-profile-editing.md`).
30+
31+
## Output Format
32+
33+
Every parent task must include **Demo Criteria** and **Proof Artifact(s)**. These are mandatory.
34+
35+
The generated task list _must_ follow this example structure:
36+
37+
```markdown
38+
## Relevant Files
39+
40+
- `path/to/potential/file1.ts` - Brief description of why this file is relevant (e.g., Contains the main component for this feature).
41+
- `path/to/file1.test.ts` - Unit tests for `file1.ts`.
42+
- `path/to/another/file.tsx` - Brief description (e.g., API route handler for data submission).
43+
- `path/to/another/file.test.tsx` - Unit tests for `another/file.tsx`.
44+
- `lib/utils/helpers.ts` - Brief description (e.g., Utility functions needed for calculations).
45+
- `lib/utils/helpers.test.ts` - Unit tests for `helpers.ts`.
46+
47+
### Notes
48+
49+
- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory).
50+
- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration.
51+
52+
## Tasks
53+
54+
- [ ] 1.0 Parent Task Title
55+
- Demo Criteria: "Open /path and complete X end-to-end; acceptance: Y visible/returned"
56+
- Proof Artifact(s): "URL: https://..., CLI: command & expected output, Test: MyFeature.test.ts"
57+
- [ ] 1.1 [Sub-task description 1.1]
58+
- [ ] 1.2 [Sub-task description 1.2]
59+
- [ ] 2.0 Parent Task Title
60+
- Demo Criteria: "User can perform Z with persisted state"
61+
- Proof Artifact(s): "Screenshot of flow; link to test suite section"
62+
- [ ] 2.1 [Sub-task description 2.1]
63+
- [ ] 3.0 Parent Task Title (may not require sub-tasks if purely structural or configuration)
64+
- Demo Criteria: "Configuration is verifiable via command/output"
65+
- Proof Artifact(s): "CLI: config get … -> expected value; log line; diff link"
66+
```
67+
68+
## Interaction Model
69+
70+
The process explicitly requires a pause after generating parent tasks to get user confirmation ("Go") before proceeding to generate the detailed sub-tasks. This ensures the high-level plan aligns with user expectations before diving into details.
71+
72+
## Target Audience
73+
74+
Assume the primary reader of the task list is a **junior developer** who will implement the feature with awareness of the existing codebase context.
75+
76+
## After Subtask Generation
77+
78+
- Prompt the user to review the generated task list and provide feedback.
79+
- Wait for instructions on next steps.
80+
- DO NOT begin implementation; that will be handled through other means.
81+
- Prioritize execution so each completed parent task yields a demoable increment with Demo Criteria and Proof Artifact(s) verified.

‎prompts/manage-tasks.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
description: Guidelines for managing task lists and working on tasks/subtasks
3+
allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch
4+
---
5+
6+
# Task List Management
7+
8+
Guidelines for managing task lists in markdown files to track progress on completing a Spec
9+
10+
## Task Implementation
11+
12+
- Tasks can be in one of three states:
13+
- `[ ]` - Not started
14+
- `[x]` - Completed
15+
- `[~]` - In progress
16+
- **One sub-task at a time:** Do **NOT** start the next sub‑task until all previous sub‑tasks are completed.
17+
- **Mark in-progress:** When you start a sub‑task, immediately mark it as in-progress by changing `[ ]` to `[~]`. Update the parent task to `[~]` if it is not already `[~]`.
18+
- **Parent Task and Subtask Relationship:**
19+
- A parent task can have multiple subtasks
20+
- A subtask can only have one parent task
21+
- The status of the parent task must always be inline with the status of its subtasks
22+
- **Completion protocol:**
23+
1. When you finish a **sub‑task**, immediately mark it as completed by changing `[~]` to `[x]`.
24+
2. If **all** subtasks underneath a parent task are now `[x]`, follow this sequence:
25+
- **First**: Run the full test suite (`pytest`, `npm test`, `bin/rails test`, etc.)
26+
- **Only if all tests pass**: Stage changes (`git add .`)
27+
- **Validate changes**: Run any additional validation steps as specified in the Spec. Also check that the demo criteria and demo artifacts are met.
28+
- **Clean up**: Remove any temporary files and temporary code before committing
29+
- **Commit**: Use a descriptive commit message that:
30+
- Uses conventional commit format (`feat:`, `fix:`, `refactor:`, etc.)
31+
- Summarizes what was accomplished in the parent task
32+
- Lists key changes and additions
33+
- References the task number and Spec context
34+
- **Formats the message as a single-line command using `-m` flags**, for example:
35+
36+
```bash
37+
git commit -m "feat: add payment validation logic" -m "- Validates card type and expiry" -m "- Adds unit tests for edge cases" -m "Related to T123 in Spec"
38+
```
39+
40+
3. Once all the subtasks are marked completed and changes have been committed, mark the **parent task** as completed.
41+
4. After marking a parent task as completed, proceed to the next open task.
42+
5. If there are no open tasks available in the list, prompt the user for how to proceed.
43+
44+
## Task List Maintenance
45+
46+
1. **Update the task list as you work:**
47+
- Mark tasks and subtasks as completed (`[x]`) per the protocol above.
48+
- Add new tasks as they emerge.
49+
50+
2. **Maintain the "Relevant Files" section:**
51+
- List every file created or modified.
52+
- Give each file a one‑line description of its purpose.
53+
54+
## Guidelines
55+
56+
When working with task lists, the AI must:
57+
58+
1. Regularly update the task list file after finishing any significant work.
59+
2. Follow the completion protocol outlined above.
60+
3. Add newly discovered tasks.
61+
4. Keep "Relevant Files" accurate and up to date.
62+
5. Before starting work, check which sub‑task is next.
63+
6. After implementing a sub‑task, update the file and then pause for user approval.
64+
65+
## Instructions
66+
67+
1. Find the most recent task list file in the `/tasks/` directory.
68+
2. Follow the guidelines above to manage the task list.
69+
3. Analyze the task list to determine what to do next:
70+
- If there is a task that is marked as in-progress, stop processing these instructions and continue working on that task.
71+
- If there are any open tasks in the list, stop processing these instructions and continue working on the next open task.
72+
- If there are no open tasks available in the list, prompt the user for how to proceed.

0 commit comments

Comments
 (0)