josiadmin/awesome-copilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

use imperative style

Browse Source
This commit is contained in:
Muhammad Ubaid Raza 2025-07-23 16:10:27 +05:00
parent babd862427
commit 947a323770
1 changed files with 187 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

339
instructions/spec-driven-workflow.instructions.md
View File

@ -1,191 +1,226 @@
--- ---
description: 'A robust, interactive approach to software development, ensuring requirements are clarified before implementation. It prioritizes safety and transparency through structured artifacts and clear protocols, with a proactive approach to edge case handling.' description: 'You must follow a robust, interactive approach to software development. Clarify all requirements before implementation to eliminate ambiguity. Prioritize safety and transparency by producing and maintaining structured artifacts and clear protocols. Proactively identify and handle edge cases rather than waiting for them to emerge.'
applyTo: '**' applyTo: '**'
--- ---
# Spec Driven Workflow v4 # Spec Driven Workflow v5
Structured, transparent software development process ensuring clarity before action, prioritizing safety and edge case handling. You must follow a robust, interactive approach to software development. Clarify all requirements before implementation to eliminate ambiguity. Prioritize safety and transparency by producing and maintaining structured artifacts and clear protocols. Proactively identify and handle edge cases rather than waiting for them to emerge.
---
## Core Principles ## Core Principles
1. **Ambiguity Resolution**: Stop and clarify any unclear, inconsistent, or incomplete request before proceeding. No assumptions allowed. 1. **Resolve Ambiguity**: Stop and clarify any unclear, inconsistent, or incomplete request. Make no assumptions.
2. **Persistent Execution**: Own task from start to finish, producing all artifacts and handling edge cases unless explicitly paused or transferred. 2. **Execute Persistently**: Own tasks from start to finish. Produce all artifacts and handle edge cases unless explicitly paused or transferred.
3. **Concise Communication**: Use minimal, clear language in responses and artifacts unless elaboration requested. 3. **Communicate Concisely**: Use minimal, clear language in responses and artifacts unless elaboration is requested.
4. **Support Steering**: Accept structured steering instructions. Adjust scope, behavior, or execution path dynamically.
5. **Maintain Artifacts**: Keep clear, verifiable artifacts updated throughout all phases.
6. **Track Global Decisions**: When any user prompt, answer, or decision represents a pattern or global behavior change, update or add a steering document in `steering/*.md`. Keep one-off or task-specific decisions in `activity_log.md` only.
---
## Artifacts ## Artifacts
Ensure transparency and auditability with minimal, clear documentation.
### Required Artifacts ### Required Artifacts
- `requirements.md`: User stories, acceptance criteria, edge case matrix (EARS notation)
- `design.md`: Architecture, sequence diagrams, edge case mitigations - `requirements.md`: Capture user stories and acceptance criteria in structured EARS notation.
- `tasks.md`: Implementation plan with edge case tasks - `design.md`: Document technical architecture, sequence diagrams, and implementation considerations.
- `decision_records.md`: Decision log with context, options, rationale - `tasks.md`: Provide detailed implementation plans with discrete, trackable tasks.
- `action_log.md`: Activity log with actions, outcomes, logs, test results - `activity_log.md`: Log decisions and actions with context, options, rationale, and execution outcomes.
- `diagrams/`: Directory for visual documentation (e.g., sequence, data flow) - `steering/*.md`: Store steering documents. Use multiple steering files to separate focused instructions.
### File Structure ### File Structure
``` ```
/spec/ /spec/
├── steering/*.md
├── requirements.md ├── requirements.md
├── design.md ├── design.md
├── tasks.md ├── tasks.md
├── decision_records.md └── activity_log.md
├── action_log.md
└── diagrams/
``` ```
### Maintenance ### Maintain Files
- Update artifacts for new, updated, or obsolete tasks. - Update artifacts for new, updated, or obsolete tasks.
- Modify documentation only if instructed. - Update steering docs when decisions or user prompts indicate reusable patterns or global policies.
- Use concise language unless elaboration requested. - Use concise language unless elaboration is requested.
## Examples ---
### requirements.md
**Functional Requirements**
- req-001: WHEN user issues code generation command, AGENT SHALL validate and generate code. Priority: High, Status: Active
- req-002: IF command has unsupported syntax, AGENT SHALL return error with hints. Priority: High, Status: Active
- req-003: WHILE memory enabled, AGENT SHALL persist command context. Priority: Medium, Status: Active
**Edge Case Matrix**
| ID | Description | Likelihood | Impact | Risk Score | Mitigation |
| -------- | ------------------------------------ | ---------- | ------ | ---------- | --------------------------------------- |
| edge-001 | Unsupported syntax/prompt | Frequent | High | 85 | Parse/validate; return actionable error |
| edge-002 | Memory context mismatch | Occasional | High | 75 | Validate memory; prompt user if unclear |
| edge-003 | Ambiguous instruction interpretation | Occasional | Medium | 60 | Ask clarifying question |
### design.md
**Function**: `submitForm(formData)`
**Inputs**: `formData: { key: string, value: any }`
**Outputs**: `{ status: "success" | "error", message: string }`
**Logic Flow**
1. Validate formData format
2. Save to IndexedDB or queue if offline
3. Return success/error
**Dependencies**
- IndexedDB API
- FormData model
**Edge Cases**
- edge-001: Empty fields (Risk: 70)
- Mitigation: Check empty fields; return error
- Test: Empty/partial submissions
- edge-002: Offline submission (Risk: 80)
- Mitigation: Queue in IndexedDB; sync on reconnect
- Test: Simulate offline mode
**Error Handling**
- Return specific error messages
- Log with timestamps
### tasks.md
**task-001**: Implement submitForm
- Depends: FormData model
- Status: To Do
- Outcome: Validates/saves form data or queues offline
- Edge Cases: Empty fields, offline scenarios
- Priority: High
**task-002**: Add form validation UI feedback
- Depends: FormHandler
- Status: To Do
- Outcome: Show error messages for invalid inputs
- Edge Cases: Real-time validation for malformed inputs
- Priority: Medium
### decision_records.md
**Decision 001**
- Date: 2025-07-21T15:00:00Z
- Decision: Use IndexedDB for offline form storage
- Context: Store form submissions offline
- Options:
1. IndexedDB: Pros - Efficient; Cons - Browser compatibility
2. LocalStorage: Pros - Simple; Cons - Limited capacity
- Rationale: IndexedDB supports larger datasets
- Impact: Needs compatibility checks for older browsers
- Review: 2026-01-21
- Status: Approved
### action_log.md
**Activity 001**
- Action: Implemented submitForm
- Date: 2025-07-21T14:00:00Z
- Outcome: Validates/saves form data
- Logs: [Console output]
- Tests: [Unit tests]
- Linting: ESLint, fixed 2 warnings (trailing commas, unused variables)
- Type Checking: TypeScript, fixed 1 formData type mismatch
- Issues: None
- Edge Cases: Handled empty fields, offline queuing
- Next Steps: Test malformed inputs, verify offline sync
## Execution Workflow (6 Phases) ## Execution Workflow (6 Phases)
1. **ANALYZE** 1. **ANALYZE**
- Read code, docs, tests, logs; summarize findings - Read code, docs, tests, and logs. Summarize findings.
- Define requirements in EARS notation - Define requirements using EARS notation.
- Identify dependencies, constraints, data flows - Identify dependencies, constraints, and data flows.
- Catalog edge cases in matrix: [Description], [Likelihood], [Impact], [Risk Score], [Mitigation] - Catalog edge cases in a matrix with description, likelihood, impact, risk score, and mitigation.
- Assess Confidence Score (0-100%) - Assess confidence score (0–100%).
- Halt if ambiguous; request clarification - Halt if ambiguous. Request clarification.
2. **DESIGN** 2. **DESIGN**
- High Confidence (>85%): Plan with edge case mitigations - Use high confidence (>85%) to plan with edge case mitigations.
- Medium Confidence (66–85%): Build PoC/MVP - Use medium confidence (66–85%) to build PoC/MVP.
- Low Confidence (<66%): Research, simulate edge cases - Use low confidence (<66%) to research and simulate edge cases.
- Document in `design.md`: architecture, interfaces, mitigations - Document architecture, interfaces, and mitigations in `design.md`.
- Define unit tests for edge cases - Define unit tests for edge cases.
- Plan tasks in `tasks.md` - Plan tasks in `tasks.md`.
- Apply available steering instructions.
3. **IMPLEMENT** 3. **IMPLEMENT**
- Code in small, testable increments - Code in small, testable increments.
- Build from dependencies upward - Build from dependencies upward.
- Follow conventions; log deviations in `decision_records.md` - Follow conventions and log deviations in `activity_log.md`.
- Add comments for intent - Add intent comments.
- Update `tasks.md` with status, edge case outcomes - Update `tasks.md` with status and edge case outcomes.
4. **VALIDATE** 4. **VALIDATE**
- Run tests; log results including edge cases - Run tests and log results, including edge cases.
- Perform linting; log in `action_log.md` - Perform linting and type checking; log results.
- Perform type checking; log in `action_log.md` - Verify performance and log traces.
- Verify performance; log traces - Resolve all issues before proceeding.
- Resolve all issues before proceeding
5. **REFLECT** 5. **REFLECT**
- Refactor for maintainability; document changes - Refactor for maintainability and document changes.
- Update artifacts, including edge case docs - Update artifacts, including edge case documentation.
- Identify improvements, technical debt, missed edge cases - Update task status in `tasks.md`.
- Validate success criteria, edge case outcomes - Log reflections in `activity_log.md`.
- Identify improvements, technical debt, and missed edge cases.
- Validate success criteria and edge case outcomes.
6. **HANDOFF** 6. **HANDOFF**
- Generate Executive Summary: Task outcomes, decisions, edge case mitigations, validation results - Generate executive summary: task outcomes, decisions, edge case mitigations, and validation results.
- Prepare Pull Request: Summary, changelog, validation/artifact links - Prepare pull request: summary, changelog, and validation/artifact links.
- Archive intermediate files to `.agent_work/` - Archive intermediate files to `/spec/agent_work/`.
- Document completion in `action_log.md` - Document completion in `activity_log.md`.
---
## Interruption/Resume ## Interruption/Resume
- Reassess system impact
- Update artifacts (`design.md`, `tasks.md`, etc.) - Reassess system impact.
- Log event in `decision_records.md` - Update artifacts (`design.md`, `tasks.md`, `activity_log.md`).
- Log event in `activity_log.md`.
## Troubleshooting ## Troubleshooting
- Re-analyze requirements, edge cases
- Update design, tasks for new mitigations - Reanalyze requirements and edge cases.
- Retry with updated logic - Update design and tasks for new mitigations.
- Escalate persistent issues; log in `decision_records.md` - Retry with updated logic.
- Escalate persistent issues and log them.
## Technical Debt ## Technical Debt
- Log in `decision_records.md`: [Title], [Priority], [Location], [Reason], [Impact], [Remediation], [Effort]
- Prioritize by risk and effort - Log technical debt in `activity_log.md` with title, priority, location, reason, impact, remediation, and effort.
- Prioritize by risk and effort.
## Quality Assurance ## Quality Assurance
**Monitoring**
- Static Analysis: Check architecture, vulnerabilities - Perform static analysis: check architecture and vulnerabilities.
- Dynamic Analysis: Monitor runtime, performance - Perform dynamic analysis: monitor runtime and performance.
- Documentation: Verify completeness, accuracy - Verify documentation for completeness and accuracy.
- Edge Case Coverage: Track mitigations in matrix - Track edge case mitigations in matrix.
- Edge Case Risk Reduction: Measure post-mitigation - Measure edge case risk reduction after mitigation.
- Validate steering instructions in `steering/*.md` and log their outcomes.
- Ensure global decisions propagate to `steering/*.md` and not only to `activity_log.md`.
## Few-Shot Examples for Artifacts
### requirements.md
```md
**Functional Requirements**
- req-001: WHEN user submits web form for code generation, AGENT SHALL validate input and generate code (HTML/JS/CSS). Priority: High, Status: Active
- req-002: IF input has invalid syntax, AGENT SHALL return error with specific hints. Priority: High, Status: Active
- req-003: WHILE session storage is active, AGENT SHALL persist command context in browser. Priority: Medium, Status: Active
**Edge Case Matrix**
| ID | Description | Likelihood | Impact | Risk Score | Mitigation |
| -------- | ------------------------------------------- | ---------- | ------ | ---------- | ------------------------------------------- |
| edge-001 | Invalid syntax in form (e.g., bad JSON/CSS) | Frequent | High | 85 | Validate input; return clear error messages |
| edge-002 | Session storage mismatch (e.g., expired) | Occasional | High | 75 | Verify storage; prompt re-authentication |
| edge-003 | Vague form input (e.g., "make webpage") | Occasional | Medium | 60 | Prompt for specific details in UI |
```
### design.md
```md
**Function**: `submitForm(formData)`\ **Inputs**: `formData: { key: string, value: any }`\ **Outputs**: `{ status: "success" | "error", message: string }`
**Logic Flow**
1. Validate formData format
2. Save to IndexedDB or queue if offline
3. Return success/error
**Dependencies**
- IndexedDB API
- FormData model
**Edge Cases**
- edge-001: Empty fields (Risk: 70)
- Mitigation: Check empty fields; return error
- Test: Empty/partial submissions
- edge-002: Offline submission (Risk: 80)
- Mitigation: Queue in IndexedDB; sync on reconnect
- Test: Simulate offline mode
**Error Handling**
- Return specific error messages
- Log with timestamps
```
### tasks.md
```md
**task-001**: Implement submitForm
- Depends: FormData model
- Status: To Do
- Outcome: Validates/saves form data or queues offline
- Edge Cases: Empty fields, offline scenarios
- Priority: High
**task-002**: Add form validation UI feedback
- Depends: FormHandler
- Status: To Do
- Outcome: Show error messages for invalid inputs
- Edge Cases: Real-time validation for malformed inputs
- Priority: Medium
```
### activity\_log.md
```md
**Decision**
- Date: 2025-07-23
- Title: Use IndexedDB for offline storage
- Context: Persistent client-side data
- Options: IndexedDB, LocalStorage
- Rationale: IndexedDB handles larger data sets
- Status: Approved
**Action**
- Date: 2025-07-23T14:00:00Z
- Action: Implement submitForm
- Outcome: Validates and saves form data
- Edge Cases: Empty fields, offline queuing
- Logs: 3 unit tests passed
- Issues: None
- Next Steps: Offline sync testing
```
### steering/performance.tuning.md
```md
**Steering: Performance Tuning**\ Date: 2025-07-23T14:00:00Z\ Context: Expected large-scale input\ Scope: Algorithm choice, data structure design\ Impact: Use streaming pipelines instead of batch processing\ Status: Applied
```