mirror of
https://github.com/norandom/OpenUltraSAST.git
synced 2026-10-18 20:49:28 +00:00
chore: add kiro spec-driven tooling and steering docs
Add the Kiro-style agentic SDLC tooling used to drive this project: the .opencode/skills/kiro-* skill set (discovery, spec init/requirements/design/ tasks, validation, implementation, review, steering), the .kiro/settings templates, and AGENTS.md describing the workflow. Update the spec docs (assessment/design/requirements/tasks) to current state. Scope tests/test_opencode_skills.py to the project's own openultrasast-* skills so the third-party kiro-* tooling (which uses a different frontmatter convention) no longer breaks the frontmatter check. Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
Marius Ciepluch
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
8fe8911020
commit
6699f1f8f9
@@ -0,0 +1,103 @@
|
||||
---
|
||||
name: kiro-validate-design
|
||||
description: Interactive technical design quality review and validation
|
||||
metadata:
|
||||
shared-rules: "design-review.md"
|
||||
---
|
||||
|
||||
|
||||
# Technical Design Validation
|
||||
|
||||
<background_information>
|
||||
- **Mission**: Conduct interactive quality review of technical design to ensure readiness for implementation
|
||||
- **Success Criteria**:
|
||||
- Critical issues identified (maximum 3 most important concerns)
|
||||
- Balanced assessment with strengths recognized
|
||||
- Clear GO/NO-GO decision with rationale
|
||||
- Actionable feedback for improvements if needed
|
||||
</background_information>
|
||||
|
||||
<instructions>
|
||||
## Core Task
|
||||
Interactive design quality review for feature **$1** based on approved requirements and design document.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
1. **Gather Context**:
|
||||
- Read `.kiro/specs/$1/spec.json` for language and metadata
|
||||
- Read `.kiro/specs/$1/requirements.md` for requirements
|
||||
- Read `.kiro/specs/$1/design.md` for design document
|
||||
- Core steering context: `product.md`, `tech.md`, `structure.md`
|
||||
- Additional steering files only when directly relevant to architecture boundaries, integrations, runtime prerequisites, domain rules, security/performance constraints, or team conventions that affect implementation readiness
|
||||
- Relevant local agent skills or playbooks only when they clearly match the feature's host environment or use case and provide review-relevant context
|
||||
|
||||
#### Parallel Research
|
||||
|
||||
The following research areas are independent and can be executed in parallel:
|
||||
1. **Context & rules loading**: Spec documents, core steering, task-relevant extra steering, relevant local agent skills/playbooks, and `rules/design-review.md` from this skill's directory for review criteria
|
||||
2. **Codebase pattern survey**: Gather existing architecture patterns, naming conventions, and component structure from the codebase to use as reference during review
|
||||
|
||||
If multi-agent is enabled, spawn sub-agents for each area above. Otherwise execute sequentially.
|
||||
|
||||
After all parallel research completes, synthesize findings for review.
|
||||
|
||||
2. **Execute Design Review**:
|
||||
- Reference conversation history when available: leverage prior requirements discussion and user's stated design intent
|
||||
- Follow design-review.md process: Analysis → Critical Issues → Strengths → GO/NO-GO
|
||||
- Limit to 3 most important concerns
|
||||
- Engage interactively with user — ask clarifying questions, propose alternatives
|
||||
- Use language specified in spec.json for output
|
||||
|
||||
3. **Decision and Next Steps**:
|
||||
- Clear GO/NO-GO decision with rationale
|
||||
- Provide specific actionable next steps (see Next Phase below)
|
||||
|
||||
## Important Constraints
|
||||
- **Quality assurance, not perfection seeking**: Accept acceptable risk
|
||||
- **Critical focus only**: Maximum 3 issues, only those significantly impacting success
|
||||
- **Conversation-aware**: Leverage discussion history for requirements context and user intent when available
|
||||
- **Interactive approach**: Engage in dialogue, ask clarifying questions, propose alternatives
|
||||
- **Balanced assessment**: Recognize both strengths and weaknesses
|
||||
- **Actionable feedback**: All suggestions must be implementable
|
||||
- **Context Discipline**: Start with core steering and expand only with review-relevant steering or use-case-aligned local agent skills/playbooks
|
||||
</instructions>
|
||||
|
||||
## Tool Guidance
|
||||
- **Read first**: Load spec, core steering, relevant local playbooks/agent skills, and rules before review
|
||||
- **Grep if needed**: Search codebase for pattern validation or integration checks
|
||||
- **Interactive**: Engage with user throughout the review process
|
||||
|
||||
## Output Description
|
||||
Provide output in the language specified in spec.json with:
|
||||
|
||||
1. **Review Summary**: Brief overview (2-3 sentences) of design quality and readiness
|
||||
2. **Critical Issues**: Maximum 3, following design-review.md format
|
||||
3. **Design Strengths**: 1-2 positive aspects
|
||||
4. **Final Assessment**: GO/NO-GO decision with rationale and next steps
|
||||
|
||||
**Format Requirements**:
|
||||
- Use Markdown headings for clarity
|
||||
- Follow design-review.md output format
|
||||
- Keep summary concise
|
||||
|
||||
## Safety & Fallback
|
||||
|
||||
### Error Scenarios
|
||||
- **Missing Design**: If design.md doesn't exist, stop with message: "Run `/kiro-spec-design $1` first to generate design document"
|
||||
- **Design Not Generated**: If design phase not marked as generated in spec.json, warn but proceed with review
|
||||
- **Empty Steering Directory**: Warn user that project context is missing and may affect review quality
|
||||
- **Language Undefined**: Default to English (`en`) if spec.json doesn't specify language
|
||||
|
||||
### Next Phase: Task Generation
|
||||
|
||||
**If Design Passes Validation (GO Decision)**:
|
||||
- Review feedback and apply changes if needed
|
||||
- Run `/kiro-spec-tasks $1` to generate implementation tasks
|
||||
- Or `/kiro-spec-tasks $1 -y` to auto-approve and proceed directly
|
||||
|
||||
**If Design Needs Revision (NO-GO Decision)**:
|
||||
- Address critical issues identified
|
||||
- Re-run `/kiro-spec-design $1` with improvements
|
||||
- Re-validate with `/kiro-validate-design $1`
|
||||
|
||||
**Note**: Design validation is recommended but optional. Quality review helps catch issues early.
|
||||
@@ -0,0 +1,110 @@
|
||||
# Design Review Process
|
||||
|
||||
## Objective
|
||||
Conduct interactive quality review of technical design documents to ensure they are solid enough to proceed to implementation with acceptable risk.
|
||||
|
||||
## Review Philosophy
|
||||
- **Quality assurance, not perfection seeking**
|
||||
- **Critical focus**: Limit to 3 most important concerns
|
||||
- **Interactive dialogue**: Engage with designer, not one-way evaluation
|
||||
- **Balanced assessment**: Recognize strengths and weaknesses
|
||||
- **Clear decision**: Definitive GO/NO-GO with rationale
|
||||
|
||||
## Scope & Non-Goals
|
||||
|
||||
- Scope: Evaluate the quality of the design document against project context and standards to decide GO/NO-GO.
|
||||
- Non-Goals: Do not perform implementation-level design, deep technology research, or finalize technology choices. Defer such items to the design phase iteration.
|
||||
|
||||
## Core Review Criteria
|
||||
|
||||
### 1. Existing Architecture Alignment (Critical)
|
||||
- Integration with existing system boundaries and layers
|
||||
- Consistency with established architectural patterns
|
||||
- Proper dependency direction and coupling management
|
||||
- Alignment with current module organization
|
||||
|
||||
### 2. Design Consistency & Standards
|
||||
- Adherence to project naming conventions and code standards
|
||||
- Consistent error handling and logging strategies
|
||||
- Uniform configuration and dependency management
|
||||
- Alignment with established data modeling patterns
|
||||
|
||||
### 3. Extensibility & Maintainability
|
||||
- Design flexibility for future requirements
|
||||
- Clear separation of concerns and single responsibility
|
||||
- Testability and debugging considerations
|
||||
- Appropriate complexity for requirements
|
||||
|
||||
### 4. Type Safety & Interface Design
|
||||
- Proper type definitions and interface contracts
|
||||
- Avoidance of unsafe patterns (e.g., `any` in TypeScript)
|
||||
- Clear API boundaries and data structures
|
||||
- Input validation and error handling coverage
|
||||
|
||||
## Review Process
|
||||
|
||||
### Step 1: Analyze
|
||||
Analyze design against all review criteria, focusing on critical issues impacting integration, maintainability, complexity, and requirements fulfillment.
|
||||
|
||||
### Step 2: Identify Critical Issues (≤3)
|
||||
For each issue:
|
||||
```
|
||||
🔴 **Critical Issue [1-3]**: [Brief title]
|
||||
**Concern**: [Specific problem]
|
||||
**Impact**: [Why it matters]
|
||||
**Suggestion**: [Concrete improvement]
|
||||
**Traceability**: [Requirement ID/section from requirements.md]
|
||||
**Evidence**: [Design doc section/heading]
|
||||
```
|
||||
|
||||
### Step 3: Recognize Strengths
|
||||
Acknowledge 1-2 strong aspects to maintain balanced feedback.
|
||||
|
||||
### Step 4: Decide GO/NO-GO
|
||||
- **GO**: No critical architectural misalignment, requirements addressed, clear implementation path, acceptable risks
|
||||
- **NO-GO**: Fundamental conflicts, critical gaps, high failure risk, disproportionate complexity
|
||||
|
||||
## Traceability & Evidence
|
||||
|
||||
- Link each critical issue to the relevant requirement(s) from `requirements.md` (ID or section).
|
||||
- Cite evidence locations in the design document (section/heading, diagram, or artifact) to support the assessment.
|
||||
- When applicable, reference constraints from steering context to justify the issue.
|
||||
|
||||
## Output Format
|
||||
|
||||
### Design Review Summary
|
||||
2-3 sentences on overall quality and readiness.
|
||||
|
||||
### Critical Issues (≤3)
|
||||
For each: Issue, Impact, Recommendation, Traceability (e.g., 1.1, 1.2), Evidence (design.md section).
|
||||
|
||||
### Design Strengths
|
||||
1-2 positive aspects.
|
||||
|
||||
### Final Assessment
|
||||
Decision (GO/NO-GO), Rationale (1-2 sentences), Next Steps.
|
||||
|
||||
### Interactive Discussion
|
||||
Engage on designer's perspective, alternatives, clarifications, and necessary changes.
|
||||
|
||||
## Length & Focus
|
||||
|
||||
- Summary: 2–3 sentences
|
||||
- Each critical issue: 5–7 lines total (including Issue/Impact/Recommendation/Traceability/Evidence)
|
||||
- Overall review: keep concise (~400 words guideline)
|
||||
|
||||
## Review Guidelines
|
||||
|
||||
1. **Critical Focus**: Only flag issues that significantly impact success
|
||||
2. **Constructive Tone**: Provide solutions, not just criticism
|
||||
3. **Interactive Approach**: Engage in dialogue rather than one-way evaluation
|
||||
4. **Balanced Assessment**: Recognize both strengths and weaknesses
|
||||
5. **Clear Decision**: Make definitive GO/NO-GO recommendation
|
||||
6. **Actionable Feedback**: Ensure all suggestions are implementable
|
||||
|
||||
## Final Checklist
|
||||
|
||||
- **Critical Issues ≤ 3** and each includes Impact and Recommendation
|
||||
- **Traceability**: Each issue references requirement ID/section
|
||||
- **Evidence**: Each issue cites design doc location
|
||||
- **Decision**: GO/NO-GO with clear rationale and next steps
|
||||
Reference in New Issue
Block a user