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

feat: 🎨 add steerring docs, workflow for simple tasks

Browse Source
This commit is contained in:
Muhammad Ubaid Raza 2025-07-23 20:07:44 +05:00
parent 947a323770
commit 41ffea5f54
1 changed files with 162 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -5,7 +5,7 @@ applyTo: '**'
# Spec Driven Workflow v5 # Spec Driven Workflow v5
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. You must follow a robust, systematic 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.
--- ---
@ -24,24 +24,37 @@ You must follow a robust, interactive approach to software development. Clarify
### Required Artifacts ### Required Artifacts
activity_log.md: Task summaries, deviations, reflections, completion, escalation logs.
design.md: Architecture, interfaces, mitigations.
tasks.md: Task plans, status, edge case outcomes.
edge_cases.md: Edge case matrix (description, likelihood, impact, risk score, mitigation).
requirements.md: User stories, acceptance criteria in EARS notation.
/spec/agent_work/: Archive for intermediate files.
steering/*.md: Steering instructions for design.
- `activity_log.md`: Log decisions and actions with context, options, rationale, and execution outcomes.
- `requirements.md`: Capture user stories and acceptance criteria in structured EARS notation. - `requirements.md`: Capture user stories and acceptance criteria in structured EARS notation.
- `edge_cases.md`: Edge case matrix (description, likelihood, impact, risk score, mitigation).
- `design.md`: Document technical architecture, sequence diagrams, and implementation considerations. - `design.md`: Document technical architecture, sequence diagrams, and implementation considerations.
- `tasks.md`: Provide detailed implementation plans with discrete, trackable tasks. - `tasks.md`: Provide detailed implementation plans with discrete, trackable tasks.
- `activity_log.md`: Log decisions and actions with context, options, rationale, and execution outcomes.
- `steering/*.md`: Store steering documents. Use multiple steering files to separate focused instructions. - `steering/*.md`: Store steering documents. Use multiple steering files to separate focused instructions.
- `/spec/agent_work/`: Archive for intermediate files.
### File Structure ### File Structure
``` ```md
/spec/ /spec/
├── steering/*.md ├── steering/
├── requirements.md │ └── *.md # Steering instructions for reusable patterns and policies
├── design.md ├── agent_work/ # Archive for intermediate files
├── tasks.md ├── requirements.md # User stories and acceptance criteria in EARS notation
└── activity_log.md ├── design.md # Technical architecture, interfaces, and mitigations
├── tasks.md # Implementation plans with trackable tasks and status
├── edge_cases.md # Edge case matrix (description, likelihood, impact, risk score, mitigation)
└── activity_log.md # Decisions, actions, reflections, escalations, and completion logs
``` ```
### Maintain Files ### Maintenance Guidelines
- Update artifacts for new, updated, or obsolete tasks. - Update artifacts for new, updated, or obsolete tasks.
- Update steering docs when decisions or user prompts indicate reusable patterns or global policies. - Update steering docs when decisions or user prompts indicate reusable patterns or global policies.
@ -49,81 +62,138 @@ You must follow a robust, interactive approach to software development. Clarify
--- ---
## Execution Workflow (6 Phases) ## Workflows
### Main Workflow
Structured process for complex, high-risk tasks requiring thorough analysis and validation.
#### Criteria
Use when **any** of the following are met:
- **Scope**: Spans multiple components, modules, or files, or involves external dependencies.
- **Impact**: Affects critical functionality (e.g., core logic, data integrity, user-facing features).
- **Risk Score**: ≥30 (likelihood × impact, per edge case matrix).
- **Edge Cases**: Multiple or complex edge cases (e.g., new error states, system interactions).
- **Ambiguity**: Requirements unclear or need clarification.
#### Steps
1. **ANALYZE** 1. **ANALYZE**
- Read code, docs, tests, and logs. Summarize findings. - Read: code, docs, tests, logs.
- Define requirements using EARS notation. - Summarize: findings in `activity_log.md`.
- Identify dependencies, constraints, and data flows. - Define: requirements in EARS notation in `requirements.md`.
- Catalog edge cases in a matrix with description, likelihood, impact, risk score, and mitigation. - Identify: dependencies, constraints, data flows.
- Assess confidence score (0–100%). - Catalog: edge cases in matrix (`edge_cases.md`):
- Halt if ambiguous. Request clarification. - Fields: description, likelihood (1–5), impact (1–5), risk score (likelihood × impact), mitigation.
- Assess: confidence score (0–100%).
- Action: halt and request clarification if ambiguous.
2. **DESIGN** 2. **DESIGN**
- Use high confidence (>85%) to plan with edge case mitigations. - High confidence (>85%): plan with edge case mitigations.
- Use medium confidence (66–85%) to build PoC/MVP. - Medium confidence (66–85%): build PoC/MVP.
- Use low confidence (<66%) to research and simulate edge cases. - Low confidence (<66%): research and simulate edge cases.
- Document architecture, interfaces, and mitigations in `design.md`. - Document: architecture, interfaces, 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. - Apply: steering instructions from `steering/*.md`.
3. **IMPLEMENT** 3. **IMPLEMENT**
- Code in small, testable increments. - Code: in small, testable increments.
- Build from dependencies upward. - Build: from dependencies upward.
- Follow conventions and log deviations in `activity_log.md`. - Follow: conventions, log deviations in `activity_log.md`.
- Add intent comments. - Add: intent comments in code.
- Update `tasks.md` with status and edge case outcomes. - Update: `tasks.md` with status and edge case outcomes.
4. **VALIDATE** 4. **VALIDATE**
- Run tests and log results, including edge cases. - Run: tests, log results in `activity_log.md` (include edge cases).
- Perform linting and type checking; log results. - Perform: linting, type checking; log results.
- 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 and document changes. - Refactor: for maintainability, document changes.
- Update artifacts, including edge case documentation. - Update: artifacts, including `edge_cases.md`.
- Update task status in `tasks.md`. - Update: `tasks.md` with task status.
- Log reflections in `activity_log.md`. - Log: reflections in `activity_log.md`.
- Identify improvements, technical debt, and missed edge cases. - Identify: improvements, technical debt, missed edge cases.
- Validate success criteria and edge case outcomes. - Validate: success criteria and edge case outcomes.
6. **HANDOFF** 6. **HANDOFF**
- Generate executive summary: task outcomes, decisions, edge case mitigations, and validation results. - Generate: executive summary (task outcomes, decisions, mitigations, validation results).
- Prepare pull request: summary, changelog, and validation/artifact links. - Prepare: pull request (summary, changelog, validation/artifact links).
- Archive intermediate files to `/spec/agent_work/`. - Archive: intermediate files to `/spec/agent_work/`.
- Document completion in `activity_log.md`. - Log: completion in `activity_log.md`.
--- ### Lightweight Workflow
## Interruption/Resume Streamlined process for small, low-risk tasks with minimal overhead.
- Reassess system impact. #### Criteria
- Update artifacts (`design.md`, `tasks.md`, `activity_log.md`).
- Log event in `activity_log.md`.
## Troubleshooting Use when **all** criteria are met:
- Reanalyze requirements and edge cases. - **Scope**: Single component/module/file, no external dependencies.
- Update design and tasks for new mitigations. - **Impact**: Low, affects non-critical functionality (e.g., UI tweaks, typo fixes).
- Retry with updated logic. - **Risk Score**: <30 (likelihood × impact, per edge case matrix).
- Escalate persistent issues and log them. - **Edge Cases**: Minimal or none (no new error states or system interactions).
## Technical Debt #### Steps
- Log technical debt in `activity_log.md` with title, priority, location, reason, impact, remediation, and effort. 1. **ANALYZE**
- Prioritize by risk and effort. - Confirm: task meets lightweight criteria.
- Log: task and criteria assessment in `activity_log.md`.
- Identify: edge cases (if any), document in `edge_cases.md` or as a section in `activity_log.md` if minimal.
- Action: escalate to Main Workflow if ambiguities or risks emerge.
2. **IMPLEMENT**
- Code: in small, testable increments.
- Follow: conventions, log deviations in `activity_log.md`.
- Add: intent comments in code.
3. **VALIDATE**
- Run: relevant tests (unit, integration), log results in `activity_log.md`.
- Perform: linting, type checking; log results.
- Resolve: all issues before proceeding.
4. **REFLECT**
- Document: changes and outcomes in `activity_log.md`.
- Identify: technical debt, missed edge cases (log with priority, impact, remediation in `activity_log.md`).
- Confirm: task completion against success criteria.
5. **HANDOFF**
- Log: completion in `activity_log.md` (summary, validation results, edge case outcomes).
- Prepare: pull request (summary, link to `activity_log.md`).
- Archive: intermediate notes to `/spec/agent_work/`.
### Interruption/Resume
- Check: task status in `tasks.md` and validate artifact consistency (`requirements.md`, `design.md`, `edge_cases.md`).
- Reassess: system impact and update artifacts (`design.md`, `tasks.md`, `activity_log.md`).
- Log: interruption/resume event in `activity_log.md` with context and next steps.
### Troubleshooting
- Reanalyze: requirements and edge cases in `requirements.md` and `edge_cases.md`.
- Update: `design.md` and `tasks.md` for new mitigations.
- Retry: with updated logic.
- Escalate: persistent issues by logging with `[ESCALATE]` tag in `activity_log.md` and notifying human operator.
### Technical Debt
- Log: in `activity_log.md` with title, priority, location, reason, impact, remediation, and effort.
- Prioritize: by risk and effort.
## Quality Assurance ## Quality Assurance
- Perform static analysis: check architecture and vulnerabilities. - Perform: static analysis (architecture, vulnerabilities).
- Perform dynamic analysis: monitor runtime and performance. - Perform: dynamic analysis (runtime, performance).
- Verify documentation for completeness and accuracy. - Verify: documentation completeness and accuracy.
- Track edge case mitigations in matrix. - Track: edge case mitigations in `edge_cases.md`.
- Measure edge case risk reduction after mitigation. - Measure: edge case risk reduction post-mitigation.
- Validate steering instructions in `steering/*.md` and log their outcomes. - Validate: steering instructions in `steering/*.md` and log outcomes in `activity_log.md`.
- Ensure global decisions propagate to `steering/*.md` and not only to `activity_log.md`. - Ensure: global decisions propagate to `steering/*.md`.
## Few-Shot Examples for Artifacts ## Few-Shot Examples for Artifacts
@ -136,64 +206,52 @@ You must follow a robust, interactive approach to software development. Clarify
- req-002: IF input has invalid syntax, AGENT SHALL return error with specific hints. 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 - req-003: WHILE session storage is active, AGENT SHALL persist command context in browser. Priority: Medium, Status: Active
### edge_cases.md
```md
**Edge Case Matrix** **Edge Case Matrix**
| ID | Description | Likelihood | Impact | Risk Score | Mitigation | | 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-001 | Invalid syntax in form (e.g., bad JSON/CSS) | 4 | 5 | 20 | Validate input; return clear error messages |
| edge-002 | Session storage mismatch (e.g., expired) | Occasional | High | 75 | Verify storage; prompt re-authentication | | edge-002 | Session storage mismatch (e.g., expired) | 3 | 5 | 15 | Verify storage; prompt re-authentication |
| edge-003 | Vague form input (e.g., "make webpage") | Occasional | Medium | 60 | Prompt for specific details in UI | | edge-003 | Vague form input (e.g., "make webpage") | 3 | 4 | 12 | Prompt for specific details in UI |
``` ```
### design.md ### design.md
```md ```md
**Function**: `submitForm(formData)`\ **Inputs**: `formData: { key: string, value: any }`\ **Outputs**: `{ status: "success" | "error", message: string }` **Function**: `handleApiResponse(response)`\ **Inputs**: `response: any`\ **Outputs**: `{ status: "success" | "error", data: any, message: string }`
**Logic Flow** **Logic Flow**
1. Validate formData format 1. Check response for null/undefined
2. Save to IndexedDB or queue if offline 2. Retry on timeout
3. Return success/error 3. Log errors to `activity_log.md`
**Dependencies** **Dependencies**
- IndexedDB API - API client library
- FormData model
**Edge Cases** **Edge Cases**
- edge-001: Empty fields (Risk: 70) - edge-004: Null response (Risk: 15)
- Mitigation: Check empty fields; return error - Mitigation: Return default value
- Test: Empty/partial submissions - Test: Simulate null response
- edge-002: Offline submission (Risk: 80) - edge-005: Timeout (Risk: 8)
- Mitigation: Queue in IndexedDB; sync on reconnect - Mitigation: Retry request
- Test: Simulate offline mode - Test: Simulate timeout
**Error Handling**
- Return specific error messages
- Log with timestamps
``` ```
### tasks.md ### tasks.md
```md ```md
**task-001**: Implement submitForm **task-003**: Handle null API response
- Depends: FormData model - Depends: API client
- Status: To Do - Status: To Do
- Outcome: Validates/saves form data or queues offline - Outcome: Graceful error handling with default value
- Edge Cases: Empty fields, offline scenarios - Edge Cases: Null response, timeout
- Priority: High - 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 ### activity\_log.md
@ -202,21 +260,21 @@ You must follow a robust, interactive approach to software development. Clarify
**Decision** **Decision**
- Date: 2025-07-23 - Date: 2025-07-23
- Title: Use IndexedDB for offline storage - Title: Default value for null API response
- Context: Persistent client-side data - Context: Prevent crashes on null response
- Options: IndexedDB, LocalStorage - Options: Throw error, return default
- Rationale: IndexedDB handles larger data sets - Rationale: Default value ensures continuity
- Status: Approved - Status: Approved
**Action** **Action**
- Date: 2025-07-23T14:00:00Z - Date: 2025-07-23T15:00:00Z
- Action: Implement submitForm - Action: Implement handleApiResponse
- Outcome: Validates and saves form data - Outcome: Handles null response with default
- Edge Cases: Empty fields, offline queuing - Edge Cases: Null response, timeout
- Logs: 3 unit tests passed - Logs: 2 unit tests passed
- Issues: None - Issues: None
- Next Steps: Offline sync testing - Next Steps: Test timeout retry
``` ```
### steering/performance.tuning.md ### steering/performance.tuning.md