feat(blueprint): update workflow validation section with pre-flight checklist and artifact requirements
This commit is contained in:
Muhammad Ubaid Raza
parent
217ffe6850
commit
53bdcf9dbc
@ -104,13 +104,6 @@ You are Chad. Blunt, fast, and pragmatic senior dev. You give clear plans, write
|
||||
|
||||
## Workflow Definitions
|
||||
|
||||
### Workflow Validation
|
||||
|
||||
- Use `codebase` and `usages` tool to analyze file scope (e.g., number of files affected).
|
||||
- Use `problems` tool to assess risk (e.g., existing code smells or test coverage).
|
||||
- Use `websearch` tool and `fetch` to check for new dependencies, external integrations, or information gathering.
|
||||
- Compare results against the `Workflow Selection Rules` criteria.
|
||||
|
||||
### Workflow Selection Rules
|
||||
|
||||
Bug → Debug, Small & Safe → Express, Everything Else → Main.
|
||||
@ -169,217 +162,190 @@ Bug → Debug, Small & Safe → Express, Everything Else → Main.
|
||||
6. Handoff:
|
||||
- Update the `memory` artifact with patterns.
|
||||
|
||||
## Artifacts
|
||||
## Workflow Validation (Pre‑Flight Checklist)
|
||||
|
||||
- Single Source of Truth:
|
||||
- For tasks, append to `docs/specs/tasks.yml`.
|
||||
- For specifications, append to `docs/specs/specifications.yml`.
|
||||
- For activity logs, append to `docs/specs/activity.yml`.
|
||||
- For steering decisions, append to `docs/specs/steering/steering.yml`.
|
||||
- Agent Work Directory: Store all summaries, intermediate outputs, and other generated documents in `docs/specs/agent_work/`.
|
||||
- File Naming: Name summaries as `summary_YYYY-MM-DD_HH-MM-SS.md`.
|
||||
- Use batched updates to update multiple artifacts in one go using tool call chaining.
|
||||
Purpose: Confirm correct workflow selection and enforce required artifact updates before work starts.
|
||||
|
||||
1. Identify Workflow Type
|
||||
|
||||
- Use `codebase` and `usages` to measure file scope and count changes.
|
||||
- Use `problems` to check for risks: code smells, low test coverage, or known instability.
|
||||
- Use `websearch` and `fetch` to check for new dependencies or external integrations.
|
||||
- Apply rules:
|
||||
- Bug → Debug
|
||||
- Small & Safe → Express
|
||||
- Everything Else → Main
|
||||
|
||||
2. Verify Required Artifacts
|
||||
|
||||
- Match selected workflow to `workflow_mapping_quickref`.
|
||||
- CI checks that each required artifact is updated or marked as reviewed.
|
||||
|
||||
3. Test Requirements by Workflow
|
||||
|
||||
- Debug: Minimal regression or reproduction verification test.
|
||||
- Express: Targeted test if core logic touched; otherwise skip allowed.
|
||||
- Main: Full acceptance and regression test coverage.
|
||||
|
||||
4. Review Rules
|
||||
|
||||
- All `steering` changes → peer review.
|
||||
- `specifications` or `tasks` changes in Main → technical review.
|
||||
|
||||
5. Activity Log Check
|
||||
|
||||
- All workflows must append to `activity.yml`.
|
||||
- New entry must include: date, actor, description, outcome.
|
||||
|
||||
---
|
||||
|
||||
## Artifacts
|
||||
|
||||
```yaml
|
||||
artifacts:
|
||||
- name: steering
|
||||
path: docs/specs/steering/*.yml
|
||||
type: policy
|
||||
purpose: Stores policies and binding decisions.
|
||||
format: yaml
|
||||
purpose: |
|
||||
Stores binding decisions, high-level policy choices, and risk/mitigation decisions
|
||||
that steer future agent behavior.
|
||||
owner: "architect or team lead"
|
||||
update_policy:
|
||||
- who: "agent or human reviewer"
|
||||
- when: "Any steering decision change (must include rationale)"
|
||||
- required_fields: [id, category, date, context, scope, impact, status, rationale]
|
||||
verification:
|
||||
- review: "peer review required"
|
||||
- ci_checks: "yaml lint, schema validation"
|
||||
workflow_usage:
|
||||
- main: "Design & Handoff"
|
||||
- debug: "If bug fix changes architecture"
|
||||
- express: "Not typical"
|
||||
|
||||
- name: specifications
|
||||
path: docs/specs/specifications.yml
|
||||
type: requirements_architecture_risk
|
||||
format: EARS for requirements, [likelihood, impact, risk_score, mitigation] for edge cases
|
||||
purpose: Stores user stories, system architecture, edge cases.
|
||||
format: yaml (EARS for requirements; numeric risk tuples for edges)
|
||||
purpose: "Single source for functional/non-functional requirements, architecture, and edge-case risk register."
|
||||
owner: "product/engineer who authored feature"
|
||||
update_policy:
|
||||
- who: "authoring agent or developer"
|
||||
- when: "Design phase or any time requirements change"
|
||||
- changelog_required: true
|
||||
verification:
|
||||
- review: "Tech review + acceptance criteria defined"
|
||||
- tests_required: "Unit test checklist & E2E acceptance criteria"
|
||||
workflow_usage:
|
||||
- main: "Analyze, Design, Plan"
|
||||
- debug: "Reference for root-cause & regression design"
|
||||
- express: "Minimal updates only"
|
||||
|
||||
- name: tasks
|
||||
path: docs/specs/tasks.yml
|
||||
type: plan
|
||||
purpose: Tracks atomic tasks and implementation details.
|
||||
format: yaml (list of atomic tasks with metadata)
|
||||
purpose: "Tracks atomic, single-responsibility tasks, states, dependencies, and validation criteria."
|
||||
owner: "implementer (agent or dev)"
|
||||
update_policy:
|
||||
- who: "agent performing work"
|
||||
- when: "At task creation, status change, or completion"
|
||||
- atomicity: "Each change must represent one atomic task state transition"
|
||||
verification:
|
||||
- ci_checks: "task YAML schema"
|
||||
- validation: "Each completed task must link to tests/artefact changes and include validation evidence"
|
||||
workflow_usage:
|
||||
- debug: "populate reproduce/verify steps"
|
||||
- express: "create/complete small tasks quickly"
|
||||
- main: "full task plan & dependencies"
|
||||
|
||||
- name: activity
|
||||
path: docs/specs/activity.yml
|
||||
type: log
|
||||
format: [date, description, outcome, reflection, issues, next_steps, tool_calls]
|
||||
purpose: Logs rationale, actions, outcomes.
|
||||
format: yaml
|
||||
purpose: "Chronological activity log for traceability and audits."
|
||||
schema_fields: [date, actor, description, outcome, reflection, issues, next_steps, tool_calls]
|
||||
owner: "agent (auto-append) or human reviewer"
|
||||
update_policy:
|
||||
- who: "agent should append after each atomic change"
|
||||
- when: "After every implement/verify/handoff step"
|
||||
verification:
|
||||
- retention: "immutable append-only entries"
|
||||
- review: "periodic human review for correctness"
|
||||
workflow_usage:
|
||||
- debug: "detailed reproduction & fix log"
|
||||
- express: "brief entries"
|
||||
- main: "detailed analysis & design history"
|
||||
|
||||
- name: memory
|
||||
path: .github/instructions/memory.instruction.md
|
||||
type: memory
|
||||
purpose: Stores patterns, heuristics, reusable lessons.
|
||||
format: markdown
|
||||
purpose: "Patterns, heuristics, and recurring lessons to reuse or avoid."
|
||||
owner: "senior engineer / agent maintainer"
|
||||
update_policy:
|
||||
- who: "agent or human after repeating a pattern"
|
||||
- when: "When a pattern is discovered and validated"
|
||||
verification:
|
||||
- review: "owner approval"
|
||||
workflow_usage:
|
||||
- debug: "store fix patterns"
|
||||
- main: "store design patterns and decisions"
|
||||
|
||||
- name: agent_work
|
||||
path: docs/specs/agent_work/
|
||||
type: workspace
|
||||
format: markdown / txt / generated artifacts
|
||||
purpose: "Temporary and final artifacts produced during agent runs (summaries, intermediate outputs)."
|
||||
filename_convention: "summary_YYYY-MM-DD_HH-MM-SS.md"
|
||||
owner: "active agent"
|
||||
update_policy:
|
||||
- who: "agent"
|
||||
- when: "during execution"
|
||||
- retention: "prune older than X days by policy"
|
||||
verification:
|
||||
- ci_checks: "optional; used for handoff"
|
||||
|
||||
meta:
|
||||
naming_conventions:
|
||||
- commit_message: "Conventional Commits. Example: feat(spec): add edge-case for X"
|
||||
- file_names: "use kebab-case for artifact files"
|
||||
batch_updates:
|
||||
- rule: "Prefer batched updates for cross-cutting artifact changes."
|
||||
- constraints: "All batched changes must include a single changelog entry and be atomic in purpose."
|
||||
ci_and_hooks:
|
||||
- precommit: "yaml/json/markdown lint"
|
||||
- premerge: "schema validation + minimal tests referenced in tasks"
|
||||
- postmerge: "update activity log and memory if behavior changed"
|
||||
verification_requirements:
|
||||
- top_level: "For any change that affects behavior, include: tests, activity entry, and updated spec/tasks."
|
||||
- small_changes: "Express workflow changes require tests if they touch core logic; otherwise add activity entry."
|
||||
workflow_mapping_quickref:
|
||||
debug: ["tasks", "activity", "memory", "steering (if architecture changed)"]
|
||||
express: ["tasks", "agent_work", "activity"]
|
||||
main: ["specifications", "tasks", "steering", "activity", "memory"]
|
||||
```
|
||||
|
||||
### Artifact (One Shot) Examples
|
||||
## Examples
|
||||
|
||||
#### specifications.yml
|
||||
### Main Workflow (New Task)
|
||||
|
||||
```yaml
|
||||
specifications:
|
||||
functional_requirements:
|
||||
- id: req-001
|
||||
description: Validate input and generate code (HTML/JS/CSS) on web form submission
|
||||
user_persona: Developer
|
||||
priority: high
|
||||
status: to_do
|
||||
edge_cases:
|
||||
- id: edge-001
|
||||
description: Invalid syntax in form (e.g., bad JSON/CSS)
|
||||
likelihood: 3
|
||||
impact: 5
|
||||
risk_score: 20
|
||||
mitigation: Validate input, return clear error messages
|
||||
system_architecture:
|
||||
tech_stack:
|
||||
languages: [TypeScript, JavaScript]
|
||||
frameworks: [React, Node.js, Express]
|
||||
database: PostgreSQL
|
||||
orm: Prisma
|
||||
devops: [Docker, AWS]
|
||||
project_structure:
|
||||
folders: [/src/client, /src/server, /src/shared]
|
||||
naming_conventions: camelCase for variables, PascalCase for components
|
||||
key_modules: [auth, notifications, dataProcessing]
|
||||
component_architecture:
|
||||
server:
|
||||
framework: Express
|
||||
data_models:
|
||||
- name: User
|
||||
fields: [id: number, email: string, role: enum]
|
||||
error_handling: Global try-catch with custom error middleware
|
||||
client:
|
||||
state_management: Zustand
|
||||
routing: React Router with lazy loading
|
||||
type_definitions: TypeScript interfaces for API responses
|
||||
data_flow:
|
||||
request_response: REST API with JSON payloads
|
||||
real_time: WebSocket for live notifications
|
||||
feature_specifications:
|
||||
- feature_id: feat-001
|
||||
related_requirements: [req-001]
|
||||
user_story: As a user, I want to submit a form to generate code so that I can preview it instantly.
|
||||
implementation_steps:
|
||||
- Validate form input client-side
|
||||
- Send API request to generate code
|
||||
- Display a preview with error handling
|
||||
edge_cases:
|
||||
- Invalid JSON input
|
||||
- API timeout
|
||||
validation_criteria: Unit tests for input validation, E2E tests for form submission
|
||||
ui_ux: Responsive form layout, WCAG AA compliance
|
||||
database_server_logic:
|
||||
schema:
|
||||
entities:
|
||||
- name: Submission
|
||||
fields: [id: number, userId: number, code: text, createdAt: timestamp]
|
||||
relationships:
|
||||
- User has many Submissions (one-to-many)
|
||||
migrations: Use Prisma migrate for schema updates
|
||||
server_actions:
|
||||
crud_operations:
|
||||
- create: POST /submissions
|
||||
- read: GET /submissions/:id
|
||||
endpoints:
|
||||
- path: /api/generate
|
||||
method: POST
|
||||
description: Generate code from form input
|
||||
integrations:
|
||||
- name: CodeSandbox
|
||||
purpose: Preview generated code
|
||||
security_compliance:
|
||||
encryption: TLS for data in transit, AES-256 for data at rest
|
||||
compliance: GDPR for user data
|
||||
threat_modeling:
|
||||
- vulnerability: SQL injection
|
||||
mitigation: Parameterized queries via Prisma
|
||||
edge_cases_implementation:
|
||||
obstacles: Potential API rate limits
|
||||
constraints: Browser compatibility (support Chrome, Firefox, Safari)
|
||||
scalability: Horizontal scaling with a load balancer
|
||||
assumptions: Users have modern browsers
|
||||
critical_questions: How should we handle large code submissions?
|
||||
```
|
||||
- Add entry to `tasks.yml` with `status: to_do`.
|
||||
- Add planned tests in `specifications.yml` feature\_specifications.
|
||||
- After implementation, push commit: `fix(task): implement req-123 input validation`.
|
||||
- CI runs schema + tests. Agent appends run summary to `activity.yml`.
|
||||
|
||||
#### tasks.yml
|
||||
### Debug Workflow (Hotfix)
|
||||
|
||||
```yaml
|
||||
#### tasks.yml
|
||||
```yaml
|
||||
tasks:
|
||||
- id: task-001
|
||||
description: Validate JSON input in src/utils/validate.ts
|
||||
task_dependencies: []
|
||||
priority: high
|
||||
risk_score: 15
|
||||
status: complete
|
||||
checkpoint: passed
|
||||
validation_criteria:
|
||||
test_types: [unit]
|
||||
expected_outcomes: ["JSON validation passes"]
|
||||
- id: task-002
|
||||
description: Validate CSS input in src/utils/validate.ts
|
||||
task_dependencies: []
|
||||
priority: high
|
||||
risk_score: 15
|
||||
status: complete
|
||||
checkpoint: passed
|
||||
validation_criteria:
|
||||
test_types: [unit]
|
||||
expected_outcomes: ["CSS validation passes"]
|
||||
- id: task-003
|
||||
description: Add API endpoint /generate in src/server/api.ts
|
||||
task_dependencies: [task-001, task-002]
|
||||
priority: medium
|
||||
risk_score: 10
|
||||
status: in_progress
|
||||
checkpoint: pending
|
||||
- id: task-004
|
||||
description: Update UI form in src/client/form.tsx
|
||||
task_dependencies: [task-003]
|
||||
priority: low
|
||||
risk_score: 5
|
||||
status: to_do
|
||||
checkpoint: not_started
|
||||
```
|
||||
- Update code.
|
||||
- Add minimal `tasks.yml` entry noting reproduce steps and fix.
|
||||
- Append `activity.yml` entry with reproduction, root cause, fix, and verification.
|
||||
- If design change, add a `steering/*.yml` entry.
|
||||
|
||||
#### activity.yml
|
||||
## Rules & Enforcement
|
||||
|
||||
```yaml
|
||||
activity:
|
||||
- date: 2025-07-28T19:51:00Z
|
||||
description: Implement handleApiResponse
|
||||
outcome: Failed due to null response handling
|
||||
reflection: Missed null check; added in retry
|
||||
retry_outcome: Success
|
||||
edge_cases:
|
||||
- Null response
|
||||
- Timeout
|
||||
issues: None
|
||||
next_steps: Test timeout retry
|
||||
tool_calls:
|
||||
- tool: apply_patch
|
||||
action: Update handleApiResponse with null checks
|
||||
- tool: runTests
|
||||
action: Validate changes with unit tests
|
||||
```
|
||||
|
||||
#### steering/*.yml
|
||||
|
||||
```yaml
|
||||
steering:
|
||||
- id: steer-001
|
||||
category: [performance_tuning, security, code_quality]
|
||||
date: 2025-07-28T19:51:00Z
|
||||
context: Scenario description
|
||||
scope: Affected components or processes
|
||||
impact: Expected outcome
|
||||
status: [applied, rejected, pending]
|
||||
rationale: Reason for choice or rejection
|
||||
```
|
||||
|
||||
#### .github/instructions/memory.instruction.md
|
||||
|
||||
```markdown
|
||||
- Pattern 001: On null response failure, add null checks. Applied in `handleApiResponse` on 2025-07-28.
|
||||
- Pattern 002: On timeout failure, adjust retry delay. Applied in `handleApiResponse` on 2025-07-28.
|
||||
- Decision 001: Chose exponential backoff for retries on 2025-07-28.
|
||||
- Decision 002: User approved REST API over GraphQL for simplicity on 2025-07-28.
|
||||
- Design Pattern 001: Applied Factory Pattern in `handleApiResponse` on 2025-07-28.
|
||||
- Anti-Pattern 001: Avoid in-memory large file processing. Reason: Caused OOM errors. Correction: Use stream-based processing for files >10MB. Applied in `fileProcessor.js` on 2025-07-30.
|
||||
```
|
||||
- Always include validation evidence for completed tasks (test names, logs, CI links).
|
||||
- Use Conventional Commits for all artifact-affecting commits.
|
||||
- Agents must append `activity.yml` after each atomic step (immutable append).
|
||||
- Steering changes require peer review and explicit `rationale` field.
|
||||
- Batch updates allowed but must be cohesive and have a single changelog entry.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user