mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
Refactor code structure for improved readability and maintainability
This commit is contained in:
catlog22
75
.ccw/workflows/cli-templates/fix-plan-template.json
Normal file
75
.ccw/workflows/cli-templates/fix-plan-template.json
Normal file
@@ -0,0 +1,75 @@
|
||||
{
|
||||
"_template_description": "Template for fix planning output. Planning agent reads this template and generates actual fix-plan.json",
|
||||
"_usage": "Planning agent should follow this structure when analyzing findings and creating fix plan",
|
||||
|
||||
"plan_id": "<string: plan-{timestamp}>",
|
||||
"created_at": "<string: ISO8601 timestamp>",
|
||||
"total_findings": "<number: total findings to fix>",
|
||||
|
||||
"execution_strategy": {
|
||||
"approach": "<string: hybrid|parallel|serial>",
|
||||
"parallel_limit": "<number: max concurrent agents, default 3>",
|
||||
"total_stages": "<number: how many stages in timeline>",
|
||||
"rationale": "<string: explain why this strategy was chosen>"
|
||||
},
|
||||
|
||||
"groups": [
|
||||
{
|
||||
"group_id": "<string: unique group identifier like G1, G2, ...>",
|
||||
"group_name": "<string: descriptive name for this group>",
|
||||
"findings": ["<array of finding IDs>"],
|
||||
|
||||
"fix_strategy": {
|
||||
"approach": "<string: high-level fix approach>",
|
||||
"rationale": "<string: why these findings were grouped together>",
|
||||
"complexity": "<string: low|medium|high>",
|
||||
"estimated_duration_minutes": "<number: estimated time>",
|
||||
"test_pattern": "<string: test file glob pattern like tests/auth/**/*.test.*>",
|
||||
"rollback_plan": "<string: what to do if fix fails>"
|
||||
},
|
||||
|
||||
"risk_assessment": {
|
||||
"level": "<string: low|medium|high|critical>",
|
||||
"concerns": ["<array of strings: potential risks>"],
|
||||
"mitigation": "<string: how to mitigate risks>"
|
||||
}
|
||||
}
|
||||
],
|
||||
|
||||
"timeline": [
|
||||
{
|
||||
"stage": "<number: stage number 1-indexed>",
|
||||
"groups": ["<array of group IDs to execute in this stage>"],
|
||||
"execution_mode": "<string: parallel|serial>",
|
||||
"depends_on": ["<optional: array of group IDs this stage depends on>"],
|
||||
"rationale": "<string: why these groups are in this stage with this mode>"
|
||||
}
|
||||
],
|
||||
|
||||
"_instructions": {
|
||||
"grouping_principles": [
|
||||
"Group findings in the same file with same dimension",
|
||||
"Group findings with similar root causes (high semantic similarity)",
|
||||
"Consider file dependencies and execution order",
|
||||
"Balance group sizes for efficient parallel execution"
|
||||
],
|
||||
"execution_strategy_guidelines": [
|
||||
"Use parallel for independent groups in different files",
|
||||
"Use serial for dependent changes (e.g., shared utilities)",
|
||||
"Limit parallelism to 3 concurrent agents to avoid resource contention",
|
||||
"High-risk groups should be isolated for careful monitoring"
|
||||
],
|
||||
"test_strategy_guidelines": [
|
||||
"Identify test files related to changed code",
|
||||
"Use specific patterns for faster test execution",
|
||||
"Ensure test coverage captures all fix impacts",
|
||||
"Define clear pass criteria (usually 100% pass rate)"
|
||||
],
|
||||
"risk_assessment_guidelines": [
|
||||
"Low: Simple fixes with comprehensive test coverage",
|
||||
"Medium: Moderate changes affecting multiple components",
|
||||
"High: Core logic changes or security-critical fixes",
|
||||
"Critical: Database schema changes or breaking API changes"
|
||||
]
|
||||
}
|
||||
}
|
||||
48
.ccw/workflows/cli-templates/fix-progress-template.json
Normal file
48
.ccw/workflows/cli-templates/fix-progress-template.json
Normal file
@@ -0,0 +1,48 @@
|
||||
{
|
||||
"$schema": "fix-progress-template.json",
|
||||
"$comment": "Template for fix-progress-{N}.json - one per group, initialized by planning agent, updated by execution agent",
|
||||
|
||||
"progress_id": "fix-progress-N",
|
||||
"group_id": "GN",
|
||||
"group_name": "Group name from fix plan",
|
||||
"status": "pending",
|
||||
"phase": "waiting",
|
||||
|
||||
"assigned_agent": null,
|
||||
"started_at": null,
|
||||
"last_update": "ISO 8601 timestamp",
|
||||
|
||||
"findings": [
|
||||
{
|
||||
"finding_id": "finding-uuid",
|
||||
"finding_title": "Finding title from review",
|
||||
"file": "path/to/file.ts",
|
||||
"line": 0,
|
||||
"status": "pending",
|
||||
"result": null,
|
||||
"attempts": 0,
|
||||
"started_at": null,
|
||||
"completed_at": null,
|
||||
"commit_hash": null,
|
||||
"test_passed": null
|
||||
}
|
||||
],
|
||||
|
||||
"summary": {
|
||||
"total_findings": 0,
|
||||
"pending": 0,
|
||||
"in_progress": 0,
|
||||
"fixed": 0,
|
||||
"failed": 0,
|
||||
"percent_complete": 0.0
|
||||
},
|
||||
|
||||
"current_finding": null,
|
||||
|
||||
"flow_control": {
|
||||
"implementation_approach": [],
|
||||
"current_step": null
|
||||
},
|
||||
|
||||
"errors": []
|
||||
}
|
||||
@@ -0,0 +1,299 @@
|
||||
# SKILL.md Template for Style Memory Package
|
||||
|
||||
---
|
||||
name: style-{package_name}
|
||||
description: {intelligent_description}
|
||||
---
|
||||
|
||||
# {Package Name} Style SKILL Package
|
||||
|
||||
## 🔍 Quick Index
|
||||
|
||||
### Available JSON Fields
|
||||
|
||||
**High-level structure overview for quick understanding**
|
||||
|
||||
#### design-tokens.json
|
||||
```
|
||||
.colors # Color palette (brand, semantic, surface, text, border)
|
||||
.typography # Font families, sizes, weights, line heights
|
||||
.spacing # Spacing scale (xs, sm, md, lg, xl, etc.)
|
||||
.border_radius # Border radius tokens (sm, md, lg, etc.)
|
||||
.shadows # Shadow definitions (elevation levels)
|
||||
._metadata # Usage recommendations and guidelines
|
||||
├─ .usage_recommendations.typography
|
||||
├─ .usage_recommendations.spacing
|
||||
└─ ...
|
||||
```
|
||||
|
||||
#### layout-templates.json
|
||||
```
|
||||
.layout_templates # Component layout patterns
|
||||
├─ .<component_name>
|
||||
│ ├─ .component_type # "universal" or "specialized"
|
||||
│ ├─ .variants # Component variants array
|
||||
│ ├─ .usage_guide # Usage guidelines
|
||||
│ │ ├─ .common_sizes
|
||||
│ │ ├─ .variant_recommendations
|
||||
│ │ ├─ .usage_context
|
||||
│ │ └─ .accessibility_tips
|
||||
│ └─ ...
|
||||
```
|
||||
|
||||
#### animation-tokens.json (if available)
|
||||
```
|
||||
.duration # Animation duration tokens
|
||||
.easing # Easing function tokens
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
### Progressive jq Usage Guide
|
||||
|
||||
#### 📦 Package Overview
|
||||
|
||||
**Base Location**: `.workflow/reference_style/{package_name}/`
|
||||
|
||||
**JSON Files**:
|
||||
- **Design Tokens**: `.workflow/reference_style/{package_name}/design-tokens.json`
|
||||
- **Layout Templates**: `.workflow/reference_style/{package_name}/layout-templates.json`
|
||||
- **Animation Tokens**: `.workflow/reference_style/{package_name}/animation-tokens.json` {has_animations ? "(available)" : "(not available)"}
|
||||
|
||||
**⚠️ Usage Note**: All jq commands below should be executed with directory context. Use the pattern:
|
||||
```bash
|
||||
cd .workflow/reference_style/{package_name} && jq '<query>' <file>.json
|
||||
```
|
||||
|
||||
#### 🔰 Level 0: Basic Queries (~5K tokens)
|
||||
|
||||
```bash
|
||||
# View entire file
|
||||
jq '.' <file>.json
|
||||
|
||||
# List top-level keys
|
||||
jq 'keys' <file>.json
|
||||
|
||||
# Extract specific field
|
||||
jq '.<field_name>' <file>.json
|
||||
```
|
||||
|
||||
**Use when:** Quick reference, first-time exploration
|
||||
|
||||
---
|
||||
|
||||
#### 🎯 Level 1: Filter & Extract (~12K tokens)
|
||||
|
||||
```bash
|
||||
# Count items
|
||||
jq '.<field> | length' <file>.json
|
||||
|
||||
# Filter by condition
|
||||
jq '[.<field>[] | select(.<key> == "<value>")]' <file>.json
|
||||
|
||||
# Extract names
|
||||
jq -r '.<field> | to_entries[] | select(<condition>) | .key' <file>.json
|
||||
|
||||
# Formatted output
|
||||
jq -r '.<field> | to_entries[] | "\(.key): \(.value)"' <file>.json
|
||||
```
|
||||
|
||||
**Universal components filter:** `select(.component_type == "universal")`
|
||||
|
||||
**Use when:** Building components, filtering data
|
||||
|
||||
---
|
||||
|
||||
#### 🚀 Level 2: Combine & Transform (~20K tokens)
|
||||
|
||||
```bash
|
||||
# Pattern search
|
||||
jq '.<field> | keys[] | select(. | contains("<pattern>"))' <file>.json
|
||||
|
||||
# Regex match
|
||||
jq -r '.<field> | to_entries[] | select(.key | test("<regex>"; "i"))' <file>.json
|
||||
|
||||
# Multi-file query
|
||||
jq '.' file1.json && jq '.' file2.json
|
||||
|
||||
# Nested extraction
|
||||
jq '.<field>["<name>"].<nested_field>' <file>.json
|
||||
|
||||
# Preview server (requires directory context)
|
||||
cd .workflow/reference_style/{package_name} && python -m http.server 8080
|
||||
```
|
||||
|
||||
**Use when:** Complex queries, comprehensive analysis
|
||||
|
||||
---
|
||||
|
||||
### Quick Reference: Consistency vs Adaptation
|
||||
|
||||
| Aspect | Prioritize Consistency | Prioritize Adaptation |
|
||||
|--------|----------------------|---------------------|
|
||||
| **UI Components** | Standard buttons, inputs, cards | Hero sections, landing pages |
|
||||
| **Spacing** | Component internal padding | Page layout, section gaps |
|
||||
| **Typography** | Body text, headings (h1-h6) | Display text, metric numbers |
|
||||
| **Colors** | Brand colors, semantic states | Marketing accents, data viz |
|
||||
| **Radius** | Interactive elements | Feature cards, containers |
|
||||
|
||||
---
|
||||
|
||||
## 📖 How to Use This SKILL
|
||||
|
||||
### Quick Access Pattern
|
||||
|
||||
**This SKILL provides design references, NOT executable code.** To use the design system:
|
||||
|
||||
1. **Query JSON files with jq commands**
|
||||
2. **Extract relevant tokens** for your implementation
|
||||
3. **Adapt values** based on your specific design needs
|
||||
|
||||
|
||||
### Progressive Loading
|
||||
|
||||
- **Level 0** (~5K tokens): Quick token reference with `jq '.colors'`, `jq '.typography'`
|
||||
- **Level 1** (~12K tokens): Component filtering with `select(.component_type == "universal")`
|
||||
- **Level 2** (~20K tokens): Complex queries, animations, and preview
|
||||
|
||||
---
|
||||
## ⚡ Core Rules
|
||||
|
||||
1. **Reference, Not Requirements**: This is a design reference system for inspiration and guidance. **DO NOT rigidly copy values.** Analyze the patterns and principles, then adapt creatively to build the optimal design for your specific requirements. Your project's unique needs, brand identity, and user context should drive the final design decisions.
|
||||
|
||||
2. **Universal Components Only**: When using `layout-templates.json`, **ONLY** reference components where `component_type: "universal"`. **IGNORE** `component_type: "specialized"`.
|
||||
|
||||
3. **Token Adaptation**: Adjust design tokens (colors, spacing, typography, shadows, etc.) based on:
|
||||
- Brand requirements and identity
|
||||
- Accessibility standards (WCAG compliance, readability)
|
||||
- Platform conventions (mobile/desktop, iOS/Android/Web)
|
||||
- Context needs (light/dark mode, responsive breakpoints)
|
||||
- User experience goals and interaction patterns
|
||||
- Performance and technical constraints
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Token Adaptation Strategy
|
||||
|
||||
### Balancing Consistency and Flexibility
|
||||
|
||||
**The Core Problem**: Reference tokens may not have suitable sizes or styles for your new interface needs. Blindly copying leads to poor, rigid design. But ignoring tokens breaks visual consistency.
|
||||
|
||||
**The Solution**: Use tokens as a **pattern foundation**, not a value prison.
|
||||
|
||||
---
|
||||
|
||||
### Decision Framework
|
||||
|
||||
**When to Use Existing Tokens (Maintain Consistency)**:
|
||||
- ✅ Common UI elements (buttons, cards, inputs, typography hierarchy)
|
||||
- ✅ Repeated patterns across multiple pages
|
||||
- ✅ Standard interactions (hover, focus, active states)
|
||||
- ✅ When existing token serves the purpose adequately
|
||||
|
||||
**When to Extend Tokens (Adapt for New Needs)**:
|
||||
- ✅ New component type not in reference system
|
||||
- ✅ Existing token creates visually awkward result
|
||||
- ✅ Special context requires unique treatment (hero sections, landing pages, data visualization)
|
||||
- ✅ Target device/platform has different constraints (mobile vs desktop)
|
||||
|
||||
|
||||
|
||||
### Integration Guidelines
|
||||
|
||||
**1. Document Your Extensions**
|
||||
When you create new token values:
|
||||
- Note the pattern/method used (interpolation, extrapolation, etc.)
|
||||
- Document the specific use case
|
||||
- Consider if it should be added to the design system
|
||||
|
||||
**2. Maintain Visual Consistency**
|
||||
- Use extended values sparingly (don't create 50 spacing tokens)
|
||||
- Prefer using existing tokens when "close enough" (90% fit is often acceptable)
|
||||
- Group extended tokens by context (e.g., "hero-section-padding", "dashboard-metric-size")
|
||||
|
||||
**3. Respect Core Patterns**
|
||||
- **Color**: Preserve hue and semantic meaning, adjust lightness/saturation
|
||||
- **Spacing**: Follow progression pattern (linear/geometric)
|
||||
- **Typography**: Maintain scale ratio and line-height relationships
|
||||
- **Radius**: Continue shape language (sharp vs rounded personality)
|
||||
|
||||
**4. Know When to Break Rules**
|
||||
Sometimes you need unique values for special contexts:
|
||||
- Landing page hero sections
|
||||
- Marketing/promotional components
|
||||
- Data visualization (charts, graphs)
|
||||
- Platform-specific requirements
|
||||
|
||||
**For these cases**: Create standalone tokens with clear naming (`hero-title-size`, `chart-accent-color`) rather than forcing into standard scale.
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Style Understanding & Design References
|
||||
|
||||
**IMPORTANT**: These are reference values and patterns extracted from codebase for inspiration. **DO NOT copy rigidly.** Use them as a starting point to understand design patterns, then creatively adapt to build the optimal solution for your specific project requirements, user needs, and brand identity.
|
||||
|
||||
### Design Principles
|
||||
|
||||
**Dynamically generated based on design token characteristics:**
|
||||
|
||||
{GENERATE_PRINCIPLES_FROM_DESIGN_ANALYSIS}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_colors:
|
||||
**Color System**
|
||||
- Semantic naming: {DESIGN_ANALYSIS.color_semantic ? "primary/secondary/accent hierarchy" : "descriptive names"}
|
||||
- Use color intentionally to guide attention and convey meaning
|
||||
- Maintain consistent color relationships for brand identity
|
||||
- Ensure sufficient contrast ratios (WCAG AA/AAA) for accessibility
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.spacing_pattern detected:
|
||||
**Spatial Rhythm**
|
||||
- Primary scale pattern: {DESIGN_ANALYSIS.spacing_scale} (derived from analysis, represents actual token values)
|
||||
- Pattern characteristics: {DESIGN_ANALYSIS.spacing_pattern} (e.g., "primarily geometric with practical refinements")
|
||||
- {DESIGN_ANALYSIS.spacing_pattern == "geometric" ? "Geometric progression provides clear hierarchy with exponential growth" : "Linear progression offers subtle gradations for fine control"}
|
||||
- Apply systematically: smaller values (4-12px) for compact elements, medium (16-32px) for standard spacing, larger (48px+) for section breathing room
|
||||
- Note: Practical scales may deviate slightly from pure mathematical patterns to optimize for real-world UI needs
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_typography with typography_hierarchy:
|
||||
**Typographic System**
|
||||
- Type scale establishes content hierarchy and readability
|
||||
- Size progression: {DESIGN_ANALYSIS.typography_scale_example} (e.g., "12px→14px→16px→20px→24px")
|
||||
- Use scale consistently: body text at base, headings at larger sizes
|
||||
- Maintain adequate line-height for readability (1.4-1.6 for body text)
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_radius:
|
||||
**Shape Language**
|
||||
- Radius style: {DESIGN_ANALYSIS.radius_style} (e.g., "sharp <4px: modern, technical" or "rounded >8px: friendly, approachable")
|
||||
- Creates visual personality: sharp = precision, rounded = warmth
|
||||
- Apply consistently across similar elements (all cards, all buttons)
|
||||
- Match to brand tone: corporate/technical = sharper, consumer/friendly = rounder
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_shadows:
|
||||
**Depth & Elevation**
|
||||
- Shadow pattern: {DESIGN_ANALYSIS.shadow_pattern} (e.g., "elevation-based: subtle→moderate→prominent")
|
||||
- Use shadows to indicate interactivity and component importance
|
||||
- Consistent application reinforces spatial relationships
|
||||
- Subtle for static cards, prominent for floating/interactive elements
|
||||
}
|
||||
|
||||
{IF DESIGN_ANALYSIS.has_animations:
|
||||
**Motion & Timing**
|
||||
- Duration range: {DESIGN_ANALYSIS.animation_range} (e.g., "100ms (fast feedback) to 300ms (content transitions)")
|
||||
- Easing variety: {DESIGN_ANALYSIS.easing_variety} (e.g., "ease-in-out for natural motion, ease-out for UI responses")
|
||||
- Fast durations for immediate feedback, slower for spatial changes
|
||||
- Consistent timing creates predictable, polished experience
|
||||
}
|
||||
|
||||
{ALWAYS include:
|
||||
**Accessibility First**
|
||||
- Minimum 4.5:1 contrast for text, 3:1 for UI components (WCAG AA)
|
||||
- Touch targets ≥44px for mobile interaction
|
||||
- Clear focus states for keyboard navigation
|
||||
- Test with screen readers and keyboard-only navigation
|
||||
}
|
||||
|
||||
---
|
||||
120
.ccw/workflows/cli-templates/planning-roles/data-architect.md
Normal file
120
.ccw/workflows/cli-templates/planning-roles/data-architect.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
name: data-architect
|
||||
description: Data modeling, storage architecture, and database design planning
|
||||
---
|
||||
|
||||
# Data Architect Planning Template
|
||||
|
||||
You are a **Data Architect** specializing in data modeling and storage architecture planning.
|
||||
|
||||
## Your Role & Responsibilities
|
||||
|
||||
**Primary Focus**: Data architecture design, storage strategy, and data flow planning
|
||||
|
||||
**Core Responsibilities**:
|
||||
- Database schema design and data model definition
|
||||
- Data flow diagrams and integration mapping
|
||||
- Storage strategy and performance optimization planning
|
||||
- API design specifications and data contracts
|
||||
- Data migration and synchronization strategies
|
||||
- Data governance, security, and compliance planning
|
||||
|
||||
**Does NOT Include**: Writing database code, implementing queries, performing data operations
|
||||
|
||||
## Planning Document Structure
|
||||
|
||||
Generate a comprehensive data architecture planning document with the following structure:
|
||||
|
||||
### 1. Data Architecture Overview
|
||||
- **Business Context**: Primary business domain, data objectives, stakeholders
|
||||
- **Data Strategy**: Vision, principles, governance framework, compliance requirements
|
||||
- **Success Criteria**: How data architecture success will be measured
|
||||
|
||||
### 2. Data Requirements Analysis
|
||||
- **Functional Requirements**: Data entities, operations (CRUD), transformations, integrations
|
||||
- **Non-Functional Requirements**: Volume, velocity, variety, veracity (4 Vs of Big Data)
|
||||
- **Data Quality Requirements**: Accuracy, completeness, consistency, timeliness standards
|
||||
|
||||
### 3. Data Model Design
|
||||
- **Conceptual Model**: High-level business entities, relationships, business rules
|
||||
- **Logical Model**: Normalized entities, attributes, primary/foreign keys, indexes
|
||||
- **Physical Model**: Database tables, columns, partitioning, storage optimization
|
||||
|
||||
### 4. Database Design Strategy
|
||||
- **Technology Selection**: Database platform choice (relational/NoSQL/NewSQL), rationale
|
||||
- **Database Architecture**: Single database, multiple databases, data warehouse, data lake
|
||||
- **Performance Optimization**: Indexing strategy, query optimization, caching, connection pooling
|
||||
|
||||
### 5. Data Integration Architecture
|
||||
- **Data Sources**: Internal systems, external APIs, file systems, real-time streams
|
||||
- **Integration Patterns**: ETL processes, real-time integration, batch processing, API integration
|
||||
- **Data Pipeline Design**: Ingestion, processing, storage, distribution workflows
|
||||
|
||||
### 6. Data Security & Governance
|
||||
- **Data Classification**: Public, internal, confidential, restricted data categories
|
||||
- **Security Measures**: Encryption at rest/transit, access controls, audit logging
|
||||
- **Privacy Protection**: PII handling, anonymization, consent management, right to erasure
|
||||
- **Data Governance**: Ownership, stewardship, lifecycle management, quality monitoring
|
||||
|
||||
### 7. Scalability & Performance Planning
|
||||
- **Scalability Strategy**: Horizontal/vertical scaling, auto-scaling, load distribution
|
||||
- **Performance Optimization**: Query performance, data partitioning, replication, caching
|
||||
- **Capacity Planning**: Storage, compute, network requirements and growth projections
|
||||
|
||||
## Template Guidelines
|
||||
|
||||
- Begin with **clear business context** and data objectives
|
||||
- Define **comprehensive data models** from conceptual to physical level
|
||||
- Consider **data quality requirements** and monitoring strategies
|
||||
- Plan for **scalability and performance** from the beginning
|
||||
- Address **security and compliance** requirements early
|
||||
- Design **flexible data integration** patterns for future growth
|
||||
- Include **governance framework** for data management
|
||||
- Focus on **data architecture planning** rather than actual database implementation
|
||||
|
||||
## Output Format
|
||||
|
||||
Create a detailed markdown document titled: **"Data Architecture Planning: [Task Description]"**
|
||||
|
||||
Include comprehensive sections covering data strategy, requirements analysis, model design, database architecture, integration patterns, security planning, and scalability considerations. Provide clear guidance for building robust, scalable, and secure data systems.
|
||||
|
||||
## Brainstorming Documentation Files to Create
|
||||
|
||||
When conducting brainstorming sessions, create the following files:
|
||||
|
||||
### Individual Role Analysis File: `data-architect-analysis.md`
|
||||
```markdown
|
||||
# Data Architect Analysis: [Topic]
|
||||
|
||||
## Data Requirements Analysis
|
||||
- Core data entities and relationships
|
||||
- Data flow patterns and integration needs
|
||||
- Storage and processing requirements
|
||||
|
||||
## Architecture Design Assessment
|
||||
- Database design patterns and selection criteria
|
||||
- Data pipeline architecture and ETL considerations
|
||||
- Scalability and performance optimization strategies
|
||||
|
||||
## Data Security and Governance
|
||||
- Data protection and privacy requirements
|
||||
- Access control and data governance frameworks
|
||||
- Compliance and regulatory considerations
|
||||
|
||||
## Integration and Analytics Framework
|
||||
- Data integration patterns and API design
|
||||
- Analytics and reporting requirements
|
||||
- Real-time vs batch processing needs
|
||||
|
||||
## Recommendations
|
||||
- Data architecture approach and technology stack
|
||||
- Implementation phases and migration strategy
|
||||
- Performance optimization and monitoring approaches
|
||||
```
|
||||
|
||||
### Session Contribution Template
|
||||
For role-specific contributions to broader brainstorming sessions, provide:
|
||||
- Data implications and requirements for each solution
|
||||
- Database design patterns and technology recommendations
|
||||
- Data integration and analytics considerations
|
||||
- Scalability and performance assessment
|
||||
119
.ccw/workflows/cli-templates/planning-roles/product-manager.md
Normal file
119
.ccw/workflows/cli-templates/planning-roles/product-manager.md
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
name: product-manager
|
||||
description: Product strategy, user needs analysis, and business value optimization
|
||||
---
|
||||
|
||||
# Product Manager Planning Template
|
||||
|
||||
You are a **Product Manager** specializing in product strategy, user needs analysis, and business value optimization.
|
||||
|
||||
## Your Role & Responsibilities
|
||||
|
||||
**Primary Focus**: Product strategy, user requirements, market positioning, and business value creation
|
||||
|
||||
**Core Responsibilities**:
|
||||
- User story creation and requirement prioritization
|
||||
- Market analysis and competitive positioning research
|
||||
- Business case development and ROI analysis
|
||||
- Product roadmap planning and milestone definition
|
||||
- Stakeholder alignment and communication strategies
|
||||
- Success metrics definition and measurement planning
|
||||
|
||||
**Does NOT Include**: Technical implementation, UI design execution, direct user research execution
|
||||
|
||||
## Planning Document Structure
|
||||
|
||||
Generate a comprehensive product management planning document with the following structure:
|
||||
|
||||
### 1. Product Vision & Strategy
|
||||
- **Product Goal**: Primary objective and target market
|
||||
- **User Value Proposition**: Core value delivered to users
|
||||
- **Business Objectives**: Revenue, growth, and strategic business goals
|
||||
- **Success Metrics**: KPIs, OKRs, and measurement criteria
|
||||
|
||||
### 2. Market Analysis & Positioning
|
||||
- **Target Market**: Primary and secondary user segments
|
||||
- **Competitive Landscape**: Key competitors, differentiation opportunities
|
||||
- **Market Opportunity**: Size, growth potential, timing considerations
|
||||
- **Positioning Strategy**: Unique value proposition and market positioning
|
||||
|
||||
### 3. User Requirements & Stories
|
||||
- **User Personas**: Primary, secondary, and edge case user definitions
|
||||
- **User Journey Mapping**: Current state, desired state, pain points
|
||||
- **User Stories**: Functional requirements in user story format
|
||||
- **Acceptance Criteria**: Clear definition of done for each requirement
|
||||
|
||||
### 4. Feature Prioritization & Roadmap
|
||||
- **Feature Backlog**: Comprehensive list of potential features
|
||||
- **Prioritization Matrix**: Impact vs effort analysis
|
||||
- **Release Planning**: Phased rollout strategy and timeline
|
||||
- **Dependency Mapping**: Feature dependencies and sequencing
|
||||
|
||||
### 5. Business Case & Resource Requirements
|
||||
- **ROI Analysis**: Expected return on investment
|
||||
- **Resource Allocation**: Team members, budget, timeline requirements
|
||||
- **Risk Assessment**: Business, market, and execution risks
|
||||
- **Success Criteria**: Measurable outcomes and success indicators
|
||||
|
||||
### 6. Stakeholder Management & Communication
|
||||
- **Stakeholder Map**: Internal and external stakeholders
|
||||
- **Communication Plan**: Regular updates, feedback loops, decision points
|
||||
- **Change Management**: Process for handling scope and priority changes
|
||||
- **Launch Strategy**: Go-to-market planning and launch coordination
|
||||
|
||||
## Key Questions to Address
|
||||
|
||||
1. **User Value**: What specific problem are we solving for users?
|
||||
2. **Business Impact**: How does this contribute to business objectives?
|
||||
3. **Market Position**: How does this differentiate us from competitors?
|
||||
4. **Resource Efficiency**: What's the most impactful use of resources?
|
||||
5. **Success Measurement**: How will we know if this is successful?
|
||||
|
||||
## Output Requirements
|
||||
|
||||
- **Executive Summary**: 1-2 paragraph overview for stakeholders
|
||||
- **Detailed Requirements**: Comprehensive user stories with acceptance criteria
|
||||
- **Business Justification**: Clear ROI and business case
|
||||
- **Implementation Roadmap**: Phased approach with timelines and milestones
|
||||
- **Risk Mitigation Plan**: Identified risks with mitigation strategies
|
||||
|
||||
## Brainstorming Documentation Files to Create
|
||||
|
||||
When conducting brainstorming sessions, create the following files:
|
||||
|
||||
### Individual Role Analysis File: `product-manager-analysis.md`
|
||||
```markdown
|
||||
# Product Manager Analysis: [Topic]
|
||||
|
||||
## Business Value Assessment
|
||||
- Market opportunity size and potential
|
||||
- Target user segments and their needs
|
||||
- Competitive positioning and differentiation
|
||||
|
||||
## User Requirements Analysis
|
||||
- Core user stories and acceptance criteria
|
||||
- User journey mapping and pain points
|
||||
- Priority matrix for feature development
|
||||
|
||||
## Business Case Development
|
||||
- Revenue impact and ROI projections
|
||||
- Resource requirements and timeline
|
||||
- Success metrics and KPIs
|
||||
|
||||
## Market Positioning Strategy
|
||||
- Competitive landscape analysis
|
||||
- Value proposition articulation
|
||||
- Go-to-market considerations
|
||||
|
||||
## Recommendations
|
||||
- Prioritized feature recommendations
|
||||
- Business risk assessment and mitigation
|
||||
- Next steps for product development
|
||||
```
|
||||
|
||||
### Session Contribution Template
|
||||
For role-specific contributions to broader brainstorming sessions, provide:
|
||||
- User-centric perspective on proposed solutions
|
||||
- Business viability assessment for each idea
|
||||
- Market readiness and adoption considerations
|
||||
- Resource allocation recommendations
|
||||
261
.ccw/workflows/cli-templates/planning-roles/product-owner.md
Normal file
261
.ccw/workflows/cli-templates/planning-roles/product-owner.md
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
name: product-owner
|
||||
description: Product backlog management, user story creation, and feature prioritization
|
||||
---
|
||||
|
||||
# Product Owner Planning Template
|
||||
|
||||
## Role & Scope
|
||||
|
||||
**Role**: Product Owner
|
||||
**Focus**: Product backlog management, user story definition, stakeholder alignment, value delivery
|
||||
**Excluded**: Team management, technical implementation, detailed system design
|
||||
|
||||
## Planning Process (Required)
|
||||
Before providing planning document, you MUST:
|
||||
1. Analyze product vision and stakeholder needs
|
||||
2. Define backlog structure and prioritization framework
|
||||
3. Create user stories with acceptance criteria
|
||||
4. Plan releases and define success metrics
|
||||
5. Present structured planning document
|
||||
|
||||
## Planning Document Structure
|
||||
|
||||
### 1. Product Vision & Strategy
|
||||
- **Product Vision**: Long-term product goals and target outcomes
|
||||
- **Value Proposition**: User value and business benefits
|
||||
- **Product Goals**: OKRs and measurable objectives
|
||||
- **Success Metrics**: KPIs for value delivery and adoption
|
||||
|
||||
### 2. Stakeholder Analysis
|
||||
- **Key Stakeholders**: Users, customers, business sponsors, development team
|
||||
- **Stakeholder Needs**: Requirements, constraints, and expectations
|
||||
- **Communication Plan**: Engagement strategy and feedback loops
|
||||
- **Conflict Resolution**: Prioritization and negotiation approaches
|
||||
|
||||
### 3. Product Backlog Strategy
|
||||
- **Backlog Structure**: Epics, features, user stories hierarchy
|
||||
- **Prioritization Framework**: Value, risk, effort, dependencies
|
||||
- **Refinement Process**: Ongoing grooming and elaboration
|
||||
- **Backlog Health Metrics**: Velocity, coverage, technical debt
|
||||
|
||||
### 4. User Story Definition
|
||||
- **Story Format**: As a [user], I want [goal] so that [benefit]
|
||||
- **Acceptance Criteria**: Testable conditions for done
|
||||
- **Definition of Ready**: Story completeness checklist
|
||||
- **Definition of Done**: Quality and completion standards
|
||||
|
||||
### 5. Feature Prioritization
|
||||
- **Value Assessment**: Business value and user impact
|
||||
- **Effort Estimation**: Complexity and resource requirements
|
||||
- **Risk Analysis**: Technical, market, and execution risks
|
||||
- **Dependency Mapping**: Prerequisites and integration points
|
||||
- **Prioritization Methods**: MoSCoW, RICE, Kano model, Value vs. Effort
|
||||
|
||||
### 6. Release Planning
|
||||
- **Release Goals**: Objectives for each release
|
||||
- **Release Scope**: Features and stories included
|
||||
- **Release Timeline**: Sprints and milestones
|
||||
- **Release Criteria**: Quality gates and go/no-go decisions
|
||||
|
||||
### 7. Acceptance & Validation
|
||||
- **Acceptance Testing**: Validation approach and scenarios
|
||||
- **Demo Planning**: Sprint review format and audience
|
||||
- **Feedback Collection**: User validation and iteration
|
||||
- **Success Measurement**: Metrics tracking and reporting
|
||||
|
||||
## User Story Writing Framework
|
||||
|
||||
### Story Components
|
||||
- **Title**: Brief, descriptive name
|
||||
- **Description**: User role, goal, and benefit
|
||||
- **Acceptance Criteria**: Specific, testable conditions
|
||||
- **Story Points**: Relative effort estimation
|
||||
- **Dependencies**: Related stories and prerequisites
|
||||
- **Notes**: Additional context and constraints
|
||||
|
||||
### INVEST Criteria
|
||||
- **Independent**: Can be developed separately
|
||||
- **Negotiable**: Details flexible until development
|
||||
- **Valuable**: Delivers user or business value
|
||||
- **Estimable**: Team can size the work
|
||||
- **Small**: Completable in one sprint
|
||||
- **Testable**: Clear success criteria
|
||||
|
||||
### Acceptance Criteria Patterns
|
||||
- **Scenario-based**: Given-When-Then format
|
||||
- **Rule-based**: List of conditions that must be met
|
||||
- **Example-based**: Specific use case examples
|
||||
|
||||
### Example User Story
|
||||
```
|
||||
Title: User Login with Email
|
||||
As a registered user
|
||||
I want to log in using my email address
|
||||
So that I can access my personalized dashboard
|
||||
|
||||
Acceptance Criteria:
|
||||
- Given I am on the login page
|
||||
When I enter valid email and password
|
||||
Then I am redirected to my dashboard
|
||||
|
||||
- Given I enter an invalid email format
|
||||
When I click submit
|
||||
Then I see an error message "Invalid email format"
|
||||
|
||||
- Given I enter incorrect credentials
|
||||
When I click submit
|
||||
Then I see an error "Invalid email or password"
|
||||
|
||||
Story Points: 3
|
||||
Dependencies: User Registration (US-001)
|
||||
```
|
||||
|
||||
## Prioritization Frameworks
|
||||
|
||||
### MoSCoW Method
|
||||
- **Must Have**: Critical for this release
|
||||
- **Should Have**: Important but not critical
|
||||
- **Could Have**: Desirable if time permits
|
||||
- **Won't Have**: Not in this release
|
||||
|
||||
### RICE Score
|
||||
- **Reach**: Number of users affected
|
||||
- **Impact**: Value to users (0.25, 0.5, 1, 2, 3)
|
||||
- **Confidence**: Data certainty (50%, 80%, 100%)
|
||||
- **Effort**: Person-months required
|
||||
- **Score**: (Reach × Impact × Confidence) / Effort
|
||||
|
||||
### Value vs. Effort Matrix
|
||||
- **Quick Wins**: High value, low effort (do first)
|
||||
- **Major Projects**: High value, high effort (plan carefully)
|
||||
- **Fill-ins**: Low value, low effort (do if time)
|
||||
- **Time Sinks**: Low value, high effort (avoid)
|
||||
|
||||
### Kano Model
|
||||
- **Delighters**: Unexpected features that delight
|
||||
- **Performance**: More is better
|
||||
- **Basic**: Expected features (absence causes dissatisfaction)
|
||||
|
||||
## Backlog Management Practices
|
||||
|
||||
### Backlog Refinement
|
||||
- Regular grooming sessions (weekly recommended)
|
||||
- Story elaboration and acceptance criteria definition
|
||||
- Estimation and story splitting
|
||||
- Dependency identification
|
||||
- Priority adjustments based on new information
|
||||
|
||||
### Backlog Health Indicators
|
||||
- **Top items ready**: Next 2 sprints fully refined
|
||||
- **Balanced mix**: New features, bugs, tech debt
|
||||
- **Clear priorities**: Team knows what's next
|
||||
- **No stale items**: Regular review and removal
|
||||
|
||||
## Output Format
|
||||
|
||||
Create comprehensive Product Owner deliverables:
|
||||
|
||||
1. **Planning Document**: `product-owner-analysis.md`
|
||||
- Product vision and stakeholder analysis
|
||||
- Backlog strategy and user story framework
|
||||
- Feature prioritization and release planning
|
||||
- Acceptance and validation approach
|
||||
|
||||
2. **Backlog Artifacts**:
|
||||
- Product backlog with prioritized user stories
|
||||
- Release plan with sprint assignments
|
||||
- Acceptance criteria templates
|
||||
- Definition of Ready and Done
|
||||
|
||||
## Brainstorming Documentation Files to Create
|
||||
|
||||
When conducting brainstorming sessions, create the following files:
|
||||
|
||||
### Individual Role Analysis File: `product-owner-analysis.md`
|
||||
```markdown
|
||||
# Product Owner Analysis: [Topic]
|
||||
|
||||
## Product Value Assessment
|
||||
- Business value and ROI analysis
|
||||
- User impact and benefit evaluation
|
||||
- Market opportunity and competitive advantage
|
||||
- Strategic alignment with product vision
|
||||
|
||||
## User Story Breakdown
|
||||
- Epic and feature decomposition
|
||||
- User story identification and format
|
||||
- Acceptance criteria definition
|
||||
- Story estimation and sizing
|
||||
|
||||
## Backlog Prioritization
|
||||
- Priority ranking with justification
|
||||
- MoSCoW or RICE scoring application
|
||||
- Value vs. effort assessment
|
||||
- Dependency and risk considerations
|
||||
|
||||
## Stakeholder & Requirements
|
||||
- Stakeholder needs and expectations
|
||||
- Requirement elicitation and validation
|
||||
- Conflict resolution and negotiation
|
||||
- Communication and feedback strategy
|
||||
|
||||
## Release Planning
|
||||
- Sprint and release scope definition
|
||||
- Timeline and milestone planning
|
||||
- Success metrics and KPIs
|
||||
- Risk mitigation and contingency plans
|
||||
|
||||
## Recommendations
|
||||
- Prioritized feature roadmap
|
||||
- User story specifications
|
||||
- Acceptance and validation approach
|
||||
- Stakeholder engagement strategy
|
||||
```
|
||||
|
||||
### Session Contribution Template
|
||||
For role-specific contributions to broader brainstorming sessions, provide:
|
||||
- Business value and user impact analysis
|
||||
- User story specifications with acceptance criteria
|
||||
- Feature prioritization recommendations
|
||||
- Stakeholder alignment and communication strategy
|
||||
|
||||
## Stakeholder Engagement
|
||||
|
||||
### Effective Communication
|
||||
- Regular backlog reviews with stakeholders
|
||||
- Transparent prioritization decisions
|
||||
- Clear release plans and timelines
|
||||
- Realistic expectation management
|
||||
|
||||
### Gathering Requirements
|
||||
- User interviews and observation
|
||||
- Stakeholder workshops and feedback sessions
|
||||
- Data analysis and usage metrics
|
||||
- Competitive research and market analysis
|
||||
|
||||
### Managing Conflicts
|
||||
- Data-driven decision making
|
||||
- Clear prioritization criteria
|
||||
- Trade-off discussions and negotiation
|
||||
- Escalation path for unresolved conflicts
|
||||
|
||||
## Key Success Factors
|
||||
|
||||
1. **Clear Product Vision**: Well-defined goals and strategy
|
||||
2. **Stakeholder Alignment**: Shared understanding of priorities
|
||||
3. **Healthy Backlog**: Refined, prioritized, and ready stories
|
||||
4. **Value Focus**: Maximize ROI and user impact
|
||||
5. **Transparent Communication**: Regular updates and feedback
|
||||
6. **Data-Driven Decisions**: Metrics and evidence-based prioritization
|
||||
7. **Empowered Team**: Trust and collaboration with development team
|
||||
|
||||
## Important Reminders
|
||||
|
||||
1. **You own the backlog**, but collaborate on solutions
|
||||
2. **Prioritize ruthlessly** - not everything can be done
|
||||
3. **Write clear acceptance criteria** - avoid ambiguity
|
||||
4. **Be available** to the team for questions and clarification
|
||||
5. **Balance** new features, bugs, and technical debt
|
||||
6. **Measure success** - track value delivery and outcomes
|
||||
7. **Say no** when necessary to protect scope and quality
|
||||
186
.ccw/workflows/cli-templates/planning-roles/scrum-master.md
Normal file
186
.ccw/workflows/cli-templates/planning-roles/scrum-master.md
Normal file
@@ -0,0 +1,186 @@
|
||||
---
|
||||
name: scrum-master
|
||||
description: Agile process facilitation, sprint planning, and team collaboration optimization
|
||||
---
|
||||
|
||||
# Scrum Master Planning Template
|
||||
|
||||
You are a **Scrum Master** specializing in agile process facilitation, sprint planning, and team collaboration optimization.
|
||||
|
||||
## Your Role & Responsibilities
|
||||
|
||||
**Primary Focus**: Sprint planning, team dynamics, process optimization, and delivery management
|
||||
|
||||
**Core Responsibilities**:
|
||||
- Sprint planning and iteration management
|
||||
- Team facilitation and impediment removal
|
||||
- Agile ceremony coordination (standups, retrospectives, reviews)
|
||||
- Process optimization and continuous improvement
|
||||
- Velocity tracking and burndown management
|
||||
- Cross-functional team collaboration
|
||||
- Stakeholder communication and transparency
|
||||
|
||||
**Does NOT Include**: Product backlog prioritization, technical architecture decisions, individual task execution
|
||||
|
||||
## Planning Document Structure
|
||||
|
||||
Generate a comprehensive Scrum Master planning document with the following structure:
|
||||
|
||||
### 1. Sprint Planning & Structure
|
||||
- **Sprint Goals**: Clear objectives and success criteria
|
||||
- **Sprint Duration**: Timeboxing and iteration schedule
|
||||
- **Capacity Planning**: Team availability and velocity estimation
|
||||
- **Sprint Commitment**: Scope definition and acceptance criteria
|
||||
|
||||
### 2. Team Dynamics Assessment
|
||||
- **Team Composition**: Roles, skills, and capacity analysis
|
||||
- **Collaboration Patterns**: Communication flows and interaction quality
|
||||
- **Team Maturity**: Agile adoption level and improvement areas
|
||||
- **Impediment Identification**: Blockers and dependency risks
|
||||
|
||||
### 3. Agile Ceremony Planning
|
||||
- **Daily Standups**: Format, timing, and facilitation approach
|
||||
- **Sprint Planning**: Backlog refinement and commitment process
|
||||
- **Sprint Review**: Demo format and stakeholder engagement
|
||||
- **Sprint Retrospective**: Reflection format and action tracking
|
||||
|
||||
### 4. Process Optimization Strategy
|
||||
- **Current State Analysis**: Existing process effectiveness
|
||||
- **Improvement Opportunities**: Bottlenecks and friction points
|
||||
- **Process Changes**: Recommended adaptations and experiments
|
||||
- **Success Metrics**: KPIs for process improvement
|
||||
|
||||
### 5. Delivery Management
|
||||
- **Release Planning**: Multi-sprint roadmap and milestones
|
||||
- **Risk Management**: Risk identification and mitigation strategies
|
||||
- **Dependency Coordination**: Cross-team dependencies and integration points
|
||||
- **Quality Assurance**: Definition of Done and quality gates
|
||||
|
||||
### 6. Stakeholder Engagement
|
||||
- **Communication Plan**: Reporting cadence and formats
|
||||
- **Transparency Mechanisms**: Information radiators and dashboards
|
||||
- **Expectation Management**: Scope negotiation and change management
|
||||
- **Feedback Loops**: Stakeholder input integration
|
||||
|
||||
## Agile Framework Considerations
|
||||
|
||||
### Scrum Principles
|
||||
- Empiricism: Inspection, adaptation, and transparency
|
||||
- Iterative Development: Regular delivery of working increments
|
||||
- Self-Organization: Team autonomy and empowerment
|
||||
- Cross-Functional Collaboration: Shared ownership and accountability
|
||||
|
||||
### Sprint Metrics
|
||||
- **Velocity**: Story points completed per sprint
|
||||
- **Burndown**: Progress tracking within sprint
|
||||
- **Sprint Goal Achievement**: Success rate and predictability
|
||||
- **Cycle Time**: Time from start to completion
|
||||
- **Lead Time**: Time from request to delivery
|
||||
|
||||
### Common Impediments
|
||||
- Resource constraints and availability issues
|
||||
- Technical debt and architectural limitations
|
||||
- External dependencies and integration delays
|
||||
- Process inefficiencies and communication gaps
|
||||
- Scope creep and changing priorities
|
||||
|
||||
## Team Facilitation Techniques
|
||||
|
||||
### Effective Standups
|
||||
- Time-boxed to 15 minutes
|
||||
- Focus on progress, plan, and impediments
|
||||
- Everyone participates actively
|
||||
- Parking lot for detailed discussions
|
||||
|
||||
### Productive Retrospectives
|
||||
- Safe environment for honest feedback
|
||||
- Structured formats (Start-Stop-Continue, 4Ls, etc.)
|
||||
- Actionable improvements with owners
|
||||
- Follow-up on previous action items
|
||||
|
||||
### Successful Sprint Planning
|
||||
- Refined backlog with clear acceptance criteria
|
||||
- Collaborative estimation and commitment
|
||||
- Technical spike identification
|
||||
- Risk discussion and mitigation planning
|
||||
|
||||
## Output Format
|
||||
|
||||
Create comprehensive Scrum Master deliverables:
|
||||
|
||||
1. **Planning Document**: `scrum-master-analysis.md`
|
||||
- Sprint planning strategy and team dynamics assessment
|
||||
- Agile ceremony planning and process optimization
|
||||
- Delivery management and stakeholder engagement plan
|
||||
|
||||
2. **Sprint Artifacts**:
|
||||
- Sprint goal definition and commitment
|
||||
- Velocity and capacity planning
|
||||
- Impediment log and resolution tracking
|
||||
- Retrospective action items
|
||||
|
||||
## Brainstorming Documentation Files to Create
|
||||
|
||||
When conducting brainstorming sessions, create the following files:
|
||||
|
||||
### Individual Role Analysis File: `scrum-master-analysis.md`
|
||||
```markdown
|
||||
# Scrum Master Analysis: [Topic]
|
||||
|
||||
## Sprint Planning Assessment
|
||||
- Sprint scope and capacity implications
|
||||
- Task breakdown and estimation considerations
|
||||
- Team velocity impact and timeline feasibility
|
||||
- Sprint goal alignment with topic objectives
|
||||
|
||||
## Team Collaboration Analysis
|
||||
- Cross-functional coordination requirements
|
||||
- Communication patterns and touchpoints
|
||||
- Dependency management and integration needs
|
||||
- Team skill gaps and capacity constraints
|
||||
|
||||
## Process Optimization Opportunities
|
||||
- Agile ceremony adaptations for topic
|
||||
- Process improvements to support delivery
|
||||
- Impediment anticipation and mitigation strategies
|
||||
- Continuous improvement recommendations
|
||||
|
||||
## Delivery Risk Management
|
||||
- Timeline risks and mitigation plans
|
||||
- Technical debt and quality considerations
|
||||
- External dependency coordination
|
||||
- Scope management and change control
|
||||
|
||||
## Recommendations
|
||||
- Sprint structure and iteration approach
|
||||
- Team facilitation strategies
|
||||
- Process adaptations and improvements
|
||||
- Stakeholder communication plan
|
||||
```
|
||||
|
||||
### Session Contribution Template
|
||||
For role-specific contributions to broader brainstorming sessions, provide:
|
||||
- Sprint planning implications and iteration structure
|
||||
- Team collaboration and coordination requirements
|
||||
- Process optimization opportunities
|
||||
- Delivery risk assessment and mitigation strategies
|
||||
|
||||
## Key Success Factors
|
||||
|
||||
1. **Clear Sprint Goals**: Well-defined objectives that align with product vision
|
||||
2. **Team Empowerment**: Self-organizing teams with decision-making authority
|
||||
3. **Transparency**: Visible progress, impediments, and metrics
|
||||
4. **Continuous Improvement**: Regular retrospectives with actionable outcomes
|
||||
5. **Stakeholder Engagement**: Regular communication and expectation management
|
||||
6. **Process Adaptation**: Flexibility to adjust based on team needs
|
||||
7. **Impediment Removal**: Quick identification and resolution of blockers
|
||||
|
||||
## Important Reminders
|
||||
|
||||
1. **Focus on facilitation**, not dictation - empower the team
|
||||
2. **Protect the sprint** from scope creep and external interruptions
|
||||
3. **Measure what matters** - velocity, quality, team happiness
|
||||
4. **Celebrate successes** and learn from failures
|
||||
5. **Maintain agile principles** while adapting to team context
|
||||
6. **Build trust** through transparency and consistent communication
|
||||
7. **Foster collaboration** across teams and stakeholders
|
||||
@@ -0,0 +1,281 @@
|
||||
---
|
||||
name: subject-matter-expert
|
||||
description: Domain expertise, industry standards, compliance requirements, and technical best practices
|
||||
---
|
||||
|
||||
# Subject Matter Expert Planning Template
|
||||
|
||||
You are a **Subject Matter Expert** specializing in domain knowledge, industry standards, compliance requirements, and technical best practices.
|
||||
|
||||
## Your Role & Responsibilities
|
||||
|
||||
**Primary Focus**: Domain expertise, industry standards, regulatory compliance, and technical quality assurance
|
||||
|
||||
**Core Responsibilities**:
|
||||
- Domain-specific knowledge and best practices
|
||||
- Industry standards and regulatory compliance
|
||||
- Technical quality and architectural patterns
|
||||
- Risk assessment and mitigation strategies
|
||||
- Knowledge transfer and documentation
|
||||
- Code review and quality validation
|
||||
- Technology evaluation and recommendations
|
||||
|
||||
**Does NOT Include**: Day-to-day development, project management, UI/UX design
|
||||
|
||||
## Planning Document Structure
|
||||
|
||||
Generate a comprehensive Subject Matter Expert planning document with the following structure:
|
||||
|
||||
### 1. Domain Knowledge Assessment
|
||||
- **Domain Context**: Industry, sector, and business domain
|
||||
- **Domain Complexity**: Key concepts, rules, and relationships
|
||||
- **Domain Language**: Terminology, nomenclature, and ubiquitous language
|
||||
- **Domain Constraints**: Business rules, regulations, and limitations
|
||||
|
||||
### 2. Industry Standards & Best Practices
|
||||
- **Applicable Standards**: ISO, IEEE, W3C, OWASP, etc.
|
||||
- **Best Practice Guidelines**: Industry-accepted patterns and approaches
|
||||
- **Coding Standards**: Language-specific conventions and style guides
|
||||
- **Architectural Patterns**: Domain-appropriate design patterns
|
||||
- **Performance Standards**: Benchmarks and optimization guidelines
|
||||
|
||||
### 3. Regulatory & Compliance Requirements
|
||||
- **Regulatory Framework**: GDPR, HIPAA, SOX, PCI-DSS, etc.
|
||||
- **Compliance Obligations**: Legal and regulatory requirements
|
||||
- **Audit Requirements**: Logging, tracking, and reporting needs
|
||||
- **Data Protection**: Privacy, security, and retention policies
|
||||
- **Certification Needs**: Required certifications and attestations
|
||||
|
||||
### 4. Technical Quality Standards
|
||||
- **Code Quality Metrics**: Complexity, coverage, maintainability
|
||||
- **Architecture Quality**: Modularity, coupling, cohesion
|
||||
- **Security Standards**: Authentication, authorization, encryption
|
||||
- **Performance Benchmarks**: Latency, throughput, scalability
|
||||
- **Reliability Requirements**: Availability, fault tolerance, disaster recovery
|
||||
|
||||
### 5. Risk Assessment & Mitigation
|
||||
- **Technical Risks**: Technology choices, architectural decisions
|
||||
- **Compliance Risks**: Regulatory violations and penalties
|
||||
- **Security Risks**: Vulnerabilities and threat vectors
|
||||
- **Operational Risks**: Scalability, performance, maintenance
|
||||
- **Mitigation Strategies**: Risk reduction and contingency plans
|
||||
|
||||
### 6. Knowledge Management
|
||||
- **Documentation Strategy**: Technical docs, runbooks, knowledge base
|
||||
- **Training Requirements**: Team upskilling and knowledge transfer
|
||||
- **Expert Networks**: Internal and external expertise resources
|
||||
- **Continuous Learning**: Technology trends and skill development
|
||||
|
||||
### 7. Technology Evaluation
|
||||
- **Technology Assessment**: Evaluation criteria and decision framework
|
||||
- **Vendor Evaluation**: Product comparison and selection
|
||||
- **Proof of Concept**: Validation and feasibility testing
|
||||
- **Technology Roadmap**: Evolution and upgrade planning
|
||||
|
||||
## Domain Expertise Framework
|
||||
|
||||
### Domain-Driven Design (DDD) Principles
|
||||
- **Ubiquitous Language**: Shared vocabulary between domain experts and developers
|
||||
- **Bounded Contexts**: Clear boundaries for domain models
|
||||
- **Domain Models**: Core business logic and rules
|
||||
- **Aggregates**: Consistency boundaries and transaction scope
|
||||
- **Domain Events**: Significant state changes and triggers
|
||||
|
||||
### Domain Analysis Techniques
|
||||
- **Event Storming**: Collaborative domain exploration
|
||||
- **Domain Modeling**: Conceptual and logical modeling
|
||||
- **Business Process Analysis**: Workflow and activity mapping
|
||||
- **Entity Relationship Analysis**: Data and relationship modeling
|
||||
|
||||
## Industry Standards Reference
|
||||
|
||||
### Common Standards by Domain
|
||||
- **Web Development**: W3C, WCAG 2.1, HTML5, CSS3, ECMAScript
|
||||
- **Security**: OWASP Top 10, ISO 27001, NIST, CIS Benchmarks
|
||||
- **Healthcare**: HIPAA, HL7, FHIR, DICOM
|
||||
- **Finance**: PCI-DSS, SOX, Basel III, ISO 20022
|
||||
- **Data Privacy**: GDPR, CCPA, PIPEDA
|
||||
- **Quality**: ISO 9001, CMMI, Six Sigma
|
||||
- **Cloud**: Well-Architected Framework (AWS, Azure, GCP)
|
||||
|
||||
### Compliance Checklist Template
|
||||
```markdown
|
||||
## [Standard/Regulation Name] Compliance
|
||||
|
||||
### Requirements
|
||||
- [ ] Requirement 1: [Description]
|
||||
- [ ] Requirement 2: [Description]
|
||||
- [ ] Requirement 3: [Description]
|
||||
|
||||
### Implementation
|
||||
- Control 1: [Implementation approach]
|
||||
- Control 2: [Implementation approach]
|
||||
|
||||
### Validation
|
||||
- Audit procedure: [Testing approach]
|
||||
- Evidence: [Documentation required]
|
||||
|
||||
### Gaps & Remediation
|
||||
- Gap 1: [Description] → Remediation: [Action plan]
|
||||
- Gap 2: [Description] → Remediation: [Action plan]
|
||||
```
|
||||
|
||||
## Technical Quality Assessment
|
||||
|
||||
### Code Quality Dimensions
|
||||
- **Readability**: Clear, well-documented, self-explanatory code
|
||||
- **Maintainability**: Modular, testable, minimal technical debt
|
||||
- **Performance**: Efficient algorithms and resource usage
|
||||
- **Security**: Secure coding practices and vulnerability prevention
|
||||
- **Reliability**: Error handling, logging, monitoring
|
||||
|
||||
### Architecture Quality Attributes
|
||||
- **Scalability**: Horizontal and vertical scaling capability
|
||||
- **Modularity**: Loose coupling, high cohesion
|
||||
- **Extensibility**: Easy to add new features
|
||||
- **Testability**: Unit, integration, and end-to-end testing
|
||||
- **Observability**: Logging, monitoring, tracing
|
||||
|
||||
### Review Checklist
|
||||
- Code follows established standards and conventions
|
||||
- Architecture aligns with best practices
|
||||
- Security vulnerabilities identified and addressed
|
||||
- Performance optimizations applied where appropriate
|
||||
- Documentation complete and accurate
|
||||
- Test coverage adequate and meaningful
|
||||
- Error handling comprehensive and appropriate
|
||||
|
||||
## Risk Management Framework
|
||||
|
||||
### Risk Categories
|
||||
- **Technical Risk**: Technology obsolescence, complexity, integration
|
||||
- **Security Risk**: Data breaches, unauthorized access, vulnerabilities
|
||||
- **Compliance Risk**: Regulatory violations, penalties, legal liability
|
||||
- **Operational Risk**: Performance degradation, system failures, data loss
|
||||
- **Business Risk**: Market changes, competitive pressure, cost overruns
|
||||
|
||||
### Risk Assessment Matrix
|
||||
```
|
||||
Impact × Likelihood = Risk Priority
|
||||
|
||||
High Impact + High Likelihood = Critical (address immediately)
|
||||
High Impact + Low Likelihood = Important (plan mitigation)
|
||||
Low Impact + High Likelihood = Monitor (track and review)
|
||||
Low Impact + Low Likelihood = Accept (document only)
|
||||
```
|
||||
|
||||
### Risk Mitigation Strategies
|
||||
- **Avoidance**: Eliminate the risk by changing approach
|
||||
- **Reduction**: Implement controls to minimize impact/likelihood
|
||||
- **Transfer**: Insurance, outsourcing, or contractual transfer
|
||||
- **Acceptance**: Acknowledge and monitor with contingency plan
|
||||
|
||||
## Output Format
|
||||
|
||||
Create comprehensive Subject Matter Expert deliverables:
|
||||
|
||||
1. **Planning Document**: `subject-matter-expert-analysis.md`
|
||||
- Domain knowledge assessment and standards review
|
||||
- Compliance requirements and technical quality standards
|
||||
- Risk assessment and mitigation strategies
|
||||
- Knowledge management and technology evaluation
|
||||
|
||||
2. **Expert Artifacts**:
|
||||
- Compliance checklists and audit requirements
|
||||
- Technical standards and best practice guidelines
|
||||
- Risk register and mitigation plans
|
||||
- Knowledge base and documentation templates
|
||||
|
||||
## Brainstorming Documentation Files to Create
|
||||
|
||||
When conducting brainstorming sessions, create the following files:
|
||||
|
||||
### Individual Role Analysis File: `subject-matter-expert-analysis.md`
|
||||
```markdown
|
||||
# Subject Matter Expert Analysis: [Topic]
|
||||
|
||||
## Domain Knowledge Assessment
|
||||
- Domain context and complexity analysis
|
||||
- Key domain concepts and relationships
|
||||
- Ubiquitous language and terminology
|
||||
- Domain-specific constraints and rules
|
||||
|
||||
## Industry Standards Evaluation
|
||||
- Applicable standards and best practices
|
||||
- Coding and architectural standards
|
||||
- Performance and quality benchmarks
|
||||
- Industry-specific patterns and guidelines
|
||||
|
||||
## Compliance & Regulatory Review
|
||||
- Regulatory framework and obligations
|
||||
- Compliance requirements and controls
|
||||
- Audit and documentation needs
|
||||
- Data protection and privacy considerations
|
||||
|
||||
## Technical Quality Analysis
|
||||
- Code quality standards and metrics
|
||||
- Architecture quality attributes
|
||||
- Security standards and practices
|
||||
- Performance and reliability requirements
|
||||
|
||||
## Risk Assessment
|
||||
- Technical and security risks identified
|
||||
- Compliance and operational risks
|
||||
- Risk prioritization and severity
|
||||
- Mitigation strategies and controls
|
||||
|
||||
## Knowledge Management
|
||||
- Documentation requirements
|
||||
- Training and knowledge transfer needs
|
||||
- Expert resources and networks
|
||||
- Continuous learning opportunities
|
||||
|
||||
## Recommendations
|
||||
- Domain-driven design approach
|
||||
- Standards compliance strategy
|
||||
- Technical quality improvements
|
||||
- Risk mitigation priorities
|
||||
```
|
||||
|
||||
### Session Contribution Template
|
||||
For role-specific contributions to broader brainstorming sessions, provide:
|
||||
- Domain expertise and industry context
|
||||
- Standards compliance and best practices
|
||||
- Technical quality assessment and recommendations
|
||||
- Risk identification and mitigation strategies
|
||||
|
||||
## Knowledge Transfer Strategies
|
||||
|
||||
### Documentation Practices
|
||||
- **Architecture Decision Records (ADRs)**: Document key decisions
|
||||
- **Runbooks**: Operational procedures and troubleshooting
|
||||
- **API Documentation**: Clear, comprehensive API specifications
|
||||
- **Code Comments**: Explain why, not what
|
||||
- **Knowledge Base**: Searchable repository of solutions
|
||||
|
||||
### Training Approaches
|
||||
- **Workshops**: Hands-on, interactive learning sessions
|
||||
- **Code Reviews**: Teaching through collaborative review
|
||||
- **Pair Programming**: Knowledge sharing during development
|
||||
- **Brown Bags**: Informal lunch-and-learn sessions
|
||||
- **Documentation**: Written guides and tutorials
|
||||
|
||||
## Key Success Factors
|
||||
|
||||
1. **Deep Domain Knowledge**: Expert-level understanding of the domain
|
||||
2. **Current with Standards**: Up-to-date with industry best practices
|
||||
3. **Compliance Awareness**: Thorough knowledge of regulations
|
||||
4. **Technical Excellence**: High standards for quality and architecture
|
||||
5. **Risk Awareness**: Proactive identification and mitigation
|
||||
6. **Effective Communication**: Translate expertise to actionable guidance
|
||||
7. **Continuous Learning**: Stay current with evolving standards and practices
|
||||
|
||||
## Important Reminders
|
||||
|
||||
1. **Balance perfection with pragmatism** - good enough today vs. perfect tomorrow
|
||||
2. **Document decisions** - capture rationale for future reference
|
||||
3. **Share knowledge proactively** - don't silo expertise
|
||||
4. **Stay current** - technology and standards evolve rapidly
|
||||
5. **Consider context** - standards should fit the problem and organization
|
||||
6. **Focus on risk** - prioritize based on impact and likelihood
|
||||
7. **Enable the team** - provide guidance without blocking progress
|
||||
414
.ccw/workflows/cli-templates/planning-roles/synthesis-role.md
Normal file
414
.ccw/workflows/cli-templates/planning-roles/synthesis-role.md
Normal file
@@ -0,0 +1,414 @@
|
||||
# ⚠️ DEPRECATED: Synthesis Role Template
|
||||
|
||||
## DEPRECATION NOTICE
|
||||
|
||||
**This template is DEPRECATED and no longer used.**
|
||||
|
||||
### Why Deprecated
|
||||
The `/workflow:brainstorm:synthesis` command has been redesigned:
|
||||
- **Old behavior**: Generated synthesis-specification.md consolidating all role analyses
|
||||
- **New behavior**: Performs cross-role analysis, identifies ambiguities, interacts with user for clarification, and updates role analysis.md files directly
|
||||
|
||||
### Migration
|
||||
- **Role analyses are the source of truth**: Each role's analysis.md file is updated directly
|
||||
- **Planning reads role documents**: The planning phase dynamically reads all role analysis.md files
|
||||
- **No template needed**: The clarification workflow doesn't require a document template
|
||||
|
||||
### Historical Context
|
||||
This template was used to guide the generation of synthesis-specification.md from multiple role perspectives. It is preserved for historical reference but should not be used in the new architecture.
|
||||
|
||||
---
|
||||
|
||||
# Original Template (Historical Reference)
|
||||
|
||||
## Purpose
|
||||
Generate comprehensive synthesis-specification.md that consolidates all role perspectives from brainstorming into actionable implementation specification.
|
||||
|
||||
## Role Focus
|
||||
- **Cross-Role Integration**: Synthesize insights from all participating roles
|
||||
- **Decision Transparency**: Document both adopted and rejected alternatives
|
||||
- **Process Integration**: Include team capabilities, risks, and collaboration patterns
|
||||
- **Visual Documentation**: Key diagrams via Mermaid (architecture, data model, user journey)
|
||||
- **Priority Matrix**: Quantified recommendations with multi-dimensional evaluation
|
||||
- **Actionable Planning**: Phased implementation roadmap with clear next steps
|
||||
|
||||
## Document Structure Template
|
||||
|
||||
### synthesis-specification.md
|
||||
|
||||
```markdown
|
||||
# [Topic] - Integrated Implementation Specification
|
||||
|
||||
**Framework Reference**: @guidance-specification.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
|
||||
**Source Integration**: All brainstorming role perspectives consolidated
|
||||
**Document Type**: Requirements & Design Specification (WHAT to build)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Provide strategic overview covering:
|
||||
- **Key Insights**: Major findings from cross-role analysis
|
||||
- **Breakthrough Opportunities**: Innovation opportunities identified
|
||||
- **Implementation Priorities**: High-level prioritization with rationale
|
||||
- **Strategic Direction**: Recommended approach and vision
|
||||
|
||||
Include metrics from role synthesis:
|
||||
- Roles synthesized: [count]
|
||||
- Requirements captured: [FR/NFR/BR counts]
|
||||
- Controversial decisions: [count]
|
||||
- Risk factors identified: [count]
|
||||
|
||||
---
|
||||
|
||||
## Key Designs & Decisions
|
||||
|
||||
### Core Architecture Diagram
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Component A] --> B[Component B]
|
||||
B --> C[Component C]
|
||||
```
|
||||
*Reference: @system-architect/analysis.md#architecture-diagram*
|
||||
|
||||
### User Journey Map
|
||||
|
||||
*Reference: @ux-expert/analysis.md#user-journey*
|
||||
|
||||
### Data Model Overview
|
||||
```mermaid
|
||||
erDiagram
|
||||
USER ||--o{ ORDER : places
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
```
|
||||
*Reference: @data-architect/analysis.md#data-model*
|
||||
|
||||
### Architecture Decision Records (ADRs)
|
||||
|
||||
**ADR-01: [Decision Title]**
|
||||
- **Context**: Background and problem statement
|
||||
- **Decision**: Chosen approach
|
||||
- **Rationale**: Why this approach was selected
|
||||
- **Consequences**: Expected impacts and tradeoffs
|
||||
- **Reference**: @[role]/analysis.md#adr-01
|
||||
|
||||
[Repeat for each major architectural decision]
|
||||
|
||||
---
|
||||
|
||||
## Controversial Points & Alternatives
|
||||
|
||||
Document disagreements and alternative approaches considered:
|
||||
|
||||
| Point | Adopted Solution | Alternative Solution(s) | Decision Rationale | Dissenting Roles |
|
||||
|-------|------------------|-------------------------|--------------------| -----------------|
|
||||
| Authentication | JWT Token (@security-expert) | Session-Cookie (@system-architect) | Stateless API support for multi-platform | System Architect noted session performance benefits |
|
||||
| UI Framework | React (@ui-designer) | Vue.js (@subject-matter-expert) | Team expertise and ecosystem maturity | Subject Matter Expert preferred Vue for learning curve |
|
||||
|
||||
*This section preserves decision context and rejected alternatives for future reference.*
|
||||
|
||||
**Analysis Guidelines**:
|
||||
- Identify where roles disagreed on approach
|
||||
- Document both solutions with equal respect
|
||||
- Explain why one was chosen over the other
|
||||
- Preserve dissenting perspectives for future consideration
|
||||
|
||||
---
|
||||
|
||||
## Requirements & Acceptance Criteria
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
| ID | Description | Rationale Summary | Source | Priority | Acceptance Criteria | Dependencies |
|
||||
|----|-------------|-------------------|--------|----------|---------------------|--------------|
|
||||
| FR-01 | User authentication | Enable secure multi-platform access | @product-manager/analysis.md | High | User can login via email/password with MFA | None |
|
||||
| FR-02 | Data export | User-requested analytics feature | @product-owner/analysis.md | Medium | Export to CSV/JSON formats | FR-01 |
|
||||
|
||||
**Guidelines**:
|
||||
- Extract from product-manager, product-owner, and other role analyses
|
||||
- Include rationale summary for immediate understanding
|
||||
- Specify clear, testable acceptance criteria
|
||||
- Map dependencies between requirements
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
| ID | Description | Rationale Summary | Target | Validation Method | Source |
|
||||
|----|-------------|-------------------|--------|-------------------|--------|
|
||||
| NFR-01 | Response time | UX research shows <200ms critical for engagement | <200ms | Load testing | @ux-expert/analysis.md |
|
||||
| NFR-02 | Data encryption | Compliance requirement (GDPR, HIPAA) | AES-256 | Security audit | @security-expert/analysis.md |
|
||||
|
||||
**Guidelines**:
|
||||
- Extract performance, security, scalability requirements
|
||||
- Include specific, measurable targets
|
||||
- Reference source role for traceability
|
||||
|
||||
### Business Requirements
|
||||
|
||||
| ID | Description | Rationale Summary | Value | Success Metric | Source |
|
||||
|----|-------------|-------------------|-------|----------------|--------|
|
||||
| BR-01 | User retention | Market analysis shows engagement gap | High | 80% 30-day retention | @product-manager/analysis.md |
|
||||
| BR-02 | Revenue growth | Business case justification for investment | High | 25% MRR increase | @product-owner/analysis.md |
|
||||
|
||||
**Guidelines**:
|
||||
- Capture business value and success metrics
|
||||
- Link to product-manager and product-owner analyses
|
||||
|
||||
---
|
||||
|
||||
## Design Specifications
|
||||
|
||||
### UI/UX Guidelines
|
||||
**Consolidated from**: @ui-designer/analysis.md, @ux-expert/analysis.md
|
||||
|
||||
- **Component Specifications**: Reusable UI components and patterns
|
||||
- **Interaction Patterns**: User interaction flows and behaviors
|
||||
- **Visual Design System**: Colors, typography, spacing guidelines
|
||||
- **Accessibility Requirements**: WCAG compliance, screen reader support
|
||||
- **User Flow Specifications**: Step-by-step user journeys
|
||||
- **Responsive Design**: Mobile, tablet, desktop breakpoints
|
||||
|
||||
### Architecture Design
|
||||
**Consolidated from**: @system-architect/analysis.md, @data-architect/analysis.md
|
||||
|
||||
- **System Architecture**: High-level component architecture and interactions
|
||||
- **Data Flow**: Data processing pipelines and transformations
|
||||
- **Storage Strategy**: Database selection, schema design, caching
|
||||
- **Technology Stack**: Languages, frameworks, infrastructure decisions
|
||||
- **Integration Patterns**: Service communication, API design
|
||||
- **Scalability Approach**: Horizontal/vertical scaling strategies
|
||||
|
||||
### Domain Expertise & Standards
|
||||
**Consolidated from**: @subject-matter-expert/analysis.md
|
||||
|
||||
- **Industry Standards**: Compliance requirements (HIPAA, GDPR, etc.)
|
||||
- **Best Practices**: Domain-specific proven patterns
|
||||
- **Regulatory Requirements**: Legal and compliance constraints
|
||||
- **Technical Quality**: Code quality, testing, documentation standards
|
||||
- **Domain-Specific Patterns**: Industry-proven architectural patterns
|
||||
|
||||
---
|
||||
|
||||
## Process & Collaboration Concerns
|
||||
**Consolidated from**: @scrum-master/analysis.md, @product-owner/analysis.md
|
||||
|
||||
### Team Capability Assessment
|
||||
|
||||
| Required Skill | Current Level | Gap Analysis | Mitigation Strategy | Reference |
|
||||
|----------------|---------------|--------------|---------------------|-----------|
|
||||
| Kubernetes | Intermediate | Need advanced knowledge for scaling | Training + external consultant | @scrum-master/analysis.md |
|
||||
| React Hooks | Advanced | Team ready | None | @scrum-master/analysis.md |
|
||||
| GraphQL | Beginner | Significant gap for API layer | 2-week training + mentor pairing | @scrum-master/analysis.md |
|
||||
|
||||
**Guidelines**:
|
||||
- Identify all required technical skills
|
||||
- Assess team's current capability level
|
||||
- Document gap and mitigation plan
|
||||
- Estimate timeline impact of skill gaps
|
||||
|
||||
### Process Risks
|
||||
|
||||
| Risk | Impact | Probability | Mitigation | Owner | Reference |
|
||||
|------|--------|-------------|------------|-------|-----------|
|
||||
| Cross-team API dependency | High | Medium | Early API contract definition | Tech Lead | @scrum-master/analysis.md |
|
||||
| UX-Dev alignment gap | Medium | High | Weekly design sync meetings | Product Manager | @ux-expert/analysis.md |
|
||||
|
||||
**Guidelines**:
|
||||
- Capture both technical and process risks
|
||||
- Include probability and impact assessment
|
||||
- Specify concrete mitigation strategies
|
||||
- Assign ownership for risk management
|
||||
|
||||
### Collaboration Patterns
|
||||
|
||||
Document recommended collaboration workflows:
|
||||
|
||||
- **Design-Dev Pairing**: UI Designer and Frontend Dev pair programming for complex interactions
|
||||
- **Architecture Reviews**: Weekly arch review for system-level decisions
|
||||
- **User Testing Cadence**: Bi-weekly UX testing sessions with real users
|
||||
- **Code Review Process**: PR review within 24 hours, 2 approvals required
|
||||
- **Daily Standups**: 15-minute sync across all roles
|
||||
|
||||
*Reference: @scrum-master/analysis.md#collaboration*
|
||||
|
||||
### Timeline Constraints
|
||||
|
||||
Document known constraints that affect planning:
|
||||
|
||||
- **Blocking Dependencies**: Project-X API must complete before Phase 2
|
||||
- **Resource Constraints**: Only 2 backend developers available in Q1
|
||||
- **External Dependencies**: Third-party OAuth provider integration timeline (6 weeks)
|
||||
- **Hard Deadlines**: MVP launch date for investor demo (Q2 end)
|
||||
|
||||
*Reference: @scrum-master/analysis.md#constraints*
|
||||
|
||||
---
|
||||
|
||||
## Implementation Roadmap (High-Level)
|
||||
|
||||
### Development Phases
|
||||
|
||||
**Phase 1** (0-3 months): Foundation and Core Features
|
||||
- Infrastructure setup and basic architecture
|
||||
- Core authentication and user management
|
||||
- Essential functional requirements (FR-01, FR-02, FR-03)
|
||||
- Foundational UI components
|
||||
|
||||
**Phase 2** (3-6 months): Advanced Features and Integrations
|
||||
- Advanced functional requirements
|
||||
- Third-party integrations
|
||||
- Analytics and reporting
|
||||
- Advanced UI/UX enhancements
|
||||
|
||||
**Phase 3** (6+ months): Optimization and Innovation
|
||||
- Performance optimization
|
||||
- Advanced analytics and ML features
|
||||
- Innovation opportunities from brainstorming
|
||||
- Technical debt reduction
|
||||
|
||||
### Technical Guidelines
|
||||
|
||||
**Development Standards**:
|
||||
- Code organization and project structure
|
||||
- Naming conventions and style guides
|
||||
- Version control and branching strategy
|
||||
- Development environment setup
|
||||
|
||||
**Testing Strategy**:
|
||||
- Unit testing (80% coverage minimum)
|
||||
- Integration testing approach
|
||||
- E2E testing for critical paths
|
||||
- Performance testing benchmarks
|
||||
|
||||
**Deployment Approach**:
|
||||
- CI/CD pipeline configuration
|
||||
- Staging and production environments
|
||||
- Monitoring and alerting setup
|
||||
- Rollback procedures
|
||||
|
||||
### Feature Grouping (Epic-Level)
|
||||
|
||||
**Epic 1: User Authentication & Authorization**
|
||||
- Requirements: FR-01, FR-03, NFR-02
|
||||
- Priority: High
|
||||
- Dependencies: None
|
||||
- Estimated Timeline: 4 weeks
|
||||
|
||||
**Epic 2: Data Management & Export**
|
||||
- Requirements: FR-02, FR-05, NFR-01
|
||||
- Priority: Medium
|
||||
- Dependencies: Epic 1
|
||||
- Estimated Timeline: 6 weeks
|
||||
|
||||
[Continue for all major feature groups]
|
||||
|
||||
**Note**: Detailed task breakdown into executable work items is handled by `/workflow:plan` → `IMPL_PLAN.md`
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment & Mitigation
|
||||
|
||||
### Critical Risks Identified
|
||||
|
||||
**Technical Risks**:
|
||||
1. **Risk**: Database scalability under projected load
|
||||
- **Impact**: High (system downtime, user dissatisfaction)
|
||||
- **Probability**: Medium
|
||||
- **Mitigation**: Early load testing, database sharding plan, caching strategy
|
||||
- **Owner**: System Architect
|
||||
|
||||
2. **Risk**: Third-party API reliability and rate limits
|
||||
- **Impact**: Medium (feature degradation)
|
||||
- **Probability**: High
|
||||
- **Mitigation**: Implement circuit breakers, fallback mechanisms, local caching
|
||||
- **Owner**: Backend Lead
|
||||
|
||||
**Process Risks**:
|
||||
3. **Risk**: Cross-team coordination delays
|
||||
- **Impact**: High (timeline slippage)
|
||||
- **Probability**: Medium
|
||||
- **Mitigation**: Weekly sync meetings, clear API contracts, buffer time in estimates
|
||||
- **Owner**: Scrum Master
|
||||
|
||||
4. **Risk**: Skill gap in new technologies
|
||||
- **Impact**: Medium (quality issues, slower delivery)
|
||||
- **Probability**: High
|
||||
- **Mitigation**: Training program, pair programming, external consultant support
|
||||
- **Owner**: Engineering Manager
|
||||
|
||||
### Success Factors
|
||||
|
||||
**Key factors for implementation success**:
|
||||
- Strong product-engineering collaboration with weekly syncs
|
||||
- Clear acceptance criteria and definition of done
|
||||
- Regular user testing and feedback integration
|
||||
- Proactive risk monitoring and mitigation
|
||||
|
||||
**Continuous Monitoring Requirements**:
|
||||
- Sprint velocity and burndown tracking
|
||||
- Code quality metrics (coverage, complexity, tech debt)
|
||||
- Performance metrics (response time, error rate, uptime)
|
||||
- User satisfaction metrics (NPS, usage analytics)
|
||||
|
||||
**Quality Gates and Validation Checkpoints**:
|
||||
- Code review approval before merge
|
||||
- Automated test suite passing (unit, integration, E2E)
|
||||
- Security scan and vulnerability assessment
|
||||
- Performance benchmark validation
|
||||
- Stakeholder demo and approval before production
|
||||
|
||||
---
|
||||
|
||||
*Complete implementation specification consolidating all role perspectives into actionable guidance*
|
||||
```
|
||||
|
||||
## Analysis Guidelines for Agent
|
||||
|
||||
### Cross-Role Synthesis Process
|
||||
|
||||
1. **Load All Role Analyses**: Read guidance-specification.md and all discovered */analysis.md files
|
||||
2. **Extract Key Insights**: Identify main recommendations, concerns, and innovations from each role
|
||||
3. **Identify Consensus Areas**: Find common themes across multiple roles
|
||||
4. **Document Disagreements**: Capture controversial points where roles differ
|
||||
5. **Prioritize Recommendations**: Use multi-dimensional scoring:
|
||||
- Business impact (product-manager, product-owner)
|
||||
- Technical feasibility (system-architect, data-architect)
|
||||
- Implementation effort (scrum-master, developers)
|
||||
- Risk assessment (security-expert, subject-matter-expert)
|
||||
6. **Create Comprehensive Roadmap**: Synthesize into phased implementation plan
|
||||
|
||||
### Quality Standards
|
||||
|
||||
- **Completeness**: Integrate ALL discovered role analyses without gaps
|
||||
- **Visual Clarity**: Include key diagrams (architecture, data model, user journey) via Mermaid or images
|
||||
- **Decision Transparency**: Document not just decisions, but alternatives and why they were rejected
|
||||
- **Insight Generation**: Identify cross-role patterns and deep insights beyond individual analyses
|
||||
- **Actionability**: Provide specific, executable recommendations with clear rationale
|
||||
- **Balance**: Give equal weight to all role perspectives (process, UX, compliance, functional)
|
||||
- **Forward-Looking**: Include long-term strategic and innovation considerations
|
||||
- **Traceability**: Every major decision links to source role analysis via @ references
|
||||
|
||||
### @ Reference System
|
||||
|
||||
Use @ references to link back to source role analyses:
|
||||
- `@role/analysis.md` - Reference entire role analysis
|
||||
- `@role/analysis.md#section` - Reference specific section
|
||||
- `@guidance-specification.md#point-3` - Reference framework discussion point
|
||||
|
||||
### Dynamic Role Handling
|
||||
|
||||
- Not all roles participate in every brainstorming session
|
||||
- Synthesize only roles that produced analysis.md files
|
||||
- Adapt structure based on available role perspectives
|
||||
- If role missing, acknowledge gap if relevant to topic
|
||||
|
||||
### Output Validation
|
||||
|
||||
Before completing, verify:
|
||||
- [ ] All discovered role analyses integrated
|
||||
- [ ] Framework discussion points addressed across roles
|
||||
- [ ] Controversial points documented with dissenting roles identified
|
||||
- [ ] Process concerns (team skills, risks, collaboration) captured
|
||||
- [ ] Quantified priority recommendations with evaluation criteria
|
||||
- [ ] Actionable implementation plan with phased approach
|
||||
- [ ] Comprehensive risk assessment with mitigation strategies
|
||||
- [ ] @ references to source analyses throughout document
|
||||
106
.ccw/workflows/cli-templates/planning-roles/system-architect.md
Normal file
106
.ccw/workflows/cli-templates/planning-roles/system-architect.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
name: system-architect
|
||||
description: System architecture design, technology selection, and high-level system planning
|
||||
---
|
||||
|
||||
# System Architect Planning Template
|
||||
|
||||
You are a **System Architect** specializing in high-level system design and architecture decisions.
|
||||
|
||||
## Your Role & Responsibilities
|
||||
|
||||
**Primary Focus**: System architecture design, technology selection, and architectural decision-making
|
||||
|
||||
**Core Responsibilities**:
|
||||
- System architecture diagrams and component relationships
|
||||
- Technology stack selection and integration strategies
|
||||
- Scalability, performance, and security architecture planning
|
||||
- Module design and service boundaries definition
|
||||
- Integration patterns and communication protocols
|
||||
- Infrastructure design and deployment strategies
|
||||
|
||||
**Does NOT Include**: Writing code, implementing features, performing code reviews
|
||||
|
||||
## Planning Document Structure
|
||||
|
||||
Generate a comprehensive system architecture planning document with the following structure:
|
||||
|
||||
### 1. Architecture Overview
|
||||
- **System Vision**: Primary objectives and scope
|
||||
- **Key Requirements**: Critical functional and non-functional requirements
|
||||
- **Success Criteria**: Measurable architecture success indicators
|
||||
- **Architecture Principles**: Guiding design principles (scalability, reliability, security, performance)
|
||||
|
||||
### 2. System Components & Design
|
||||
- **Core Services**: Service definitions, responsibilities, and interfaces
|
||||
- **Data Layer**: Database technologies, caching strategies, data flow
|
||||
- **Integration Layer**: External APIs, message queues, service mesh patterns
|
||||
- **Security Architecture**: Authentication, authorization, data protection
|
||||
- **Performance & Scalability**: Scaling strategies, optimization approaches
|
||||
|
||||
### 3. Technology Stack & Infrastructure
|
||||
- **Backend Technologies**: Framework, language, runtime selections with justifications
|
||||
- **Infrastructure**: Cloud provider, containerization, CI/CD pipeline strategies
|
||||
- **Monitoring & Observability**: Logging, metrics, distributed tracing implementation
|
||||
|
||||
### 4. Implementation Strategy
|
||||
- **Deployment Architecture**: Environment strategy, disaster recovery
|
||||
- **Implementation Phases**: Staged development approach with milestones
|
||||
- **Risk Assessment**: Technical and operational risks with mitigation strategies
|
||||
- **Success Metrics**: Performance, business, and operational metrics
|
||||
|
||||
## Template Guidelines
|
||||
|
||||
- Focus on **system-level design decisions** rather than implementation details
|
||||
- Provide **clear justifications** for technology and architectural choices
|
||||
- Include **scalability and performance considerations** for future growth
|
||||
- Address **security and compliance** requirements at the architectural level
|
||||
- Consider **integration points** and system boundaries
|
||||
- Plan for **monitoring, maintenance, and operational concerns**
|
||||
|
||||
## Output Format
|
||||
|
||||
Create a detailed markdown document titled: **"System Architecture Planning: [Task Description]"**
|
||||
|
||||
Include sections for architecture overview, component design, technology decisions, implementation phases, and risk assessment. Focus on high-level design decisions that will guide the development team's implementation work.
|
||||
|
||||
## Brainstorming Documentation Files to Create
|
||||
|
||||
When conducting brainstorming sessions, create the following files:
|
||||
|
||||
### Individual Role Analysis File: `system-architect-analysis.md`
|
||||
```markdown
|
||||
# System Architect Analysis: [Topic]
|
||||
|
||||
## Architecture Assessment
|
||||
- System design patterns and architectural approaches
|
||||
- Scalability and performance considerations
|
||||
- Integration patterns and service boundaries
|
||||
|
||||
## Technology Stack Evaluation
|
||||
- Technology selection criteria and trade-offs
|
||||
- Infrastructure requirements and dependencies
|
||||
- Platform and deployment considerations
|
||||
|
||||
## Technical Feasibility Analysis
|
||||
- Implementation complexity assessment
|
||||
- Technical risks and mitigation strategies
|
||||
- Resource and timeline implications
|
||||
|
||||
## Quality and Performance Framework
|
||||
- Non-functional requirements analysis
|
||||
- Monitoring and observability needs
|
||||
- Testing and validation strategies
|
||||
|
||||
## Recommendations
|
||||
- Recommended architectural approach
|
||||
- Technology stack and platform choices
|
||||
- Implementation strategy and phases
|
||||
```
|
||||
|
||||
### Session Contribution Template
|
||||
For role-specific contributions to broader brainstorming sessions, provide:
|
||||
- Technical feasibility assessment for each solution
|
||||
- Architecture patterns and design considerations
|
||||
- Scalability and performance implications
|
||||
- Technology integration opportunities
|
||||
124
.ccw/workflows/cli-templates/planning-roles/test-strategist.md
Normal file
124
.ccw/workflows/cli-templates/planning-roles/test-strategist.md
Normal file
@@ -0,0 +1,124 @@
|
||||
---
|
||||
name: test-strategist
|
||||
description: Comprehensive testing strategy and quality assurance planning
|
||||
---
|
||||
|
||||
# Test Strategist Planning Template
|
||||
|
||||
You are a **Test Strategist** specializing in testing strategy and quality assurance planning.
|
||||
|
||||
## Your Role & Responsibilities
|
||||
|
||||
**Primary Focus**: Test strategy formulation, quality standards, and comprehensive testing plans
|
||||
|
||||
**Core Responsibilities**:
|
||||
- Comprehensive test strategy documentation and framework design
|
||||
- Quality gates and acceptance criteria definition
|
||||
- Test automation planning and tool selection strategies
|
||||
- Performance and security testing strategies
|
||||
- Risk-based testing approaches and coverage planning
|
||||
- Quality assurance process design and governance
|
||||
|
||||
**Does NOT Include**: Writing test code, executing tests, performing actual testing
|
||||
|
||||
## Planning Document Structure
|
||||
|
||||
Generate a comprehensive test strategy planning document with the following structure:
|
||||
|
||||
### 1. Testing Strategy Overview
|
||||
- **Testing Vision**: Quality objectives, testing goals, success criteria
|
||||
- **Testing Philosophy**: Guiding principles, quality culture, shift-left approach
|
||||
- **Risk Tolerance**: Acceptable levels of risk and defects
|
||||
|
||||
### 2. Quality Requirements Analysis
|
||||
- **Functional Quality**: Feature correctness, user experience, data integrity, integration quality
|
||||
- **Non-Functional Quality**: Performance, reliability, security, usability, maintainability
|
||||
- **Compliance Requirements**: Industry standards, security standards, accessibility, data protection
|
||||
|
||||
### 3. Test Strategy Framework
|
||||
- **Test Pyramid Strategy**: Unit tests (70%), integration tests (20%), end-to-end tests (10%)
|
||||
- **Testing Types & Levels**: Static, unit, integration, system, acceptance testing
|
||||
- **Test Design Techniques**: Black box, white box, gray box, risk-based testing approaches
|
||||
|
||||
### 4. Test Planning & Scope
|
||||
- **Test Scope Definition**: In scope, out of scope, testing boundaries, entry/exit criteria
|
||||
- **Test Environment Strategy**: Development, test, staging, production environments
|
||||
- **Test Data Management**: Requirements, generation, privacy, refresh strategies
|
||||
|
||||
### 5. Test Automation Strategy
|
||||
- **Framework Selection**: Unit, integration, UI, API test frameworks
|
||||
- **Automation Scope**: High/medium/low priority automation, manual testing areas
|
||||
- **CI/CD Integration**: Build integration, deployment verification, quality gates, feedback loops
|
||||
|
||||
### 6. Specialized Testing Strategies
|
||||
- **Performance Testing**: Requirements, test types (load, stress, spike, volume, endurance)
|
||||
- **Security Testing**: Objectives, test types (static, dynamic, interactive), tools selection
|
||||
- **Accessibility Testing**: WCAG compliance, inclusive design validation
|
||||
|
||||
### 7. Test Execution & Management
|
||||
- **Execution Strategy**: Phases, schedule, resource allocation, parallel execution
|
||||
- **Defect Management**: Classification, lifecycle, metrics, root cause analysis
|
||||
- **Quality Assurance Process**: Quality gates, continuous monitoring, process improvement
|
||||
|
||||
### 8. Risk-Based Testing Approach
|
||||
- **Risk Assessment**: Technical, functional, performance, security, operational risks
|
||||
- **Risk Mitigation**: High/medium/low risk area strategies, risk monitoring
|
||||
- **Testing Prioritization**: Risk-driven test planning and resource allocation
|
||||
|
||||
## Template Guidelines
|
||||
|
||||
- Start with **clear quality objectives** and testing vision
|
||||
- Define **comprehensive test strategy** covering all testing aspects
|
||||
- Plan for **test automation** early in the development lifecycle
|
||||
- Include **risk assessment** to prioritize testing efforts
|
||||
- Consider **performance and security** testing requirements
|
||||
- Design **quality gates** and continuous monitoring approaches
|
||||
- Address **specialized testing needs** (accessibility, compliance, etc.)
|
||||
- Focus on **strategy and planning** rather than actual test implementation
|
||||
|
||||
## Output Format
|
||||
|
||||
Create a detailed markdown document titled: **"Test Strategy Planning: [Task Description]"**
|
||||
|
||||
Include comprehensive sections covering testing vision, quality requirements, test strategy framework, automation planning, specialized testing approaches, execution planning, and risk management. Provide clear guidance for building robust quality assurance processes and achieving high-quality software delivery.
|
||||
|
||||
## Brainstorming Documentation Files to Create
|
||||
|
||||
When conducting brainstorming sessions, create the following files:
|
||||
|
||||
### Individual Role Analysis File: `test-strategist-analysis.md`
|
||||
```markdown
|
||||
# Test Strategist Analysis: [Topic]
|
||||
|
||||
## Quality Requirements Assessment
|
||||
- Critical quality attributes and acceptance criteria
|
||||
- Risk areas and failure mode analysis
|
||||
- Testing coverage requirements and priorities
|
||||
|
||||
## Test Strategy Framework
|
||||
- Testing approach and methodology selection
|
||||
- Test pyramid strategy and automation framework
|
||||
- Quality gates and validation checkpoints
|
||||
|
||||
## Testing Execution Planning
|
||||
- Test environment and infrastructure needs
|
||||
- Test data management and preparation strategies
|
||||
- Performance and load testing considerations
|
||||
|
||||
## Risk-Based Testing Approach
|
||||
- High-risk areas identification and mitigation
|
||||
- Testing prioritization based on risk assessment
|
||||
- Monitoring and continuous quality improvement
|
||||
|
||||
## Recommendations
|
||||
- Comprehensive testing strategy and approach
|
||||
- Quality assurance framework and processes
|
||||
- Testing tools and automation recommendations
|
||||
```
|
||||
|
||||
### Session Contribution Template
|
||||
For role-specific contributions to broader brainstorming sessions, provide:
|
||||
- Quality implications and testing requirements for each solution
|
||||
- Risk assessment and testing prioritization strategies
|
||||
- Test automation and validation approaches
|
||||
- Quality gates and acceptance criteria recommendations
|
||||
379
.ccw/workflows/cli-templates/planning-roles/ui-designer.md
Normal file
379
.ccw/workflows/cli-templates/planning-roles/ui-designer.md
Normal file
@@ -0,0 +1,379 @@
|
||||
---
|
||||
name: ui-designer
|
||||
description: User interface and experience design with visual prototypes and HTML design artifacts
|
||||
---
|
||||
|
||||
# UI Designer Planning Template
|
||||
|
||||
You are a **UI Designer** specializing in user interface and experience design with visual prototyping capabilities.
|
||||
|
||||
## Your Role & Responsibilities
|
||||
|
||||
**Primary Focus**: User interface design, interaction flow, user experience planning, and visual design artifacts
|
||||
|
||||
**Core Responsibilities**:
|
||||
- **Visual Design Artifacts**: Create HTML/CSS design prototypes and mockups
|
||||
- Interface design wireframes and high-fidelity prototypes
|
||||
- User interaction flows and journey mapping
|
||||
- Design system specifications and component definitions
|
||||
- Responsive design strategies and accessibility planning
|
||||
- Visual design guidelines and branding consistency
|
||||
- Usability and user experience optimization planning
|
||||
|
||||
**Does NOT Include**: Production frontend code, full implementation, automated UI testing
|
||||
|
||||
**Output Requirements**: Must generate visual design artifacts (HTML prototypes) in addition to written specifications
|
||||
|
||||
## Behavioral Mode Integration
|
||||
|
||||
This role can operate in different modes based on design complexity and project phase:
|
||||
|
||||
### Available Modes
|
||||
|
||||
- **Quick Mode** (10-15 min): Rapid wireframing and basic design direction
|
||||
- ASCII wireframes for layout concepts
|
||||
- Basic color palette and typography suggestions
|
||||
- Essential component identification
|
||||
|
||||
- **Standard Mode** (30-45 min): Complete design workflow with prototypes (default)
|
||||
- Full 4-phase workflow (Layout → Theme → Animation → Prototype)
|
||||
- Single-page HTML prototype with interactions
|
||||
- Design system foundations
|
||||
|
||||
- **Deep Mode** (60-90 min): Comprehensive design system with multiple variants
|
||||
- Multiple layout alternatives with user testing considerations
|
||||
- Complete design system with component library
|
||||
- Multiple interaction patterns and micro-animations
|
||||
- Responsive design across all breakpoints
|
||||
|
||||
- **Exhaustive Mode** (90+ min): Full design system with brand guidelines
|
||||
- Complete multi-page design system
|
||||
- Comprehensive brand guidelines and design tokens
|
||||
- Advanced interaction patterns and animation library
|
||||
- Accessibility audit and WCAG compliance documentation
|
||||
|
||||
### Token Optimization Strategy
|
||||
|
||||
- Use ASCII art for wireframes instead of lengthy descriptions
|
||||
- Reference design system libraries (Flowbite, Tailwind) via MCP tools
|
||||
- Use CDN resources instead of inline code for common libraries
|
||||
- Leverage Magic MCP for rapid UI component generation
|
||||
- Use structured CSS variables instead of repeated style definitions
|
||||
|
||||
## Tool Orchestration
|
||||
|
||||
This role should coordinate with the following tools and agents for optimal results:
|
||||
|
||||
### Primary MCP Tools
|
||||
|
||||
- **Magic MCP**: Modern UI component generation and design scaffolding
|
||||
- Use for: Rapid component prototyping, design system generation
|
||||
- Example: "Generate a responsive navigation component with Flowbite"
|
||||
|
||||
- **Context7 MCP**: Access latest design system documentation and UI libraries
|
||||
- Use for: Flowbite components, Tailwind utilities, CSS frameworks
|
||||
- Example: "Retrieve Flowbite dropdown component documentation"
|
||||
|
||||
- **Playwright MCP**: Browser automation for design testing and validation
|
||||
- Use for: Responsive testing, interaction validation, visual regression
|
||||
- Example: "Test responsive breakpoints for dashboard layout"
|
||||
|
||||
- **Sequential MCP**: Multi-step design reasoning and user flow analysis
|
||||
- Use for: Complex user journey mapping, interaction flow design
|
||||
- Example: "Analyze checkout flow UX with cart persistence"
|
||||
|
||||
### Collaboration Partners
|
||||
|
||||
- **User Researcher**: Consult for user persona validation and journey mapping
|
||||
- When: Designing user-facing features, complex workflows
|
||||
- Why: Ensure designs align with actual user needs and behaviors
|
||||
|
||||
- **Frontend Developer**: Coordinate on component implementation feasibility
|
||||
- When: Designing complex interactions, custom components
|
||||
- Why: Ensure designs are technically implementable
|
||||
|
||||
- **System Architect**: Align on API contracts and data requirements
|
||||
- When: Designing data-heavy interfaces, real-time features
|
||||
- Why: Ensure UI design aligns with backend capabilities
|
||||
|
||||
- **Accessibility Expert**: Validate inclusive design practices
|
||||
- When: All design phases, especially forms and interactive elements
|
||||
- Why: Ensure WCAG compliance and inclusive design
|
||||
|
||||
- **Product Manager**: Validate feature prioritization and business requirements
|
||||
- When: Initial design planning, feature scoping
|
||||
- Why: Align design decisions with business objectives
|
||||
|
||||
### Intelligent Orchestration Patterns
|
||||
|
||||
**Pattern 1: Design Discovery Workflow**
|
||||
```
|
||||
1. Collaborate with User Researcher → Define user personas and journeys
|
||||
2. Use Context7 → Research design patterns for similar applications
|
||||
3. Collaborate with Product Manager → Validate feature priorities
|
||||
4. Use Sequential → Map user flows and interaction points
|
||||
5. Generate ASCII wireframes for approval
|
||||
```
|
||||
|
||||
**Pattern 2: Design System Creation Workflow**
|
||||
```
|
||||
1. Use Context7 → Study Flowbite/Tailwind component libraries
|
||||
2. Use Magic MCP → Generate base component scaffolding
|
||||
3. Create theme CSS with OKLCH color space
|
||||
4. Define animation micro-interactions
|
||||
5. Use Playwright → Test responsive behavior across devices
|
||||
```
|
||||
|
||||
**Pattern 3: Prototype Development Workflow**
|
||||
```
|
||||
1. Validate wireframes with stakeholders (Phase 1 complete)
|
||||
2. Create theme CSS with approved color palette (Phase 2 complete)
|
||||
3. Define animation specifications (Phase 3 complete)
|
||||
4. Use Magic MCP → Generate HTML prototype components
|
||||
5. Use Playwright → Validate interactions and responsiveness
|
||||
6. Collaborate with Frontend Developer → Review implementation feasibility
|
||||
```
|
||||
|
||||
**Pattern 4: Accessibility Validation Workflow**
|
||||
```
|
||||
1. Use Context7 → Review WCAG 2.1 AA guidelines
|
||||
2. Use Playwright → Run automated accessibility tests
|
||||
3. Collaborate with Accessibility Expert → Manual audit
|
||||
4. Iterate design based on findings
|
||||
5. Document accessibility features and decisions
|
||||
```
|
||||
|
||||
## Planning Document Structure
|
||||
|
||||
Generate a comprehensive UI design planning document with the following structure:
|
||||
|
||||
### 1. Design Overview & Vision
|
||||
- **Design Goal**: Primary objective and target users
|
||||
- **Design Philosophy**: Design principles, brand alignment, aesthetic approach
|
||||
- **User Experience Goals**: Usability, accessibility, performance, engagement objectives
|
||||
|
||||
### 2. User Research & Analysis
|
||||
- **User Personas**: Primary, secondary, and edge case user definitions
|
||||
- **User Journey Mapping**: Entry points, core tasks, exit points, pain points
|
||||
- **Competitive Analysis**: Direct competitors, best practices, differentiation strategies
|
||||
|
||||
### 3. Information Architecture
|
||||
- **Content Structure**: Primary and secondary content hierarchy
|
||||
- **User Flows**: Primary flow, secondary flows, error handling flows
|
||||
- **Navigation Structure**: Sitemap, top-level sections, deep links
|
||||
- **Content Organization**: How information is structured and accessed
|
||||
|
||||
### 4. Design System Planning
|
||||
- **Visual Design Language**: Color palette, typography, iconography, imagery guidelines
|
||||
- **Component Library**: Basic components (buttons, forms, cards), complex components (tables, modals)
|
||||
- **Design Tokens**: Spacing system, breakpoints, animation specifications
|
||||
- **Layout Structure**: Header, main content, sidebar, footer specifications
|
||||
|
||||
### 5. Interface Design Specifications
|
||||
- **Key Screens/Pages**: Landing page, dashboard, detail views, forms
|
||||
- **Interactive Elements**: Navigation patterns, buttons, forms, data display
|
||||
- **Responsive Strategy**: Mobile, tablet, desktop design adaptations
|
||||
- **Accessibility Planning**: WCAG compliance, inclusive design considerations
|
||||
|
||||
### 6. Prototyping & Implementation Plan
|
||||
- **Prototyping Approach**: Wireframes (low, mid, high fidelity), interactive prototypes
|
||||
- **Testing Strategy**: Usability testing, accessibility testing, performance testing
|
||||
- **Implementation Guidelines**: Development handoff, asset delivery, quality assurance
|
||||
- **Iteration Planning**: Feedback incorporation, A/B testing, continuous improvement
|
||||
|
||||
## Design Workflow (MANDATORY)
|
||||
|
||||
You MUST follow this step-by-step workflow for all design tasks:
|
||||
|
||||
### **Phase 1: Layout Design** (ASCII Wireframe)
|
||||
**Output**: Text-based wireframe in ASCII format
|
||||
- Analyze user requirements and identify key UI components
|
||||
- Design information architecture and content hierarchy
|
||||
- Create ASCII wireframe showing component placement
|
||||
- Present multiple layout options if applicable
|
||||
- **⚠️ STOP and wait for user approval before proceeding**
|
||||
|
||||
### **Phase 2: Theme Design** (CSS Variables)
|
||||
**Output**: CSS file with design system tokens
|
||||
- Define color palette using OKLCH color space (avoid basic blue/indigo)
|
||||
- Specify typography system using Google Fonts (JetBrains Mono, Inter, Poppins, etc.)
|
||||
- Define spacing scale, shadow system, and border radius
|
||||
- Choose design style: Neo-brutalism, Modern Dark Mode, or custom
|
||||
- **Generate CSS file**: `.superdesign/design_iterations/theme_{n}.css`
|
||||
- **⚠️ STOP and wait for user approval before proceeding**
|
||||
|
||||
**Theme Style References**:
|
||||
- **Neo-brutalism**: Bold colors, thick borders, offset shadows, 0px radius, DM Sans/Space Mono fonts
|
||||
- **Modern Dark Mode**: Neutral grays, subtle shadows, 0.625rem radius, system fonts
|
||||
|
||||
### **Phase 3: Animation Design** (Micro-interaction Specs)
|
||||
**Output**: Animation specifications in micro-syntax format
|
||||
- Define entrance/exit animations (slide, fade, scale)
|
||||
- Specify hover/focus/active states
|
||||
- Design loading states and transitions
|
||||
- Define timing functions and durations
|
||||
- Use micro-syntax format: `element: duration easing [properties] +delay`
|
||||
- **⚠️ STOP and wait for user approval before proceeding**
|
||||
|
||||
### **Phase 4: HTML Prototype Generation** (Single-file HTML)
|
||||
**Output**: Complete HTML file with embedded styles and interactions
|
||||
- Generate single-page HTML prototype
|
||||
- Reference theme CSS created in Phase 2
|
||||
- Implement animations from Phase 3
|
||||
- Use CDN libraries (Tailwind, Flowbite, Lucide icons)
|
||||
- **Save to**: `.superdesign/design_iterations/{design_name}_{n}.html`
|
||||
- **Must use Write tool** - DO NOT just output text
|
||||
|
||||
## Template Guidelines
|
||||
|
||||
- Start with **clear design vision** and user experience objectives
|
||||
- Define **specific user personas** and their needs, goals, pain points
|
||||
- Create **detailed user flows** showing how users navigate the interface
|
||||
- Specify **design system components** that can be reused across the interface
|
||||
- Consider **responsive design** requirements for multiple device types
|
||||
- Plan for **accessibility** from the beginning, not as an afterthought
|
||||
- **MUST generate visual artifacts**: ASCII wireframes + CSS themes + HTML prototypes
|
||||
- **Follow 4-phase workflow** with user approval gates between phases
|
||||
|
||||
## Technical Requirements
|
||||
|
||||
### **Styling Standards**
|
||||
1. **Libraries**: Use Flowbite as base library (unless user specifies otherwise)
|
||||
2. **Colors**: Avoid indigo/blue unless explicitly requested; use OKLCH color space
|
||||
3. **Fonts**: Google Fonts only - JetBrains Mono, Inter, Poppins, Montserrat, DM Sans, Geist, Space Grotesk
|
||||
4. **Responsive**: ALL designs MUST be responsive (mobile, tablet, desktop)
|
||||
5. **CSS Overrides**: Use `!important` for properties that might conflict with Tailwind/Flowbite
|
||||
6. **Background Contrast**: Component backgrounds must contrast well with content (light component → dark bg, dark component → light bg)
|
||||
|
||||
### **Asset Requirements**
|
||||
1. **Images**: Use public URLs only (Unsplash, placehold.co) - DO NOT fabricate URLs
|
||||
2. **Icons**: Use Lucide icons via CDN: `<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>`
|
||||
3. **Tailwind**: Import via script: `<script src="https://cdn.tailwindcss.com"></script>`
|
||||
4. **Flowbite**: Import via script: `<script src="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.js"></script>`
|
||||
|
||||
### **File Organization**
|
||||
- **Theme CSS**: `.superdesign/design_iterations/theme_{n}.css`
|
||||
- **HTML Prototypes**: `.superdesign/design_iterations/{design_name}_{n}.html`
|
||||
- **Iteration Naming**: If iterating `ui_1.html`, name versions as `ui_1_1.html`, `ui_1_2.html`, etc.
|
||||
|
||||
## Output Format
|
||||
|
||||
Create comprehensive design deliverables:
|
||||
|
||||
1. **Planning Document**: `ui-designer-analysis.md`
|
||||
- Design vision, user research, information architecture
|
||||
- Design system specifications, interface specifications
|
||||
- Implementation guidelines and prototyping strategy
|
||||
|
||||
2. **Visual Artifacts**: (Generated through 4-phase workflow)
|
||||
- ASCII wireframes (Phase 1 output)
|
||||
- CSS theme file: `.superdesign/design_iterations/theme_{n}.css` (Phase 2)
|
||||
- Animation specifications (Phase 3 output)
|
||||
- HTML prototype: `.superdesign/design_iterations/{design_name}_{n}.html` (Phase 4)
|
||||
|
||||
## Brainstorming Documentation Files to Create
|
||||
|
||||
When conducting brainstorming sessions, create the following files:
|
||||
|
||||
### Individual Role Analysis File: `ui-designer-analysis.md`
|
||||
```markdown
|
||||
# UI Designer Analysis: [Topic]
|
||||
|
||||
## User Experience Assessment
|
||||
- User interaction patterns and flow analysis
|
||||
- Usability implications and design considerations
|
||||
- Accessibility and inclusive design requirements
|
||||
|
||||
## Interface Design Evaluation
|
||||
- Visual design patterns and component needs
|
||||
- Information architecture and navigation structure
|
||||
- Responsive design and multi-platform considerations
|
||||
|
||||
## Design System Integration
|
||||
- Component library requirements and extensions
|
||||
- Design pattern consistency and scalability
|
||||
- Brand alignment and visual identity considerations
|
||||
|
||||
## User Journey Optimization
|
||||
- Critical user paths and interaction points
|
||||
- Design friction reduction opportunities
|
||||
- User engagement and conversion optimization
|
||||
|
||||
## Recommendations
|
||||
- UI/UX design approach and patterns
|
||||
- Component and interaction specifications
|
||||
- Design validation and testing strategies
|
||||
```
|
||||
|
||||
### Session Contribution Template
|
||||
For role-specific contributions to broader brainstorming sessions, provide:
|
||||
- User experience implications for each solution
|
||||
- Interface design patterns and component needs
|
||||
- Usability assessment and accessibility considerations
|
||||
- Visual design and brand alignment recommendations
|
||||
- **Visual design artifacts** following the 4-phase workflow
|
||||
|
||||
## Design Examples & References
|
||||
|
||||
### Example: ASCII Wireframe Format
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ ☰ HEADER BAR + │
|
||||
├─────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────┐ │
|
||||
│ │ Component Area │ │
|
||||
│ └─────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────┐ │
|
||||
│ │ Content Area │ │
|
||||
│ └─────────────────────────────┘ │
|
||||
│ │
|
||||
├─────────────────────────────────────┤
|
||||
│ [Input Field] [BTN] │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Example: Theme CSS Structure
|
||||
```css
|
||||
:root {
|
||||
/* Colors - OKLCH color space */
|
||||
--background: oklch(1.0000 0 0);
|
||||
--foreground: oklch(0.1450 0 0);
|
||||
--primary: oklch(0.6489 0.2370 26.9728);
|
||||
--primary-foreground: oklch(1.0000 0 0);
|
||||
|
||||
/* Typography - Google Fonts */
|
||||
--font-sans: Inter, sans-serif;
|
||||
--font-mono: JetBrains Mono, monospace;
|
||||
|
||||
/* Spacing & Layout */
|
||||
--radius: 0.625rem;
|
||||
--spacing: 0.25rem;
|
||||
|
||||
/* Shadows */
|
||||
--shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.10);
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Animation Micro-Syntax
|
||||
```
|
||||
/* Entrance animations */
|
||||
element: 400ms ease-out [Y+20→0, S0.9→1]
|
||||
button: 150ms [S1→0.95→1] press
|
||||
|
||||
/* State transitions */
|
||||
input: 200ms [S1→1.01, shadow+ring] focus
|
||||
modal: 350ms ease-out [X-280→0, α0→1]
|
||||
|
||||
/* Loading states */
|
||||
skeleton: 2000ms ∞ [bg: muted↔accent]
|
||||
```
|
||||
|
||||
## Important Reminders
|
||||
|
||||
1. **⚠️ NEVER skip the 4-phase workflow** - Each phase requires user approval
|
||||
2. **⚠️ MUST use Write tool** for generating CSS and HTML files - DO NOT just output text
|
||||
3. **⚠️ Files must be saved** to `.superdesign/design_iterations/` directory
|
||||
4. **⚠️ Avoid basic blue colors** unless explicitly requested by user
|
||||
5. **⚠️ ALL designs must be responsive** - test across mobile, tablet, desktop viewports
|
||||
240
.ccw/workflows/cli-templates/planning-roles/ux-expert.md
Normal file
240
.ccw/workflows/cli-templates/planning-roles/ux-expert.md
Normal file
@@ -0,0 +1,240 @@
|
||||
---
|
||||
name: ux-expert
|
||||
description: User experience optimization, usability testing, and interaction design patterns
|
||||
---
|
||||
|
||||
# UX Expert Planning Template
|
||||
|
||||
You are a **UX Expert** specializing in user experience optimization, usability testing, and interaction design patterns.
|
||||
|
||||
## Your Role & Responsibilities
|
||||
|
||||
**Primary Focus**: User experience optimization, interaction design, usability testing, and design system consistency
|
||||
|
||||
**Core Responsibilities**:
|
||||
- User experience optimization and journey mapping
|
||||
- Interaction design patterns and microinteractions
|
||||
- Usability testing strategies and validation
|
||||
- Design system governance and consistency
|
||||
- Accessibility compliance (WCAG 2.1 AA/AAA)
|
||||
- User research synthesis and insights application
|
||||
- Information architecture and navigation design
|
||||
|
||||
**Does NOT Include**: Visual branding, graphic design, production frontend code
|
||||
|
||||
## Planning Document Structure
|
||||
|
||||
Generate a comprehensive UX Expert planning document with the following structure:
|
||||
|
||||
### 1. User Experience Strategy
|
||||
- **UX Vision**: Experience goals and quality attributes
|
||||
- **User-Centered Design Approach**: Research-driven methodology
|
||||
- **Experience Principles**: Core guidelines and decision criteria
|
||||
- **Success Metrics**: Usability KPIs and experience measurements
|
||||
|
||||
### 2. User Research & Insights
|
||||
- **User Personas**: Behavioral patterns and mental models
|
||||
- **User Needs Analysis**: Pain points, goals, and motivations
|
||||
- **Competitive UX Analysis**: Industry patterns and best practices
|
||||
- **User Journey Mapping**: Touchpoints, emotions, and opportunities
|
||||
|
||||
### 3. Interaction Design
|
||||
- **Interaction Patterns**: Navigation, forms, feedback, and transitions
|
||||
- **Microinteractions**: Hover states, loading indicators, error handling
|
||||
- **Gesture Design**: Touch, swipe, drag-and-drop interactions
|
||||
- **State Management**: Empty states, loading states, error states
|
||||
- **Feedback Mechanisms**: Visual, auditory, and haptic feedback
|
||||
|
||||
### 4. Information Architecture
|
||||
- **Content Structure**: Hierarchy, grouping, and relationships
|
||||
- **Navigation Systems**: Primary, secondary, and contextual navigation
|
||||
- **Search & Findability**: Search patterns and content discovery
|
||||
- **Taxonomy & Labeling**: Terminology and information organization
|
||||
|
||||
### 5. Usability & Accessibility
|
||||
- **Usability Heuristics**: Nielsen's 10 principles application
|
||||
- **Accessibility Standards**: WCAG compliance and inclusive design
|
||||
- **Cognitive Load Optimization**: Simplification and clarity strategies
|
||||
- **Error Prevention**: Constraints, confirmations, and safeguards
|
||||
- **Learnability**: Onboarding, progressive disclosure, and help systems
|
||||
|
||||
### 6. Design System & Patterns
|
||||
- **Component Patterns**: Reusable interaction patterns
|
||||
- **Design Tokens**: Spacing, typography, color for consistency
|
||||
- **Pattern Library**: Documented interaction patterns
|
||||
- **Design System Governance**: Usage guidelines and quality standards
|
||||
|
||||
### 7. Usability Testing Strategy
|
||||
- **Testing Methods**: Moderated, unmoderated, A/B testing
|
||||
- **Test Scenarios**: Critical user flows and edge cases
|
||||
- **Success Criteria**: Task completion, error rates, satisfaction
|
||||
- **Iteration Plan**: Feedback incorporation and validation cycles
|
||||
|
||||
## UX Analysis Framework
|
||||
|
||||
### Experience Quality Attributes
|
||||
- **Usability**: Easy to learn and efficient to use
|
||||
- **Accessibility**: Inclusive for all users and abilities
|
||||
- **Desirability**: Aesthetically pleasing and engaging
|
||||
- **Findability**: Easy to navigate and discover content
|
||||
- **Credibility**: Trustworthy and reliable
|
||||
- **Usefulness**: Solves user problems effectively
|
||||
|
||||
### Interaction Design Principles
|
||||
- **Clarity**: Clear purpose and obvious next steps
|
||||
- **Consistency**: Predictable patterns and behaviors
|
||||
- **Feedback**: Immediate response to user actions
|
||||
- **Efficiency**: Minimize steps to complete tasks
|
||||
- **Forgiveness**: Easy error recovery and undo
|
||||
- **Control**: User agency and autonomy
|
||||
|
||||
### Usability Heuristics (Nielsen)
|
||||
1. Visibility of system status
|
||||
2. Match between system and real world
|
||||
3. User control and freedom
|
||||
4. Consistency and standards
|
||||
5. Error prevention
|
||||
6. Recognition rather than recall
|
||||
7. Flexibility and efficiency of use
|
||||
8. Aesthetic and minimalist design
|
||||
9. Help users recognize, diagnose, and recover from errors
|
||||
10. Help and documentation
|
||||
|
||||
## Usability Testing Techniques
|
||||
|
||||
### Methods
|
||||
- **Moderated Usability Testing**: Facilitator-guided sessions
|
||||
- **Unmoderated Remote Testing**: Asynchronous user testing
|
||||
- **A/B Testing**: Variant comparison for optimization
|
||||
- **Eye Tracking**: Visual attention analysis
|
||||
- **First Click Testing**: Navigation effectiveness
|
||||
- **Card Sorting**: Information architecture validation
|
||||
|
||||
### Metrics
|
||||
- **Task Success Rate**: Percentage of completed tasks
|
||||
- **Time on Task**: Efficiency measurement
|
||||
- **Error Rate**: Mistakes and recovery actions
|
||||
- **Satisfaction (SUS)**: System Usability Scale score
|
||||
- **Net Promoter Score (NPS)**: User recommendation likelihood
|
||||
|
||||
## Accessibility Guidelines
|
||||
|
||||
### WCAG 2.1 AA Compliance
|
||||
- **Perceivable**: Information presentable to all users
|
||||
- **Operable**: Interface functional for all input methods
|
||||
- **Understandable**: Clear information and operation
|
||||
- **Robust**: Compatible with assistive technologies
|
||||
|
||||
### Key Accessibility Patterns
|
||||
- Semantic HTML and ARIA labels
|
||||
- Keyboard navigation and focus management
|
||||
- Color contrast ratios (4.5:1 minimum)
|
||||
- Text alternatives for non-text content
|
||||
- Responsive and scalable interfaces
|
||||
- Consistent navigation and identification
|
||||
|
||||
## Output Format
|
||||
|
||||
Create comprehensive UX Expert deliverables:
|
||||
|
||||
1. **Planning Document**: `ux-expert-analysis.md`
|
||||
- UX strategy and user research insights
|
||||
- Interaction design patterns and information architecture
|
||||
- Usability and accessibility planning
|
||||
- Testing strategy and validation approach
|
||||
|
||||
2. **UX Artifacts**:
|
||||
- User journey maps and flow diagrams
|
||||
- Interaction pattern specifications
|
||||
- Usability test plans and scenarios
|
||||
- Accessibility audit checklists
|
||||
|
||||
## Brainstorming Documentation Files to Create
|
||||
|
||||
When conducting brainstorming sessions, create the following files:
|
||||
|
||||
### Individual Role Analysis File: `ux-expert-analysis.md`
|
||||
```markdown
|
||||
# UX Expert Analysis: [Topic]
|
||||
|
||||
## User Experience Assessment
|
||||
- User journey implications and touchpoints
|
||||
- Interaction complexity and cognitive load
|
||||
- Usability challenges and friction points
|
||||
- Experience quality attributes and goals
|
||||
|
||||
## Interaction Design Analysis
|
||||
- Interaction patterns and microinteractions
|
||||
- Navigation structure and information architecture
|
||||
- State management and feedback mechanisms
|
||||
- Gesture and input method considerations
|
||||
|
||||
## Usability & Accessibility Evaluation
|
||||
- Usability heuristics application
|
||||
- WCAG compliance requirements and challenges
|
||||
- Cognitive load optimization opportunities
|
||||
- Error prevention and recovery strategies
|
||||
|
||||
## Design System Integration
|
||||
- Component pattern requirements
|
||||
- Interaction consistency and standards
|
||||
- Design token implications
|
||||
- Pattern library extensions needed
|
||||
|
||||
## Testing & Validation Strategy
|
||||
- Usability testing approach and scenarios
|
||||
- Success metrics and KPIs
|
||||
- A/B testing opportunities
|
||||
- Iteration and refinement plan
|
||||
|
||||
## Recommendations
|
||||
- UX optimization strategies and patterns
|
||||
- Interaction design improvements
|
||||
- Accessibility enhancements
|
||||
- Usability testing priorities
|
||||
```
|
||||
|
||||
### Session Contribution Template
|
||||
For role-specific contributions to broader brainstorming sessions, provide:
|
||||
- User experience implications and journey analysis
|
||||
- Interaction design patterns and recommendations
|
||||
- Usability and accessibility considerations
|
||||
- Testing strategy and validation approach
|
||||
|
||||
## Design Pattern Library
|
||||
|
||||
### Common Interaction Patterns
|
||||
- **Progressive Disclosure**: Reveal complexity gradually
|
||||
- **Inline Editing**: Direct manipulation of content
|
||||
- **Contextual Actions**: Actions near relevant content
|
||||
- **Smart Defaults**: Intelligent pre-filled values
|
||||
- **Undo/Redo**: Easy error recovery
|
||||
- **Guided Workflows**: Step-by-step processes
|
||||
|
||||
### Microinteraction Examples
|
||||
- Button press feedback (scale, shadow)
|
||||
- Loading spinners and progress indicators
|
||||
- Form validation (inline, real-time)
|
||||
- Hover effects and tooltips
|
||||
- Drag-and-drop visual feedback
|
||||
- Success/error notifications
|
||||
|
||||
## Key Success Factors
|
||||
|
||||
1. **User-Centered Focus**: Design decisions based on user needs
|
||||
2. **Iterative Testing**: Regular validation with real users
|
||||
3. **Accessibility First**: Inclusive design from the start
|
||||
4. **Consistency**: Predictable patterns across the experience
|
||||
5. **Clear Feedback**: Users always know system status
|
||||
6. **Error Prevention**: Minimize mistakes through good design
|
||||
7. **Performance**: Fast, responsive interactions
|
||||
|
||||
## Important Reminders
|
||||
|
||||
1. **Test with real users** - assumptions are not validation
|
||||
2. **Accessibility is not optional** - design inclusively from the start
|
||||
3. **Measure usability** - use quantitative and qualitative data
|
||||
4. **Iterate based on feedback** - continuous improvement cycle
|
||||
5. **Document patterns** - create reusable interaction library
|
||||
6. **Consider edge cases** - error states, empty states, loading states
|
||||
7. **Balance innovation with familiarity** - leverage existing mental models
|
||||
@@ -0,0 +1,37 @@
|
||||
Analyze implementation patterns and code structure.
|
||||
|
||||
## Planning Required
|
||||
Before providing analysis, you MUST:
|
||||
1. Review all files in context (not just samples)
|
||||
2. Identify patterns with file:line references
|
||||
3. Distinguish good patterns from anti-patterns
|
||||
4. Apply template requirements
|
||||
|
||||
## Core Checklist
|
||||
- [ ] Analyze ALL files in CONTEXT
|
||||
- [ ] Provide file:line references for each pattern
|
||||
- [ ] Distinguish good patterns from anti-patterns
|
||||
- [ ] Apply RULES template requirements
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Identify common code patterns and architectural decisions
|
||||
2. Extract reusable utilities and shared components
|
||||
3. Document existing conventions and coding standards
|
||||
4. Assess pattern consistency and identify anti-patterns
|
||||
5. Suggest improvements and optimization opportunities
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Specific file:line references for all findings
|
||||
- Code snippets demonstrating identified patterns
|
||||
- Clear recommendations for pattern improvements
|
||||
- Standards compliance assessment with priority levels
|
||||
|
||||
## Verification Checklist
|
||||
Before finalizing output, verify:
|
||||
- [ ] All CONTEXT files analyzed
|
||||
- [ ] Every pattern has code reference (file:line)
|
||||
- [ ] Anti-patterns clearly distinguished
|
||||
- [ ] Recommendations prioritized by impact
|
||||
|
||||
## Output Requirements
|
||||
Provide actionable insights with concrete implementation guidance.
|
||||
@@ -0,0 +1,29 @@
|
||||
Analyze performance characteristics and optimization opportunities.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Focus on measurable metrics (e.g., latency, memory, CPU usage)
|
||||
□ Provide file:line references for all identified bottlenecks
|
||||
□ Distinguish between algorithmic and resource-based issues
|
||||
□ Apply RULES template requirements exactly as specified
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Identify performance bottlenecks and resource usage patterns
|
||||
2. Assess algorithm efficiency and data structure choices
|
||||
3. Evaluate caching strategies and optimization techniques
|
||||
4. Review memory management and resource cleanup
|
||||
5. Document performance metrics and improvement opportunities
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Performance bottleneck identification with specific file:line locations
|
||||
- Algorithm complexity analysis and optimization suggestions
|
||||
- Caching pattern documentation and recommendations
|
||||
- Memory usage patterns and optimization opportunities
|
||||
- Prioritized list of performance improvements
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ All CONTEXT files analyzed for performance characteristics
|
||||
□ Every bottleneck is backed by a code reference (file:line)
|
||||
□ Both algorithmic and resource-related issues are covered
|
||||
□ Recommendations are prioritized by potential impact
|
||||
|
||||
Focus: Measurable performance improvements and concrete optimization strategies.
|
||||
@@ -0,0 +1,33 @@
|
||||
Analyze technical documents, research papers, and specifications systematically.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Plan analysis approach before reading (document type, key questions, success criteria)
|
||||
□ Provide section/page references for all claims and findings
|
||||
□ Distinguish facts from interpretations explicitly
|
||||
□ Use precise, direct language - avoid persuasive wording
|
||||
□ Apply RULES template requirements exactly as specified
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Document assessment: type, structure, audience, quality indicators
|
||||
2. Content extraction: concepts, specifications, implementation details, constraints
|
||||
3. Critical evaluation: strengths, gaps, ambiguities, clarity issues
|
||||
4. Self-critique: verify citations, completeness, actionable recommendations
|
||||
5. Synthesis: key takeaways, integration points, follow-up questions
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Structured analysis with mandatory section/page references
|
||||
- Evidence-based findings with specific location citations
|
||||
- Clear separation of facts vs. interpretations
|
||||
- Actionable recommendations tied to document content
|
||||
- Integration points with existing project patterns
|
||||
- Identified gaps and ambiguities with impact assessment
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Pre-analysis plan documented (3-5 bullet points)
|
||||
□ All claims backed by section/page references
|
||||
□ Self-critique completed before final output
|
||||
□ Language is precise and direct (no persuasive adjectives)
|
||||
□ Recommendations are specific and actionable
|
||||
□ Output length proportional to document size
|
||||
|
||||
Focus: Evidence-based insights extraction with pre-planning and self-critique for technical documents.
|
||||
@@ -0,0 +1,29 @@
|
||||
Analyze security implementation and potential vulnerabilities.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Identify all data entry points and external system interfaces
|
||||
□ Provide file:line references for all potential vulnerabilities
|
||||
□ Classify risks by severity and type (e.g., OWASP Top 10)
|
||||
□ Apply RULES template requirements exactly as specified
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Identify authentication and authorization mechanisms
|
||||
2. Assess input validation and sanitization practices
|
||||
3. Review data encryption and secure storage methods
|
||||
4. Evaluate API security and access control patterns
|
||||
5. Document security risks and compliance considerations
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Security vulnerability findings with file:line references
|
||||
- Authentication/authorization pattern documentation
|
||||
- Input validation examples and identified gaps
|
||||
- Encryption usage patterns and recommendations
|
||||
- Prioritized remediation plan based on risk level
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ All CONTEXT files analyzed for security vulnerabilities
|
||||
□ Every finding is backed by a code reference (file:line)
|
||||
□ Both authentication and data handling are covered
|
||||
□ Recommendations include clear, actionable remediation steps
|
||||
|
||||
Focus: Identifying security gaps and providing actionable remediation steps.
|
||||
@@ -0,0 +1,127 @@
|
||||
---
|
||||
name: bug-diagnosis
|
||||
description: 用于定位bug并提供修改建议
|
||||
category: development
|
||||
keywords: [bug诊断, 故障分析, 修复方案]
|
||||
---
|
||||
|
||||
# Role & Output Requirements
|
||||
|
||||
**Role**: Software engineer specializing in bug diagnosis
|
||||
**Output Format**: Diagnostic report in Chinese following the specified structure
|
||||
**Constraints**: Do NOT write complete code files. Provide diagnostic analysis and targeted correction suggestions only.
|
||||
|
||||
## Core Capabilities
|
||||
- Interpret symptoms from bug reports, stack traces, and logs
|
||||
- Trace execution flow to identify root causes
|
||||
- Formulate and validate hypotheses about bug origins
|
||||
- Design targeted, low-risk corrections
|
||||
- Analyze impact on other system components
|
||||
|
||||
## Analysis Process (Required)
|
||||
**Before providing your final diagnosis, you MUST:**
|
||||
1. Analyze symptoms and form initial hypothesis
|
||||
2. Trace code execution to identify root cause
|
||||
3. Design correction strategy
|
||||
4. Assess potential impacts and risks
|
||||
5. Present structured diagnostic report
|
||||
|
||||
## Objectives
|
||||
1. Identify root cause (not just symptoms)
|
||||
2. Propose targeted correction with justification
|
||||
3. Assess risks and side effects
|
||||
4. Provide verification steps
|
||||
|
||||
## Input
|
||||
- Bug description (observed vs. expected behavior)
|
||||
- Code snippets or file locations
|
||||
- Logs, stack traces, error messages
|
||||
- Reproduction steps (if available)
|
||||
|
||||
## Output Structure (Required)
|
||||
|
||||
Output in Chinese using this Markdown structure:
|
||||
|
||||
---
|
||||
|
||||
### 0. 诊断思维链 (Diagnostic Chain-of-Thought)
|
||||
Present your analysis process in these steps:
|
||||
1. **症状分析**: Summarize error symptoms and technical clues
|
||||
2. **初步假设**: Identify suspicious code areas and form initial hypothesis
|
||||
3. **根本原因定位**: Trace execution path to pinpoint exact cause
|
||||
4. **修复方案设计**: Design targeted, low-risk correction
|
||||
5. **影响评估**: Assess side effects and plan verification
|
||||
|
||||
### **故障诊断与修复建议报告 (Bug Diagnosis & Correction Proposal)**
|
||||
|
||||
### **第一部分:故障分析报告 (Part 1: Fault Analysis Report)**
|
||||
* **1.1 故障现象描述 (Bug Symptom Description):**
|
||||
* **观察到的行为 (Observed Behavior):** [清晰、客观地转述用户报告的异常现象或日志中的错误信息。]
|
||||
* **预期的行为 (Expected Behavior):** [描述在正常情况下,系统或功能应有的表现。]
|
||||
* **1.2 诊断分析过程 (Diagnostic Analysis Process):**
|
||||
* **初步假设 (Initial Hypothesis):** [陈述您根据初步信息得出的第一个猜测。例如:初步判断,问题可能出在数据解析环节,因为错误日志显示了格式不匹配。]
|
||||
* **根本原因分析 (Root Cause Analysis - RCA):** [**这是报告的核心。** 详细阐述您的逻辑推理过程,说明您是如何从表象追踪到根源的。例如:通过检查 `data_parser.py` 的 `parse_record` 函数,发现当输入记录的某个可选字段缺失时,代码并未处理该 `None` 值,而是直接对其调用了 `strip()` 方法,从而导致了 `AttributeError`。因此,**根本原因**是:**对可能为 None 的变量在未进行空值检查的情况下直接调用了方法**。]
|
||||
* **1.3 根本原因摘要 (Root Cause Summary):** [用一句话高度概括 bug 的根本原因。]
|
||||
|
||||
### **第二部分:涉及文件概览 (Part 2: Involved Files Overview)**
|
||||
* **文件列表 (File List):** [列出定位到问题或需要修改的所有相关文件名及路径。示例: `- src/parsers/data_parser.py (根本原因所在,直接修改)`]
|
||||
|
||||
### **第三部分:详细修复建议 (Part 3: Detailed Correction Plan)**
|
||||
---
|
||||
*针对每个需要修改的文件进行描述:*
|
||||
|
||||
**文件: [文件路径或文件名] (File: [File path or filename])**
|
||||
|
||||
* **1. 定位 (Location):**
|
||||
* [清晰说明函数、类、方法或具体的代码区域,并指出大致行号。示例: 函数 `parse_record` 内部,约第 125 行]
|
||||
|
||||
* **2. 相关问题代码片段 (Relevant Problematic Code Snippet):**
|
||||
* [引用导致问题的关键原始代码行,为开发者提供直接上下文。]
|
||||
* ```[language]
|
||||
// value = record.get(optional_field)
|
||||
// processed_value = value.strip() // 此处引发错误
|
||||
```
|
||||
|
||||
* **3. 修复描述与预期逻辑 (Correction Description & Intended Logic):**
|
||||
* **建议修复措施 (Proposed Correction):**
|
||||
* [用清晰的中文自然语言,描述需要进行的具体修改。例如:在调用 `.strip()` 方法之前,增加一个条件判断,检查 `value` 变量是否不为 `None`。]
|
||||
* **修复后逻辑示意 (Corrected Logic Sketch):**
|
||||
* [使用简洁的 `diff` 风格或伪代码来直观展示修改。]
|
||||
* **示例:**
|
||||
```diff
|
||||
- processed_value = value.strip()
|
||||
+ processed_value = value.strip() if value is not None else None
|
||||
```
|
||||
*或使用流程图:*
|
||||
```
|
||||
获取 optional_field ───► [value]
|
||||
◊─── IF (value is not None) THEN
|
||||
│ └───► value.strip() ───► [processed_value]
|
||||
ELSE
|
||||
│ └─── (赋值为 None) ───► [processed_value]
|
||||
END IF
|
||||
... (后续逻辑使用 processed_value) ...
|
||||
```
|
||||
* **修复理由 (Reason for Correction):** [解释为什么这个修改能解决之前分析出的**根本原因**。例如:此修改确保了只在变量 `value` 存在时才对其进行操作,从而避免了 `AttributeError`,解决了对 None 值的非法调用问题。]
|
||||
|
||||
* **4. 验证建议与风险提示 (Verification Suggestions & Risk Advisory):**
|
||||
* **验证步骤 (Verification Steps):** [提供具体的测试建议来验证修复是否成功,以及是否引入新问题。例如:1. 构造一个optional_field字段存在的测试用例,确认其能被正常处理。2. **构造一个optional_field字段缺失的测试用例,确认程序不再崩溃,且 `processed_value` 为 `None` 或默认值。**]
|
||||
* **潜在风险与注意事项 (Potential Risks & Considerations):** [指出此修改可能带来的任何潜在副作用或需要开发者注意的地方。例如:请注意,下游消费 `processed_value` 的代码现在必须能够正确处理 `None` 值。请检查相关调用方是否已做相应处理。]
|
||||
|
||||
---
|
||||
*(对每个需要修改的文件重复上述格式)*
|
||||
|
||||
## Key Requirements
|
||||
1. **Language**: All output in Chinese
|
||||
2. **No Code Generation**: Use diff format or pseudo-code only. Do not write complete functions or files
|
||||
3. **Focus on Root Cause**: Analysis must be logical and evidence-based
|
||||
4. **State Assumptions**: Clearly note any assumptions when information is incomplete
|
||||
|
||||
## Self-Review Checklist
|
||||
Before providing final output, verify:
|
||||
- [ ] Diagnostic chain reflects logical debugging process
|
||||
- [ ] Root cause analysis is clear and evidence-based
|
||||
- [ ] Correction directly addresses root cause (not just symptoms)
|
||||
- [ ] Correction is minimal and targeted (not broad refactoring)
|
||||
- [ ] Verification steps are actionable
|
||||
- [ ] No complete code blocks generated
|
||||
@@ -0,0 +1,29 @@
|
||||
Analyze system architecture and design decisions.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Analyze system-wide structure, not just isolated components
|
||||
□ Provide file:line references for key architectural elements
|
||||
□ Distinguish between intended design and actual implementation
|
||||
□ Apply RULES template requirements exactly as specified
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Identify main architectural patterns and design principles
|
||||
2. Map module dependencies and component relationships
|
||||
3. Assess integration points and data flow patterns
|
||||
4. Evaluate scalability and maintainability aspects
|
||||
5. Document architectural trade-offs and design decisions
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Architectural diagrams or textual descriptions
|
||||
- Dependency mapping with specific file references
|
||||
- Integration point documentation with examples
|
||||
- Scalability assessment and bottleneck identification
|
||||
- Prioritized recommendations for architectural improvement
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ All major components and their relationships analyzed
|
||||
□ Key architectural decisions and trade-offs are documented
|
||||
□ Data flow and integration points are clearly mapped
|
||||
□ Scalability and maintainability findings are supported by evidence
|
||||
|
||||
Focus: High-level design patterns and system-wide architectural concerns.
|
||||
@@ -0,0 +1,28 @@
|
||||
Conduct comprehensive code review and quality assessment.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Review against established coding standards and conventions
|
||||
□ Assess logic correctness, including potential edge cases
|
||||
□ Evaluate security implications and vulnerability risks
|
||||
□ Check for performance bottlenecks and optimization opportunities
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Review code against established coding standards and conventions
|
||||
2. Assess logic correctness and potential edge cases
|
||||
3. Evaluate security implications and vulnerability risks
|
||||
4. Check performance characteristics and optimization opportunities
|
||||
5. Validate test coverage and documentation completeness
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Standards compliance assessment with specific violations
|
||||
- Logic review findings with potential issue identification
|
||||
- Security assessment with vulnerability documentation
|
||||
- Performance review with optimization recommendations
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Code is assessed against established standards
|
||||
□ Logic, including edge cases, is thoroughly reviewed
|
||||
□ Security and performance have been evaluated
|
||||
□ Test coverage and documentation are validated
|
||||
|
||||
Focus: Actionable feedback with clear improvement priorities and implementation guidance.
|
||||
@@ -0,0 +1,29 @@
|
||||
Analyze code quality and maintainability aspects.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Analyze against the project's established coding standards
|
||||
□ Provide file:line references for all quality issues
|
||||
□ Assess both implementation code and test coverage
|
||||
□ Apply RULES template requirements exactly as specified
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Assess code organization and structural quality
|
||||
2. Evaluate naming conventions and readability standards
|
||||
3. Review error handling and logging practices
|
||||
4. Analyze test coverage and testing strategies
|
||||
5. Document technical debt and improvement priorities
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Code quality metrics and specific improvement areas
|
||||
- Naming convention consistency analysis
|
||||
- Error handling and logging pattern documentation
|
||||
- Test coverage assessment with gap identification
|
||||
- Prioritized list of technical debt to address
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ All CONTEXT files analyzed for code quality
|
||||
□ Every finding is backed by a code reference (file:line)
|
||||
□ Both code and test quality have been evaluated
|
||||
□ Recommendations are prioritized by impact on maintainability
|
||||
|
||||
Focus: Maintainability improvements and long-term code health.
|
||||
@@ -0,0 +1,115 @@
|
||||
# AI Prompt: Code Analysis & Execution Tracing Expert (Chinese Output)
|
||||
|
||||
## I. PREAMBLE & CORE DIRECTIVE
|
||||
You are a **Senior Code Virtuoso & Debugging Strategist**. Your primary function is to conduct meticulous, systematic, and insightful analysis of provided source code. You are to understand its intricate structure, data flow, and control flow, and then provide exceptionally clear, accurate, and pedagogically sound answers to specific user questions related to that code. You excel at tracing execution paths, explaining complex interactions in a step-by-step "Chain-of-Thought" manner, and visually representing call logic. Your responses **MUST** be in **Chinese (中文)**.
|
||||
|
||||
## II. ROLE DEFINITION & CORE CAPABILITIES
|
||||
1. **Role**: Senior Code Virtuoso & Debugging Strategist.
|
||||
2. **Core Capabilities**:
|
||||
* **Deep Code Expertise**: Profound understanding of programming language syntax, semantics, execution models, standard library functions, common data structures, object-oriented programming (OOP), error handling, and idiomatic patterns.
|
||||
* **Systematic Code Analysis**: Ability to break down complex code into manageable parts, identify key components (functions, classes, variables, control structures), and understand their interrelationships.
|
||||
* **Logical Reasoning & Problem Solving**: Skill in deducing code behavior, identifying potential bugs or inefficiencies, and explaining the "why" behind the code's operation.
|
||||
* **Execution Path Tracing**: Expertise in mentally (or by simulated execution) stepping through code, tracking variable states and call stacks.
|
||||
* **Clear Communication**: Ability to explain technical concepts and code logic clearly and concisely to a developer audience, using precise terminology.
|
||||
* **Visual Representation**: Skill in creating simple, effective diagrams to illustrate call flows and data dependencies.
|
||||
3. **Adaptive Strategy**: While the following process is standard, you should adapt your analytical depth based on the complexity of the code and the specificity of the user's question.
|
||||
4. **Core Thinking Mode**:
|
||||
* **Systematic & Rigorous**: Approach every analysis with a structured methodology.
|
||||
* **Insightful & Deep**: Go beyond surface-level explanations; uncover underlying logic and potential implications.
|
||||
* **Chain-of-Thought (CoT) Driven**: Explicitly articulate your reasoning process.
|
||||
|
||||
## III. OBJECTIVES
|
||||
1. **Deeply Analyze**: Scrutinize the structure, syntax, control flow, data flow, and logic of the provided source code.
|
||||
2. **Comprehend Questions**: Thoroughly understand the user's specific question(s) regarding the code, identifying the core intent.
|
||||
3. **Accurate & Comprehensive Answers**: Provide precise, complete, and logically sound answers.
|
||||
4. **Elucidate Logic**: Clearly explain the code calling logic, dependencies, and data flow relevant to the question, both textually (step-by-step) and visually.
|
||||
5. **Structured Presentation**: Present explanations in a highly structured and easy-to-understand format (Markdown), highlighting key code segments, their interactions, and a concise call flow diagram.
|
||||
6. **Pedagogical Value**: Ensure explanations are not just correct but also help the user learn about the code's behavior in the given context.
|
||||
7. **Show Your Work (CoT)**: Crucially, before the main analysis, outline your thinking process, assumptions, and how you plan to tackle the question.
|
||||
|
||||
## IV. INPUT SPECIFICATIONS
|
||||
1. **Code Snippet**: A block of source code provided as text.
|
||||
2. **Specific Question(s)**: One or more questions directly related to the provided code snippet.
|
||||
|
||||
## V. RESPONSE STRUCTURE & CONTENT (Strictly Adhere - Output in Chinese)
|
||||
|
||||
Your response **MUST** be in Chinese and structured in Markdown as follows:
|
||||
|
||||
---
|
||||
|
||||
### 0. 思考过程 (Thinking Process)
|
||||
* *(Before any analysis, outline your key thought process for tackling the question(s). For example: "1. Identify target functions/variables from the question. 2. Trace execution flow related to these. 3. Note data transformations. 4. Formulate a concise answer. 5. Detail the steps and create a diagram.")*
|
||||
* *(List any initial assumptions made about the code or standard library behavior.)*
|
||||
|
||||
### 1. 对问题的理解 (Understanding of the Question)
|
||||
* 简明扼要地复述或重申用户核心问题,确认理解无误。
|
||||
|
||||
### 2. 核心解答 (Core Answer)
|
||||
* 针对每个问题,提供直接、简洁的答案。
|
||||
|
||||
### 3. 详细分析与调用逻辑 (Detailed Analysis and Calling Logic)
|
||||
|
||||
#### 3.1. 相关代码段识别 (Identification of Relevant Code Sections)
|
||||
* 精确定位解答问题所必须的关键函数、方法、类或代码块。
|
||||
* 使用带语言标识的Markdown代码块 (e.g., ```python ... ```) 展示这些片段。
|
||||
|
||||
#### 3.2. 文本化执行流程/调用顺序 (Textual Execution Flow / Calling Sequence)
|
||||
* 提供逐步的文本解释,说明相关代码如何执行,函数/方法如何相互调用,以及数据(参数、返回值)如何传递。
|
||||
* 明确指出控制流(如循环、条件判断)如何影响执行。
|
||||
|
||||
#### 3.3. 简洁调用图 (Concise Call Flow Diagram)
|
||||
* 使用缩进、箭头 (例如: `───►` 调用, `◄───` 返回, `│` 持续, `├─` 中间步骤, `└─` 块内最后步骤) 和其他简洁符号,清晰地可视化函数调用层级和与问题相关的关键操作/数据转换。
|
||||
* 此图应作为文本解释的补充,增强理解。
|
||||
* **示例图例参考**:
|
||||
```
|
||||
main()
|
||||
│
|
||||
├─► helper_function1(arg1)
|
||||
│ │
|
||||
│ ├─ (内部逻辑/数据操作)
|
||||
│ │
|
||||
│ └─► another_function(data)
|
||||
│ │
|
||||
│ └─ (返回结果) ◄─── result_from_another
|
||||
│
|
||||
│ └─ (返回结果) ◄─── result_from_helper1
|
||||
│
|
||||
└─► helper_function2()
|
||||
...
|
||||
```
|
||||
|
||||
#### 3.4. 详细数据传递与状态变化 (Detailed Data Passing and State Changes)
|
||||
* 结合调用图,详细说明具体数据值(参数、返回值、关键变量)如何在函数/方法间传递,以及在与问题相关的执行过程中变量状态如何变化。
|
||||
* 关注特定语言的数据传递机制 (e.g., pass-by-value, pass-by-reference).
|
||||
|
||||
#### 3.5. 逻辑解释 (Logical Explanation)
|
||||
* 解释为什么代码会这样运行,将其与用户的具体问题联系起来,并结合编程语言特性进行说明。
|
||||
|
||||
### 4. 总结 (Summary - 复杂问题推荐)
|
||||
* 根据详细分析,简要总结关键发现或问题的答案。
|
||||
|
||||
---
|
||||
|
||||
## VI. STYLE & TONE (Chinese Output)
|
||||
* **Professional & Technical**: Maintain a formal, expert tone.
|
||||
* **Analytical & Pedagogical**: Focus on insightful analysis and clear explanations.
|
||||
* **Precise Terminology**: Use correct technical terms.
|
||||
* **Clarity & Structure**: Employ lists, bullet points, Markdown code blocks, and the specified diagramming symbols for maximum clarity.
|
||||
* **Helpful & Informative**: The goal is to assist and educate.
|
||||
|
||||
## VII. CONSTRAINTS & PROHIBITED BEHAVIORS
|
||||
1. **Confine Analysis**: Your analysis MUST be strictly confined to the provided code snippet.
|
||||
2. **Standard Library Assumption**: Assume standard library functions behave as documented unless their implementation is part of the provided code.
|
||||
3. **No External Knowledge**: Do not use external knowledge beyond standard libraries unless explicitly provided in the context.
|
||||
4. **No Speculation**: Avoid speculative answers. If information is insufficient to provide a definitive answer based *solely* on the provided code, clearly state what information is missing.
|
||||
5. **No Generic Tutorials**: Do not provide generic tutorials or explanations of basic syntax unless it's directly essential for explaining the specific behavior in the provided code relevant to the user's question.
|
||||
6. **Focus on Code Context**: Always frame explanations within the context of the specific implementation and behavior.
|
||||
|
||||
## VIII. SELF-CORRECTION / REFLECTION
|
||||
* Before finalizing your response, review it to ensure:
|
||||
* All parts of the user's question(s) have been addressed.
|
||||
* The analysis is accurate and logically sound.
|
||||
* The textual explanation and the call flow diagram are consistent and mutually reinforcing.
|
||||
* The language used is precise, clear, and professional (Chinese).
|
||||
* All formatting requirements have been met.
|
||||
* The "Thinking Process" (CoT) is clearly articulated.
|
||||
@@ -0,0 +1,55 @@
|
||||
Debug and resolve issues systematically in the codebase.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Identify and reproduce the issue completely before fixing
|
||||
□ Perform root cause analysis (not just symptom treatment)
|
||||
□ Provide file:line references for all changes
|
||||
□ Add tests to prevent regression of this specific issue
|
||||
|
||||
## IMPLEMENTATION PHASES
|
||||
|
||||
### Issue Analysis Phase
|
||||
1. Identify and reproduce the reported issue
|
||||
2. Analyze error logs and stack traces
|
||||
3. Study code flow and identify potential failure points
|
||||
4. Review recent changes that might have introduced the issue
|
||||
|
||||
### Investigation Phase
|
||||
1. Add strategic logging and debugging statements
|
||||
2. Use debugging tools and profilers as appropriate
|
||||
3. Test with different input conditions and edge cases
|
||||
4. Isolate the root cause through systematic elimination
|
||||
|
||||
### Root Cause Analysis
|
||||
1. Document the exact cause of the issue
|
||||
2. Identify contributing factors and conditions
|
||||
3. Assess impact scope and affected functionality
|
||||
4. Determine if similar issues exist elsewhere
|
||||
|
||||
### Resolution Phase
|
||||
1. Implement minimal, targeted fix for the root cause
|
||||
2. Ensure fix doesn't introduce new issues or regressions
|
||||
3. Add proper error handling and validation
|
||||
4. Include defensive programming measures
|
||||
|
||||
### Prevention Phase
|
||||
1. Add tests to prevent regression of this issue
|
||||
2. Improve error messages and logging
|
||||
3. Add monitoring or alerts for early detection
|
||||
4. Document lessons learned and prevention strategies
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Detailed root cause analysis with file:line references
|
||||
- Exact code changes made to resolve the issue
|
||||
- New tests added to prevent regression
|
||||
- Debugging process documentation and lessons learned
|
||||
- Impact assessment and affected functionality
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Root cause identified and documented (not just symptoms)
|
||||
□ Minimal fix applied without introducing new issues
|
||||
□ Tests added to prevent this specific regression
|
||||
□ Similar issues checked and addressed if found
|
||||
□ Prevention measures documented
|
||||
|
||||
Focus: Systematic root cause resolution with regression prevention.
|
||||
@@ -0,0 +1,70 @@
|
||||
Create comprehensive tests for the codebase.
|
||||
|
||||
## Planning Required
|
||||
Before creating tests, you MUST:
|
||||
1. Analyze existing test coverage and identify gaps
|
||||
2. Study testing frameworks and conventions used
|
||||
3. Plan test strategy covering unit, integration, and e2e
|
||||
4. Design test data management approach
|
||||
|
||||
## Core Checklist
|
||||
- [ ] Analyze coverage gaps
|
||||
- [ ] Follow testing frameworks and conventions
|
||||
- [ ] Include unit, integration, and e2e tests
|
||||
- [ ] Ensure tests are reliable and deterministic
|
||||
|
||||
## IMPLEMENTATION PHASES
|
||||
|
||||
### Test Strategy Phase
|
||||
1. Analyze existing test coverage and identify gaps
|
||||
2. Study codebase architecture and critical paths
|
||||
3. Identify edge cases and error scenarios
|
||||
4. Review testing frameworks and conventions used
|
||||
|
||||
### Unit Testing Phase
|
||||
1. Write tests for individual functions and methods
|
||||
2. Test all branches and conditional logic
|
||||
3. Cover edge cases and boundary conditions
|
||||
4. Mock external dependencies appropriately
|
||||
|
||||
### Integration Testing Phase
|
||||
1. Test interactions between components and modules
|
||||
2. Verify API endpoints and data flow
|
||||
3. Test database operations and transactions
|
||||
4. Validate external service integrations
|
||||
|
||||
### End-to-End Testing Phase
|
||||
1. Test complete user workflows and scenarios
|
||||
2. Verify critical business logic and processes
|
||||
3. Test error handling and recovery mechanisms
|
||||
4. Validate performance under load
|
||||
|
||||
### Quality Assurance
|
||||
1. Ensure tests are reliable and deterministic
|
||||
2. Make tests readable and maintainable
|
||||
3. Add proper test documentation and comments
|
||||
4. Follow testing best practices and conventions
|
||||
|
||||
### Test Data Management
|
||||
1. Create realistic test data and fixtures
|
||||
2. Ensure test isolation and cleanup
|
||||
3. Use factories or builders for complex objects
|
||||
4. Handle sensitive data appropriately in tests
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Comprehensive test suite with high coverage
|
||||
- Performance benchmarks where relevant
|
||||
- Testing strategy and conventions documentation
|
||||
- Test coverage metrics and quality improvements
|
||||
- File:line references for tested code
|
||||
|
||||
## Verification Checklist
|
||||
Before finalizing, verify:
|
||||
- [ ] Coverage gaps filled
|
||||
- [ ] All test types included
|
||||
- [ ] Tests are reliable (no flaky tests)
|
||||
- [ ] Test data properly managed
|
||||
- [ ] Conventions followed
|
||||
|
||||
## Focus
|
||||
High-quality, reliable test suite with comprehensive coverage.
|
||||
@@ -0,0 +1,55 @@
|
||||
Create a reusable component following project conventions and best practices.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Analyze existing component patterns BEFORE implementing
|
||||
□ Follow established naming conventions and prop patterns
|
||||
□ Include comprehensive tests (unit + visual + accessibility)
|
||||
□ Provide complete TypeScript types and documentation
|
||||
|
||||
## IMPLEMENTATION PHASES
|
||||
|
||||
### Design Phase
|
||||
1. Analyze existing component patterns and structures
|
||||
2. Identify reusable design principles and styling approaches
|
||||
3. Review component hierarchy and prop patterns
|
||||
4. Study existing component documentation and usage
|
||||
|
||||
### Development Phase
|
||||
1. Create component with proper TypeScript interfaces
|
||||
2. Implement following established naming conventions
|
||||
3. Add appropriate default props and validation
|
||||
4. Include comprehensive prop documentation
|
||||
|
||||
### Styling Phase
|
||||
1. Follow existing styling methodology (CSS modules, styled-components, etc.)
|
||||
2. Ensure responsive design principles
|
||||
3. Add proper theming support if applicable
|
||||
4. Include accessibility considerations (ARIA, keyboard navigation)
|
||||
|
||||
### Testing Phase
|
||||
1. Write component tests covering all props and states
|
||||
2. Test accessibility compliance
|
||||
3. Add visual regression tests if applicable
|
||||
4. Test component in different contexts and layouts
|
||||
|
||||
### Documentation Phase
|
||||
1. Create usage examples and code snippets
|
||||
2. Document all props and their purposes
|
||||
3. Include accessibility guidelines
|
||||
4. Add integration examples with other components
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Complete component implementation with TypeScript types
|
||||
- Usage examples and integration patterns
|
||||
- Component API documentation and best practices
|
||||
- Test suite with accessibility validation
|
||||
- File:line references for pattern sources
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Implementation follows existing component patterns
|
||||
□ Complete TypeScript types and prop documentation
|
||||
□ Comprehensive tests (unit + visual + accessibility)
|
||||
□ Accessibility compliance (ARIA, keyboard navigation)
|
||||
□ Usage examples and integration documented
|
||||
|
||||
Focus: Production-ready reusable component with comprehensive documentation and testing.
|
||||
@@ -0,0 +1,58 @@
|
||||
Implement a new feature following project conventions and best practices.
|
||||
|
||||
## Planning Required
|
||||
Before implementing, you MUST:
|
||||
1. Study existing code patterns and conventions
|
||||
2. Review project architecture and design principles
|
||||
3. Plan implementation with error handling and tests
|
||||
4. Document integration points and dependencies
|
||||
|
||||
## Core Checklist
|
||||
- [ ] Study existing code patterns first
|
||||
- [ ] Follow project conventions and architecture
|
||||
- [ ] Include comprehensive tests
|
||||
- [ ] Provide file:line references
|
||||
|
||||
## IMPLEMENTATION PHASES
|
||||
|
||||
### Analysis Phase
|
||||
1. Study existing code patterns and conventions
|
||||
2. Identify similar features and their implementation approaches
|
||||
3. Review project architecture and design principles
|
||||
4. Understand dependencies and integration points
|
||||
|
||||
### Implementation Phase
|
||||
1. Create feature following established patterns
|
||||
2. Implement with proper error handling and validation
|
||||
3. Add comprehensive logging for debugging
|
||||
4. Follow security best practices
|
||||
|
||||
### Integration Phase
|
||||
1. Ensure seamless integration with existing systems
|
||||
2. Update configuration files as needed
|
||||
3. Add proper TypeScript types and interfaces
|
||||
4. Update documentation and comments
|
||||
|
||||
### Testing Phase
|
||||
1. Write unit tests covering edge cases
|
||||
2. Add integration tests for feature workflows
|
||||
3. Verify error scenarios are properly handled
|
||||
4. Test performance and security implications
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- File:line references for all changes
|
||||
- Code examples demonstrating key patterns
|
||||
- Explanation of architectural decisions made
|
||||
- Documentation of new dependencies or configurations
|
||||
- Test coverage summary
|
||||
|
||||
## Verification Checklist
|
||||
Before finalizing, verify:
|
||||
- [ ] Follows existing patterns
|
||||
- [ ] Complete test coverage
|
||||
- [ ] Documentation updated
|
||||
- [ ] No breaking changes
|
||||
- [ ] Security and performance validated
|
||||
|
||||
## Focus
|
||||
Production-ready implementation with comprehensive testing and documentation.
|
||||
@@ -0,0 +1,55 @@
|
||||
Refactor existing code to improve quality, performance, or maintainability.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Preserve existing functionality (no behavioral changes unless specified)
|
||||
□ Ensure all existing tests continue to pass
|
||||
□ Plan incremental changes (avoid big-bang refactoring)
|
||||
□ Provide file:line references for all modifications
|
||||
|
||||
## IMPLEMENTATION PHASES
|
||||
|
||||
### Analysis Phase
|
||||
1. Identify code smells and technical debt
|
||||
2. Analyze performance bottlenecks and inefficiencies
|
||||
3. Review code complexity and maintainability metrics
|
||||
4. Study existing test coverage and identify gaps
|
||||
|
||||
### Planning Phase
|
||||
1. Create refactoring strategy preserving existing functionality
|
||||
2. Identify breaking changes and migration paths
|
||||
3. Plan incremental refactoring steps
|
||||
4. Consider backward compatibility requirements
|
||||
|
||||
### Refactoring Phase
|
||||
1. Apply SOLID principles and design patterns
|
||||
2. Improve code readability and documentation
|
||||
3. Optimize performance while maintaining functionality
|
||||
4. Reduce code duplication and improve reusability
|
||||
|
||||
### Validation Phase
|
||||
1. Ensure all existing tests continue to pass
|
||||
2. Add new tests for improved code coverage
|
||||
3. Verify performance improvements with benchmarks
|
||||
4. Test edge cases and error scenarios
|
||||
|
||||
### Migration Phase
|
||||
1. Update dependent code to use refactored interfaces
|
||||
2. Update documentation and usage examples
|
||||
3. Provide migration guides for breaking changes
|
||||
4. Add deprecation warnings for old interfaces
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Before/after code comparisons with file:line references
|
||||
- Performance improvements documented with benchmarks
|
||||
- Migration instructions for breaking changes
|
||||
- Updated test coverage and quality metrics
|
||||
- Technical debt reduction summary
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ All existing tests pass (functionality preserved)
|
||||
□ New tests added for improved coverage
|
||||
□ Performance verified with benchmarks (if applicable)
|
||||
□ Backward compatibility maintained or migration provided
|
||||
□ Documentation updated with refactoring changes
|
||||
|
||||
Focus: Incremental quality improvement while preserving functionality.
|
||||
15
.ccw/workflows/cli-templates/prompts/documentation-api.txt
Normal file
15
.ccw/workflows/cli-templates/prompts/documentation-api.txt
Normal file
@@ -0,0 +1,15 @@
|
||||
Generate comprehensive API documentation for code or HTTP services.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Include only sections relevant to the project type (Code API vs. HTTP API)
|
||||
□ Provide complete and runnable examples for HTTP APIs
|
||||
□ Use signatures-only for Code API documentation (no implementation)
|
||||
□ Document all public-facing APIs, not internal ones
|
||||
|
||||
## UNIFIED API DOCUMENTATION TEMPLATE
|
||||
|
||||
This template supports both **Code API** (for libraries/modules) and **HTTP API** (for web services). Include only the sections relevant to your project type.
|
||||
|
||||
---
|
||||
|
||||
...(content truncated)...
|
||||
@@ -0,0 +1,27 @@
|
||||
Generate a navigation README for directories that contain only subdirectories.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Keep the content brief and act as an index
|
||||
□ Use one-line descriptions for each module
|
||||
□ Ensure all mentioned modules link to their respective READMEs
|
||||
□ Use scannable formats like tables and lists
|
||||
|
||||
## REQUIRED CONTENT
|
||||
1. **Overview**: Brief description of the directory's purpose.
|
||||
2. **Directory Structure**: A tree view of subdirectories with one-line descriptions.
|
||||
3. **Module Quick Reference**: A table with links, purposes, and key features.
|
||||
4. **How to Navigate**: Guidance on which module to explore for specific needs.
|
||||
5. **Module Relationships (Optional)**: A simple diagram showing dependencies.
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- A scannable index for navigating subdirectories.
|
||||
- Links to each submodule's detailed documentation.
|
||||
- A clear, high-level overview of the directory's contents.
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ The generated README is brief and serves as a scannable index
|
||||
□ All submodules are linked correctly
|
||||
□ Descriptions are concise and clear
|
||||
□ The structure follows the required content outline
|
||||
|
||||
Focus: Creating a clear and concise navigation hub for parent directories.
|
||||
@@ -0,0 +1,49 @@
|
||||
Generate module documentation focused on understanding and usage.
|
||||
|
||||
## Planning Required
|
||||
Before providing documentation, you MUST:
|
||||
1. Understand what the module does and why it exists
|
||||
2. Review existing documentation to avoid duplication
|
||||
3. Prepare practical usage examples
|
||||
4. Identify module boundaries and dependencies
|
||||
|
||||
## Core Checklist
|
||||
- [ ] Explain WHAT, WHY, and HOW
|
||||
- [ ] Reference API.md instead of duplicating signatures
|
||||
- [ ] Include practical usage examples
|
||||
- [ ] Define module boundaries and dependencies
|
||||
|
||||
## DOCUMENTATION STRUCTURE
|
||||
|
||||
### 1. Purpose
|
||||
- **What**: Clearly state what this module is responsible for.
|
||||
- **Why**: Explain the problem it solves.
|
||||
- **Boundaries**: Define what is in and out of scope.
|
||||
|
||||
### 2. Core Concepts
|
||||
- Explain key concepts, patterns, or abstractions.
|
||||
|
||||
### 3. Usage Scenarios
|
||||
- Provide 2-4 common use cases with code examples.
|
||||
|
||||
### 4. Dependencies
|
||||
- List internal and external dependencies with explanations.
|
||||
|
||||
### 5. Configuration
|
||||
- Document environment variables and configuration options.
|
||||
|
||||
### 6. Testing
|
||||
- Explain how to run tests for the module.
|
||||
|
||||
### 7. Common Issues
|
||||
- List common problems and their solutions.
|
||||
|
||||
## Verification Checklist
|
||||
Before finalizing output, verify:
|
||||
- [ ] Module purpose, scope, and boundaries are clear
|
||||
- [ ] Core concepts are explained
|
||||
- [ ] Usage examples are practical and realistic
|
||||
- [ ] Dependencies and configuration are documented
|
||||
|
||||
## Focus
|
||||
Explain module purpose and usage, not just API details.
|
||||
@@ -0,0 +1,41 @@
|
||||
Generate comprehensive architecture documentation for the entire project.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Synthesize information from all modules; do not duplicate content
|
||||
□ Maintain a system-level perspective, focusing on module interactions
|
||||
□ Use visual aids (like ASCII diagrams) to clarify structure
|
||||
□ Explain the WHY behind architectural decisions
|
||||
|
||||
## DOCUMENTATION STRUCTURE
|
||||
|
||||
### 1. System Overview
|
||||
- Architectural Style, Core Principles, and Technology Stack.
|
||||
|
||||
### 2. System Structure
|
||||
- Visual representation of the system's layers or components.
|
||||
|
||||
### 3. Module Map
|
||||
- A table listing all modules, their layers, responsibilities, and dependencies.
|
||||
|
||||
### 4. Module Interactions
|
||||
- Describe key data flows and show a dependency graph.
|
||||
|
||||
### 5. Design Patterns
|
||||
- Document key architectural patterns used across the project.
|
||||
|
||||
### 6. Aggregated API Overview
|
||||
- A high-level summary of all public APIs, grouped by category.
|
||||
|
||||
### 7. Data Flow
|
||||
- Describe the typical request lifecycle or event flow.
|
||||
|
||||
### 8. Security and Scalability
|
||||
- Overview of security measures and scalability considerations.
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ The documentation provides a cohesive, system-level view
|
||||
□ Module interactions and dependencies are clearly illustrated
|
||||
□ The rationale behind major design patterns and decisions is explained
|
||||
□ The document synthesizes, rather than duplicates, module-level details
|
||||
|
||||
Focus: Providing a holistic, system-level understanding of the project architecture.
|
||||
@@ -0,0 +1,35 @@
|
||||
Generate practical, end-to-end examples demonstrating core project usage.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Provide complete, runnable code for every example
|
||||
□ Focus on realistic, real-world scenarios, not trivial cases
|
||||
□ Explain the flow and how different modules interact
|
||||
□ Include expected output to verify correctness
|
||||
|
||||
## EXAMPLES STRUCTURE
|
||||
|
||||
### 1. Introduction
|
||||
- Overview of the examples and any prerequisites.
|
||||
|
||||
### 2. Quick Start Example
|
||||
- The simplest possible working example to verify setup.
|
||||
|
||||
### 3. Core Use Cases
|
||||
- 3-5 complete examples for common scenarios with code, output, and explanations.
|
||||
|
||||
### 4. Advanced & Integration Examples
|
||||
- Showcase more complex scenarios or integrations with external systems.
|
||||
|
||||
### 5. Testing Examples
|
||||
- Show how to test code that uses the project.
|
||||
|
||||
### 6. Best Practices & Troubleshooting
|
||||
- Demonstrate recommended patterns and provide solutions to common issues.
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ All examples are complete, runnable, and tested
|
||||
□ Scenarios are realistic and demonstrate key project features
|
||||
□ Explanations clarify module interactions and data flow
|
||||
□ Best practices and error handling are demonstrated
|
||||
|
||||
Focus: Helping users accomplish common tasks through complete, practical examples.
|
||||
@@ -0,0 +1,35 @@
|
||||
Generate a comprehensive project-level README documentation.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Clearly state the project's purpose and target audience
|
||||
□ Provide clear, runnable instructions for getting started
|
||||
□ Outline the development workflow and coding standards
|
||||
□ Offer a high-level overview of the project structure and architecture
|
||||
|
||||
## README STRUCTURE
|
||||
|
||||
### 1. Overview
|
||||
- Purpose, Target Audience, and Key Features.
|
||||
|
||||
### 2. System Architecture
|
||||
- Architectural Style, Core Components, Tech Stack, and Design Principles.
|
||||
|
||||
### 3. Getting Started
|
||||
- Prerequisites, Installation, Configuration, and Running the Project.
|
||||
|
||||
### 4. Development Workflow
|
||||
- Branching Strategy, Coding Standards, Testing, and Build/Deployment.
|
||||
|
||||
### 5. Project Structure
|
||||
- A high-level tree view of the main directories.
|
||||
|
||||
### 6. Navigation
|
||||
- Links to more detailed documentation (modules, API, architecture).
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ The project's purpose and value proposition are clear
|
||||
□ A new developer can successfully set up and run the project
|
||||
□ The development process and standards are well-defined
|
||||
□ The README provides clear navigation to other key documents
|
||||
|
||||
Focus: Providing a central entry point for new users and developers to understand and run the project.
|
||||
@@ -0,0 +1,266 @@
|
||||
生成符合 RESTful 规范的完整 Swagger/OpenAPI API 文档。
|
||||
|
||||
## 核心检查清单 ⚡
|
||||
□ 严格遵循 RESTful API 设计规范
|
||||
□ 每个接口必须包含：功能描述、请求方法、URL路径、参数说明
|
||||
□ 必须包含全局 Security 配置（Authorization Bearer Token）
|
||||
□ 使用中文命名目录，保持层级清晰
|
||||
□ 每个字段需注明：类型、是否必填、示例值、说明
|
||||
□ 包含成功和失败的响应示例
|
||||
□ 标注接口版本和最后更新时间
|
||||
|
||||
## OpenAPI 规范结构
|
||||
|
||||
### 1. 文档信息 (info)
|
||||
```yaml
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: {项目名称} API
|
||||
description: |
|
||||
{项目描述}
|
||||
|
||||
## 认证方式
|
||||
所有需要认证的接口必须在请求头中携带 Bearer Token：
|
||||
```
|
||||
Authorization: Bearer <your-token>
|
||||
```
|
||||
version: "1.0.0"
|
||||
contact:
|
||||
name: API 支持
|
||||
email: api-support@example.com
|
||||
license:
|
||||
name: MIT
|
||||
```
|
||||
|
||||
### 2. 服务器配置 (servers)
|
||||
```yaml
|
||||
servers:
|
||||
- url: https://api.example.com/v1
|
||||
description: 生产环境
|
||||
- url: https://staging-api.example.com/v1
|
||||
description: 测试环境
|
||||
- url: http://localhost:3000/v1
|
||||
description: 开发环境
|
||||
```
|
||||
|
||||
### 3. 全局安全配置 (security)
|
||||
```yaml
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT Token 认证
|
||||
|
||||
获取方式：调用 POST /auth/login 接口
|
||||
有效期：24小时
|
||||
刷新：调用 POST /auth/refresh 接口
|
||||
|
||||
security:
|
||||
- bearerAuth: []
|
||||
```
|
||||
|
||||
### 4. 接口路径规范 (paths)
|
||||
```yaml
|
||||
paths:
|
||||
/users:
|
||||
get:
|
||||
tags:
|
||||
- 用户管理
|
||||
summary: 获取用户列表
|
||||
description: |
|
||||
分页获取系统用户列表，支持按状态、角色筛选。
|
||||
|
||||
**适用环境**: 开发、测试、生产
|
||||
**前置条件**: 需要管理员权限
|
||||
operationId: listUsers
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
default: 1
|
||||
minimum: 1
|
||||
description: 页码（从1开始）
|
||||
example: 1
|
||||
- name: limit
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
default: 20
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
description: 每页数量
|
||||
example: 20
|
||||
responses:
|
||||
'200':
|
||||
description: 成功获取用户列表
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserListResponse'
|
||||
example:
|
||||
code: 0
|
||||
message: success
|
||||
data:
|
||||
items:
|
||||
- id: "usr_123"
|
||||
email: "user@example.com"
|
||||
name: "张三"
|
||||
total: 100
|
||||
page: 1
|
||||
limit: 20
|
||||
'401':
|
||||
$ref: '#/components/responses/UnauthorizedError'
|
||||
'403':
|
||||
$ref: '#/components/responses/ForbiddenError'
|
||||
```
|
||||
|
||||
### 5. 数据模型规范 (schemas)
|
||||
```yaml
|
||||
components:
|
||||
schemas:
|
||||
# 基础响应结构
|
||||
BaseResponse:
|
||||
type: object
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- timestamp
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
description: 业务状态码，0表示成功
|
||||
example: 0
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: success
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
description: 响应时间戳
|
||||
example: "2025-01-01T12:00:00Z"
|
||||
|
||||
# 错误响应
|
||||
ErrorResponse:
|
||||
type: object
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
description: 错误码
|
||||
example: "AUTH_001"
|
||||
message:
|
||||
type: string
|
||||
description: 错误信息
|
||||
example: "Token 无效或已过期"
|
||||
details:
|
||||
type: object
|
||||
description: 错误详情
|
||||
additionalProperties: true
|
||||
```
|
||||
|
||||
### 6. 统一响应定义 (responses)
|
||||
```yaml
|
||||
components:
|
||||
responses:
|
||||
UnauthorizedError:
|
||||
description: 认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "AUTH_001"
|
||||
message: "Token 无效或已过期"
|
||||
ForbiddenError:
|
||||
description: 权限不足
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "AUTH_003"
|
||||
message: "权限不足，需要管理员角色"
|
||||
NotFoundError:
|
||||
description: 资源不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "BIZ_002"
|
||||
message: "资源不存在"
|
||||
ValidationError:
|
||||
description: 参数验证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "PARAM_001"
|
||||
message: "参数格式错误"
|
||||
details:
|
||||
field: "email"
|
||||
reason: "邮箱格式不正确"
|
||||
```
|
||||
|
||||
## 接口文档必填项
|
||||
|
||||
每个接口必须包含：
|
||||
|
||||
1. **基本信息**
|
||||
- tags: 所属模块（中文）
|
||||
- summary: 一句话描述
|
||||
- description: 详细说明（含适用环境、前置条件）
|
||||
- operationId: 唯一操作标识
|
||||
|
||||
2. **安全配置**
|
||||
- security: 认证要求
|
||||
|
||||
3. **参数定义**
|
||||
- name: 参数名
|
||||
- in: 位置 (path/query/header/cookie)
|
||||
- required: 是否必填
|
||||
- schema: 类型定义（含 default, minimum, maximum）
|
||||
- description: 参数说明
|
||||
- example: 示例值
|
||||
|
||||
4. **响应定义**
|
||||
- 200: 成功响应（含完整示例）
|
||||
- 400: 参数错误
|
||||
- 401: 认证失败
|
||||
- 403: 权限不足
|
||||
- 404: 资源不存在（如适用）
|
||||
- 500: 服务器错误
|
||||
|
||||
5. **版本信息**
|
||||
- x-version: 接口版本
|
||||
- x-updated: 最后更新时间
|
||||
|
||||
## 错误码规范
|
||||
|
||||
| 前缀 | 类别 | HTTP状态码 | 说明 |
|
||||
|------|------|------------|------|
|
||||
| AUTH_ | 认证错误 | 401/403 | 身份验证相关 |
|
||||
| PARAM_ | 参数错误 | 400 | 请求参数验证 |
|
||||
| BIZ_ | 业务错误 | 409/422 | 业务逻辑相关 |
|
||||
| SYS_ | 系统错误 | 500/503 | 服务器异常 |
|
||||
|
||||
## RESTful 设计规范
|
||||
|
||||
1. **URL 命名**: 使用复数名词，小写，连字符分隔
|
||||
2. **HTTP 方法**: GET(查询)、POST(创建)、PUT(更新)、DELETE(删除)、PATCH(部分更新)
|
||||
3. **状态码**: 正确使用 2xx/3xx/4xx/5xx
|
||||
4. **分页**: 使用 page/limit 或 offset/limit
|
||||
5. **筛选**: 使用查询参数
|
||||
6. **版本**: URL 路径 (/v1/) 或 请求头
|
||||
@@ -0,0 +1,165 @@
|
||||
Create or update CLAUDE.md documentation using unified module/file template.
|
||||
|
||||
## ⚠️ FILE NAMING RULE (CRITICAL)
|
||||
- Target file: MUST be named exactly `CLAUDE.md` in the current directory
|
||||
- NEVER create files like `ToolSidebar.CLAUDE.md` or `[filename].CLAUDE.md`
|
||||
- ALWAYS use the fixed name: `CLAUDE.md`
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ MUST create/update file named exactly 'CLAUDE.md' (not variants)
|
||||
□ MUST include all 6 sections: Purpose, Structure, Components, Dependencies, Integration, Implementation
|
||||
□ For code files: Document all public/exported APIs with complete parameter details
|
||||
□ For folders: Reference subdirectory CLAUDE.md files instead of duplicating
|
||||
□ Provide method signatures with parameter types, descriptions, defaults, and return values
|
||||
□ Distinguish internal dependencies from external libraries
|
||||
□ Apply RULES template requirements exactly as specified
|
||||
|
||||
## DOCUMENTATION REQUIREMENTS
|
||||
|
||||
### Analysis Strategy
|
||||
- **Folders/Modules**: Analyze directory structure, sub-modules, and architectural patterns
|
||||
- **Code Files**: Analyze classes, functions, interfaces, and implementation details
|
||||
|
||||
### Required Sections (ALL 6 MUST BE INCLUDED)
|
||||
|
||||
#### 1. Purpose and Scope
|
||||
- Clear description of what this module/file does
|
||||
- Main responsibilities and boundaries
|
||||
- Role within the larger system
|
||||
|
||||
#### 2. Structure Overview
|
||||
**For Folders**: Directory organization, sub-module categorization, architectural layout
|
||||
**For Code Files**: File organization (imports, exports), class hierarchy, function grouping
|
||||
|
||||
#### 3. Key Components
|
||||
**For Folders**: Sub-modules, major components, entry points, public interfaces
|
||||
**For Code Files**:
|
||||
- Core classes with descriptions and responsibilities
|
||||
- Key methods with complete signatures:
|
||||
```
|
||||
methodName(param1: Type1, param2: Type2): ReturnType
|
||||
- Purpose: [what it does]
|
||||
- Parameters:
|
||||
• param1 (Type1): [description] [default: value]
|
||||
• param2 (Type2): [description] [optional]
|
||||
- Returns: (ReturnType) [description]
|
||||
- Throws: [exception types and conditions]
|
||||
- Example: [usage example for complex methods]
|
||||
```
|
||||
- Important interfaces/types
|
||||
- Exported APIs
|
||||
|
||||
#### 4. Dependencies
|
||||
**Internal Dependencies**: Other modules/files within project (with purpose)
|
||||
**External Dependencies**: Third-party libraries and frameworks (with purpose, version constraints if critical)
|
||||
|
||||
#### 5. Integration Points
|
||||
- How this connects to other parts
|
||||
- Public APIs or interfaces exposed
|
||||
- Data flow patterns (input → processing → output)
|
||||
- Event handling or callbacks
|
||||
- Extension points for customization
|
||||
|
||||
#### 6. Implementation Notes
|
||||
- Key design patterns used (e.g., Singleton, Factory, Observer)
|
||||
- Important technical decisions and rationale
|
||||
- Configuration requirements or environment variables
|
||||
- Performance considerations
|
||||
- Security considerations if applicable
|
||||
- Known limitations or caveats
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
|
||||
### File Naming (CRITICAL)
|
||||
- **Output file**: MUST be named exactly `CLAUDE.md` in the current directory
|
||||
- **Examples of WRONG naming**: `ToolSidebar.CLAUDE.md`, `index.CLAUDE.md`, `utils.CLAUDE.md`
|
||||
- **Correct naming**: `CLAUDE.md` (always, for all directories)
|
||||
|
||||
### Template Structure
|
||||
```markdown
|
||||
# [Module/File Name]
|
||||
|
||||
## Purpose and Scope
|
||||
[Clear description of responsibilities and role]
|
||||
|
||||
## Structure Overview
|
||||
[Directory structure for modules OR File organization for code files]
|
||||
|
||||
## Key Components
|
||||
### [Component/Class Name]
|
||||
- Description: [Brief description]
|
||||
- Responsibilities: [What it does]
|
||||
- Key Methods:
|
||||
#### `methodName(param1: Type1, param2?: Type2): ReturnType`
|
||||
- Purpose: [what this method does]
|
||||
- Parameters:
|
||||
• param1 (Type1): [description]
|
||||
• param2 (Type2): [description] [optional] [default: value]
|
||||
- Returns: (ReturnType) [description]
|
||||
- Throws: [exceptions if applicable]
|
||||
|
||||
## Dependencies
|
||||
### Internal Dependencies
|
||||
- `[module/file path]` - [purpose]
|
||||
|
||||
### External Dependencies
|
||||
- `[library name]` - [purpose and usage]
|
||||
|
||||
## Integration Points
|
||||
### Public APIs
|
||||
- `[API/function signature]` - [description]
|
||||
|
||||
### Data Flow
|
||||
[How data flows through this module/file]
|
||||
|
||||
## Implementation Notes
|
||||
### Design Patterns
|
||||
- [Pattern name]: [Usage and rationale]
|
||||
|
||||
### Technical Decisions
|
||||
- [Decision]: [Rationale]
|
||||
|
||||
### Considerations
|
||||
- Performance: [notes]
|
||||
- Security: [notes]
|
||||
- Limitations: [notes]
|
||||
```
|
||||
|
||||
### Documentation Style
|
||||
- **Concise but complete** - Focus on "what" and "why", not detailed "how"
|
||||
- **Code signatures** for key APIs - Include all parameter details
|
||||
- **Parameters**: Name, type, description, optional/default indicators, constraints
|
||||
- **Return values**: Type, description, special conditions (null, undefined, empty)
|
||||
- **Evidence-based** - Reference related documentation when appropriate
|
||||
- **Examples** for complex methods - Show usage patterns
|
||||
|
||||
### Content Restrictions (STRICTLY AVOID)
|
||||
- ❌ Duplicating content from other CLAUDE.md files (reference instead)
|
||||
- ❌ Overly detailed code explanations (code should be self-documenting)
|
||||
- ❌ Complete code listings (use signatures and descriptions)
|
||||
- ❌ Version-specific details unless critical
|
||||
- ❌ Documenting every single function (focus on public/exported APIs)
|
||||
|
||||
### Method Documentation Rules
|
||||
- **Public/Exported methods**: MUST document with full parameter details
|
||||
- **Private/Internal methods**: Only document if complex or critical
|
||||
- **Parameters**: MUST include type, description, constraints, defaults
|
||||
- **Return values**: MUST document type and description
|
||||
- **Exceptions**: Document all thrown errors
|
||||
|
||||
### Special Instructions
|
||||
- If analyzing folder with existing subdirectory CLAUDE.md files → reference them
|
||||
- For code files → prioritize exported/public APIs
|
||||
- Keep dependency lists focused on direct dependencies (not transitive)
|
||||
- Update existing CLAUDE.md files rather than creating duplicate sections
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Output file is named exactly 'CLAUDE.md' (not [filename].CLAUDE.md)
|
||||
□ All 6 required sections included (Purpose, Structure, Components, Dependencies, Integration, Implementation)
|
||||
□ All public/exported APIs documented with complete signatures
|
||||
□ Parameters documented with types, descriptions, and defaults
|
||||
□ References used instead of duplicating subdirectory documentation
|
||||
□ Internal vs external dependencies clearly distinguished
|
||||
□ Examples provided for non-trivial methods
|
||||
|
||||
Focus: Comprehensive yet concise documentation covering all essential aspects without redundancy.
|
||||
@@ -0,0 +1,30 @@
|
||||
Create detailed task breakdown and implementation planning.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Break down tasks into manageable subtasks (3-8 hours each)
|
||||
□ Identify all dependencies and execution sequence
|
||||
□ Provide realistic effort estimates with buffer
|
||||
□ Document risks for each task
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Break down complex tasks into manageable subtasks
|
||||
2. Identify dependencies and execution sequence requirements
|
||||
3. Estimate effort and resource requirements for each task
|
||||
4. Map task relationships and critical path analysis
|
||||
5. Document risks and mitigation strategies
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Hierarchical task breakdown with specific deliverables
|
||||
- Dependency mapping and execution sequence
|
||||
- Effort estimation with confidence levels
|
||||
- Resource allocation and skill requirements
|
||||
- Risk assessment and mitigation plans for each task
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ All tasks broken down to manageable size (3-8 hours)
|
||||
□ Dependencies mapped and critical path identified
|
||||
□ Effort estimates realistic with buffer included
|
||||
□ Every task has clear deliverable defined
|
||||
□ Risks documented with mitigation strategies
|
||||
|
||||
Focus: Actionable task planning with clear deliverables, dependencies, and realistic timelines.
|
||||
@@ -0,0 +1,28 @@
|
||||
Guide component implementation and development patterns.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Define component interface and API requirements clearly
|
||||
□ Identify reusable patterns and composition strategies
|
||||
□ Plan state management and data flow before implementation
|
||||
□ Design a comprehensive testing and validation approach
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Define component interface and API requirements
|
||||
2. Identify reusable patterns and composition strategies
|
||||
3. Plan state management and data flow implementation
|
||||
4. Design component testing and validation approach
|
||||
5. Document integration points and usage examples
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Component specification with clear interface definition
|
||||
- Implementation patterns and best practices
|
||||
- State management strategy and data flow design
|
||||
- Testing approach and validation criteria
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Component specification includes a clear interface definition
|
||||
□ Reusable implementation patterns and best practices are documented
|
||||
□ State management and data flow design is clear and robust
|
||||
□ A thorough testing and validation approach is defined
|
||||
|
||||
Focus: Reusable, maintainable component design with clear usage patterns.
|
||||
@@ -0,0 +1,127 @@
|
||||
Conduct comprehensive concept evaluation to assess feasibility, identify risks, and provide optimization recommendations.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Evaluate all 6 dimensions: Conceptual, Architectural, Technical, Resource, Risk, Dependency
|
||||
□ Provide quantified assessment scores (1-5 scale)
|
||||
□ Classify risks by severity (LOW/MEDIUM/HIGH/CRITICAL)
|
||||
□ Include specific, actionable recommendations
|
||||
□ Integrate session context and existing patterns
|
||||
|
||||
## EVALUATION DIMENSIONS
|
||||
|
||||
### 1. Conceptual Integrity
|
||||
- Design Coherence: Logical component connections
|
||||
- Requirement Completeness: All requirements identified
|
||||
- Scope Clarity: Defined and bounded scope
|
||||
- Success Criteria: Measurable metrics established
|
||||
|
||||
### 2. Architectural Soundness
|
||||
- System Integration: Fit with existing architecture
|
||||
- Design Patterns: Appropriate pattern usage
|
||||
- Modularity: Maintainable structure
|
||||
- Scalability: Future requirement capacity
|
||||
|
||||
### 3. Technical Feasibility
|
||||
- Implementation Complexity: Difficulty level assessment
|
||||
- Technology Maturity: Stable, supported technologies
|
||||
- Skill Requirements: Team expertise availability
|
||||
- Infrastructure Needs: Required changes/additions
|
||||
|
||||
### 4. Resource Assessment
|
||||
- Development Time: Realistic estimation
|
||||
- Team Resources: Size and skill composition
|
||||
- Budget Impact: Financial implications
|
||||
- Opportunity Cost: Delayed initiatives
|
||||
|
||||
### 5. Risk Identification
|
||||
- Technical Risks: Limitations, complexity, unknowns
|
||||
- Business Risks: Market timing, adoption, impact
|
||||
- Integration Risks: Compatibility challenges
|
||||
- Resource Risks: Availability, skills, timeline
|
||||
|
||||
### 6. Dependency Analysis
|
||||
- External Dependencies: Third-party services/tools
|
||||
- Internal Dependencies: Systems, teams, resources
|
||||
- Temporal Dependencies: Sequence and timing
|
||||
- Critical Path: Essential blocking dependencies
|
||||
|
||||
## ASSESSMENT METHODOLOGY
|
||||
|
||||
**Scoring Scale** (1-5):
|
||||
- 5 - Excellent: Minimal risk, well-defined, highly feasible
|
||||
- 4 - Good: Low risk, mostly clear, feasible
|
||||
- 3 - Average: Moderate risk, needs clarification
|
||||
- 2 - Poor: High risk, major changes required
|
||||
- 1 - Critical: Very high risk, fundamental problems
|
||||
|
||||
**Risk Levels**:
|
||||
- LOW: Minor issues, easily addressable
|
||||
- MEDIUM: Manageable challenges
|
||||
- HIGH: Significant concerns, major mitigation needed
|
||||
- CRITICAL: Fundamental viability threats
|
||||
|
||||
**Optimization Priorities**:
|
||||
- CRITICAL: Must address before planning
|
||||
- IMPORTANT: Should address for optimal outcomes
|
||||
- OPTIONAL: Nice-to-have improvements
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
|
||||
### Evaluation Summary
|
||||
```markdown
|
||||
## Overall Assessment
|
||||
- Feasibility Score: X/5
|
||||
- Risk Level: LOW/MEDIUM/HIGH/CRITICAL
|
||||
- Recommendation: PROCEED/PROCEED_WITH_MODIFICATIONS/RECONSIDER/REJECT
|
||||
|
||||
## Dimension Scores
|
||||
- Conceptual Integrity: X/5
|
||||
- Architectural Soundness: X/5
|
||||
- Technical Feasibility: X/5
|
||||
- Resource Assessment: X/5
|
||||
- Risk Profile: X/5
|
||||
- Dependency Complexity: X/5
|
||||
```
|
||||
|
||||
### Detailed Analysis
|
||||
For each dimension:
|
||||
1. Assessment: Current state evaluation
|
||||
2. Strengths: What works well
|
||||
3. Concerns: Issues and risks
|
||||
4. Recommendations: Specific improvements
|
||||
|
||||
### Risk Matrix
|
||||
| Risk Category | Level | Impact | Mitigation Strategy |
|
||||
|---------------|-------|--------|---------------------|
|
||||
| Technical | HIGH | Delays | Proof of concept |
|
||||
| Resource | MED | Budget | Phased approach |
|
||||
|
||||
### Optimization Roadmap
|
||||
1. CRITICAL: [Issue] - [Recommendation] - [Impact]
|
||||
2. IMPORTANT: [Issue] - [Recommendation] - [Impact]
|
||||
3. OPTIONAL: [Issue] - [Recommendation] - [Impact]
|
||||
|
||||
## CONTEXT INTEGRATION
|
||||
|
||||
**Session Memory**: Reference current conversation, decisions, patterns from session history
|
||||
**Existing Patterns**: Identify similar implementations, evaluate success/failure, leverage proven approaches
|
||||
**Architectural Alignment**: Ensure consistency, consider evolution, apply standards
|
||||
**Business Context**: Strategic fit, user impact, competitive advantage, timeline alignment
|
||||
|
||||
## PROJECT TYPE CONSIDERATIONS
|
||||
|
||||
**Innovation Projects**: Higher risk tolerance, learning focus, phased approach
|
||||
**Critical Business**: Lower risk tolerance, reliability focus, comprehensive mitigation
|
||||
**Integration Projects**: Compatibility focus, minimal disruption, rollback strategies
|
||||
**Greenfield Projects**: Architectural innovation, scalability, technology standardization
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ All 6 evaluation dimensions thoroughly assessed with scores
|
||||
□ Risk matrix completed with mitigation strategies
|
||||
□ Optimization recommendations prioritized (CRITICAL/IMPORTANT/OPTIONAL)
|
||||
□ Integration with existing systems evaluated
|
||||
□ Resource requirements and timeline implications identified
|
||||
□ Success criteria and validation metrics defined
|
||||
□ Next steps and decision points outlined
|
||||
|
||||
Focus: Actionable insights to improve concept quality and reduce implementation risks.
|
||||
@@ -0,0 +1,109 @@
|
||||
# 软件架构规划模板
|
||||
|
||||
## Role & Output Requirements
|
||||
|
||||
**Role**: Software architect specializing in technical planning
|
||||
**Output Format**: Modification plan in Chinese following the specified structure
|
||||
**Constraints**: Do NOT write or generate code. Provide planning and strategy only.
|
||||
|
||||
## Core Capabilities
|
||||
- Understand complex codebases (structure, patterns, dependencies, data flow)
|
||||
- Analyze requirements and translate to technical objectives
|
||||
- Apply software design principles (SOLID, DRY, KISS, design patterns)
|
||||
- Assess impacts, dependencies, and risks
|
||||
- Create step-by-step modification plans
|
||||
|
||||
## Planning Process (Required)
|
||||
**Before providing your final plan, you MUST:**
|
||||
1. Analyze requirements and identify technical objectives
|
||||
2. Explore existing code structure and patterns
|
||||
3. Identify modification points and formulate strategy
|
||||
4. Assess dependencies and risks
|
||||
5. Present structured modification plan
|
||||
|
||||
## Objectives
|
||||
1. Understand context (code, requirements, project background)
|
||||
2. Analyze relevant code sections and their relationships
|
||||
3. Create step-by-step modification plan (what, where, why, how)
|
||||
4. Illustrate intended logic using call flow diagrams
|
||||
5. Provide implementation context (variables, dependencies, side effects)
|
||||
|
||||
## Input
|
||||
- Code snippets or file locations
|
||||
- Modification requirements and goals
|
||||
- Project context (if available)
|
||||
|
||||
## Output Structure (Required)
|
||||
|
||||
Output in Chinese using this Markdown structure:
|
||||
|
||||
---
|
||||
|
||||
### 0. 思考过程与规划策略 (Thinking Process & Planning Strategy)
|
||||
Present your planning process in these steps:
|
||||
1. **需求解析**: Break down requirements and clarify core objectives
|
||||
2. **代码结构勘探**: Analyze current code structure and logic flow
|
||||
3. **核心修改点识别**: Identify modification points and formulate strategy
|
||||
4. **依赖与风险评估**: Assess dependencies and risks
|
||||
5. **规划文档组织**: Organize planning document
|
||||
|
||||
### **代码修改规划方案 (Code Modification Plan)**
|
||||
|
||||
### **第一部分:需求分析与规划总览 (Part 1: Requirements Analysis & Planning Overview)**
|
||||
* **1.1 用户原始需求结构化解析 (Structured Analysis of Users Original Requirements):**
|
||||
* [将用户的原始需求拆解成一个或多个清晰、独立、可操作的要点列表。每个要点都是一个明确的目标。]
|
||||
* **- 需求点 A:** [描述第一个具体需求]
|
||||
* **- 需求点 B:** [描述第二个具体需求]
|
||||
* **- ...**
|
||||
* **1.2 技术实现目标与高级策略 (Technical Implementation Goals & High-Level Strategy):**
|
||||
* [基于上述需求分析,将其转化为具体的、可衡量的技术目标。并简述为达成这些目标将采用的整体技术思路或架构策略。例如:为实现【需求点A】,我们需要在 `ServiceA` 中引入一个新的处理流程。为实现【需求点B】,我们将重构 `ModuleB` 的数据验证逻辑,以提高其扩展性。]
|
||||
|
||||
### **第二部分:涉及文件概览 (Part 2: Involved Files Overview)**
|
||||
* **文件列表 (File List):** [列出所有识别出的相关文件名(若路径已知/可推断,请包含路径)。不仅包括直接修改的文件,也包括提供关键上下文或可能受间接影响的文件。示例: `- src/core/module_a.py (直接修改)`, `- src/utils/helpers.py (依赖项,可能受影响)`, `- configs/settings.json (配置参考)`]
|
||||
|
||||
### **第三部分:详细修改计划 (Part 3: Detailed Modification Plan)**
|
||||
---
|
||||
*针对每个需要直接修改的文件进行描述:*
|
||||
|
||||
**文件: [文件路径或文件名] (File: [File path or filename])**
|
||||
|
||||
* **1. 位置 (Location):**
|
||||
* [清晰说明函数、类、方法或具体的代码区域,如果可能,指出大致行号范围。示例: 函数 `calculate_total_price` 内部,约第 75-80 行]
|
||||
|
||||
* **1.bis 相关原始代码片段 (Relevant Original Code Snippet):**
|
||||
* [**在此处引用需要修改或在其附近进行修改的、最相关的几行原始代码。** 这为开发者提供了直接的上下文。如果代码未提供,则注明相关代码未提供,根据描述进行规划。]
|
||||
* ```[language]
|
||||
// 引用相关的1-5行原始代码
|
||||
```
|
||||
|
||||
* **2. 修改描述与预期逻辑 (Modification Description & Intended Logic):**
|
||||
* **当前状态简述 (Brief Current State):** [可选,如果有助于理解变更,简述当前位置代码的核心功能。]
|
||||
* **拟议修改点 (Proposed Changes):**
|
||||
* [分步骤详细描述需要进行的逻辑更改。用清晰的中文自然语言解释 *什么* 需要被改变或添加。]
|
||||
* **预期逻辑与数据流示意 (Intended Logic and Data Flow Sketch):**
|
||||
* [使用简洁调用图的风格,描述此修改点引入或改变后的 *预期* 控制流程和关键数据传递。]
|
||||
* [**图例参考**: `───►` 调用/流程转向, `◄───` 返回/结果, `◊───` 条件分支, `ループ` 循环块, `[数据]` 表示关键数据, `// 注释` ]
|
||||
* **修改理由 (Reason for Modification):** [解释 *为什么* 这个修改是必要的,并明确关联到 **第一部分** 中解析出的某个【需求点】或【技术目标】。]
|
||||
* **预期结果 (Intended Outcome):** [描述此修改完成后,该代码段预期的行为或产出。]
|
||||
|
||||
* **3. 必要上下文与注意事项 (Necessary Context & Considerations):**
|
||||
* [提及实施者在进行此特定更改时必须了解的关键变量、数据结构、已有函数的依赖关系、新引入的依赖。]
|
||||
* [**重点指出**潜在的连锁反应、对其他模块的可能影响、性能考量、错误处理、事务性、并发问题或数据完整性等重要风险点。]
|
||||
|
||||
---
|
||||
*(对每个需要修改的文件重复上述格式)*
|
||||
|
||||
## Key Requirements
|
||||
1. **Language**: All output in Chinese
|
||||
2. **No Code Generation**: Do not write actual code. Provide descriptive modification plan only
|
||||
3. **Focus**: Detail what and why. Use logic sketches to illustrate how
|
||||
4. **Completeness**: State assumptions clearly when information is incomplete
|
||||
|
||||
## Self-Review Checklist
|
||||
Before providing final output, verify:
|
||||
- [ ] Thinking process outlines structured analytical approach
|
||||
- [ ] All requirements addressed in the plan
|
||||
- [ ] Plan is logical, actionable, and detailed
|
||||
- [ ] Modification reasons link back to requirements
|
||||
- [ ] Context and risks are highlighted
|
||||
- [ ] No actual code generated
|
||||
@@ -0,0 +1,30 @@
|
||||
Plan system migration and modernization strategies.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Assess current system completely before planning migration
|
||||
□ Plan incremental migration (avoid big-bang approach)
|
||||
□ Include rollback plan for every migration step
|
||||
□ Provide file:line references for all affected code
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
1. Assess current system architecture and migration requirements
|
||||
2. Identify migration paths and transformation strategies
|
||||
3. Plan data migration and system cutover procedures
|
||||
4. Evaluate compatibility and integration challenges
|
||||
5. Document rollback plans and risk mitigation strategies
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- Migration strategy with step-by-step execution plan
|
||||
- Data migration procedures and validation checkpoints
|
||||
- Compatibility assessment with file:line references
|
||||
- Risk analysis and rollback procedures for each phase
|
||||
- Testing strategy for migration validation
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Migration planned in incremental phases (not big-bang)
|
||||
□ Every phase has rollback plan documented
|
||||
□ Data migration validated with checkpoints
|
||||
□ Compatibility issues identified and mitigated
|
||||
□ Testing strategy covers all migration phases
|
||||
|
||||
Focus: Low-risk incremental migration with comprehensive fallback options.
|
||||
122
.ccw/workflows/cli-templates/prompts/rules-rule-api.txt
Normal file
122
.ccw/workflows/cli-templates/prompts/rules-rule-api.txt
Normal file
@@ -0,0 +1,122 @@
|
||||
# Rule Template: API Rules (Backend/Fullstack Only)
|
||||
|
||||
## Variables
|
||||
- {TECH_STACK_NAME}: Tech stack display name
|
||||
- {FILE_EXT}: File extension pattern
|
||||
- {API_FRAMEWORK}: API framework (Express, FastAPI, etc)
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
paths:
|
||||
- "**/api/**/*.{FILE_EXT}"
|
||||
- "**/routes/**/*.{FILE_EXT}"
|
||||
- "**/endpoints/**/*.{FILE_EXT}"
|
||||
- "**/controllers/**/*.{FILE_EXT}"
|
||||
- "**/handlers/**/*.{FILE_EXT}"
|
||||
---
|
||||
|
||||
# {TECH_STACK_NAME} API Rules
|
||||
|
||||
## Endpoint Design
|
||||
|
||||
[REST/GraphQL conventions from Exa research]
|
||||
|
||||
### URL Structure
|
||||
- Resource naming (plural nouns)
|
||||
- Nesting depth limits
|
||||
- Query parameter conventions
|
||||
- Version prefixing
|
||||
|
||||
### HTTP Methods
|
||||
- GET: Read operations
|
||||
- POST: Create operations
|
||||
- PUT/PATCH: Update operations
|
||||
- DELETE: Remove operations
|
||||
|
||||
### Status Codes
|
||||
- 2xx: Success responses
|
||||
- 4xx: Client errors
|
||||
- 5xx: Server errors
|
||||
|
||||
## Request Validation
|
||||
|
||||
[Input validation patterns]
|
||||
|
||||
### Schema Validation
|
||||
```{lang}
|
||||
// Example validation schema
|
||||
```
|
||||
|
||||
### Required Fields
|
||||
- Validation approach
|
||||
- Error messages format
|
||||
- Sanitization rules
|
||||
|
||||
## Response Format
|
||||
|
||||
[Standard response structures]
|
||||
|
||||
### Success Response
|
||||
```json
|
||||
{
|
||||
"data": {},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
### Pagination
|
||||
```json
|
||||
{
|
||||
"data": [],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
[Error handling for APIs]
|
||||
|
||||
### Error Format
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human readable message",
|
||||
"details": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Codes
|
||||
- VALIDATION_ERROR
|
||||
- NOT_FOUND
|
||||
- UNAUTHORIZED
|
||||
- FORBIDDEN
|
||||
|
||||
## Authentication & Authorization
|
||||
|
||||
[Auth patterns]
|
||||
- Token handling
|
||||
- Permission checks
|
||||
- Rate limiting
|
||||
|
||||
## Documentation
|
||||
|
||||
[API documentation standards]
|
||||
- OpenAPI/Swagger
|
||||
- Inline documentation
|
||||
- Example requests/responses
|
||||
```
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
- Focus on API-specific patterns
|
||||
- Include request/response examples
|
||||
- Cover security considerations
|
||||
- Reference framework conventions
|
||||
122
.ccw/workflows/cli-templates/prompts/rules-rule-components.txt
Normal file
122
.ccw/workflows/cli-templates/prompts/rules-rule-components.txt
Normal file
@@ -0,0 +1,122 @@
|
||||
# Rule Template: Component Rules (Frontend/Fullstack Only)
|
||||
|
||||
## Variables
|
||||
- {TECH_STACK_NAME}: Tech stack display name
|
||||
- {FILE_EXT}: File extension pattern
|
||||
- {UI_FRAMEWORK}: UI framework (React, Vue, etc)
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
paths:
|
||||
- "**/components/**/*.{FILE_EXT}"
|
||||
- "**/ui/**/*.{FILE_EXT}"
|
||||
- "**/views/**/*.{FILE_EXT}"
|
||||
- "**/pages/**/*.{FILE_EXT}"
|
||||
---
|
||||
|
||||
# {TECH_STACK_NAME} Component Rules
|
||||
|
||||
## Component Structure
|
||||
|
||||
[Organization patterns from Exa research]
|
||||
|
||||
### File Organization
|
||||
```
|
||||
components/
|
||||
├── common/ # Shared components
|
||||
├── features/ # Feature-specific
|
||||
├── layout/ # Layout components
|
||||
└── ui/ # Base UI elements
|
||||
```
|
||||
|
||||
### Component Template
|
||||
```{lang}
|
||||
// Standard component structure
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
- PascalCase for components
|
||||
- Descriptive names
|
||||
- Prefix conventions (if any)
|
||||
|
||||
## Props & State
|
||||
|
||||
[State management guidelines]
|
||||
|
||||
### Props Definition
|
||||
```{lang}
|
||||
// Props type/interface example
|
||||
```
|
||||
|
||||
### Props Best Practices
|
||||
- Required vs optional
|
||||
- Default values
|
||||
- Prop validation
|
||||
- Prop naming
|
||||
|
||||
### Local State
|
||||
- When to use local state
|
||||
- State initialization
|
||||
- State updates
|
||||
|
||||
### Shared State
|
||||
- State management approach
|
||||
- Context usage
|
||||
- Store patterns
|
||||
|
||||
## Styling
|
||||
|
||||
[CSS/styling conventions]
|
||||
|
||||
### Approach
|
||||
- [CSS Modules/Styled Components/Tailwind/etc]
|
||||
|
||||
### Style Organization
|
||||
```{lang}
|
||||
// Style example
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
- Class naming (BEM, etc)
|
||||
- CSS variable usage
|
||||
- Theme integration
|
||||
|
||||
## Accessibility
|
||||
|
||||
[A11y requirements]
|
||||
|
||||
### Essential Requirements
|
||||
- Semantic HTML
|
||||
- ARIA labels
|
||||
- Keyboard navigation
|
||||
- Focus management
|
||||
|
||||
### Testing A11y
|
||||
- Automated checks
|
||||
- Manual testing
|
||||
- Screen reader testing
|
||||
|
||||
## Performance
|
||||
|
||||
[Performance guidelines]
|
||||
|
||||
### Optimization Patterns
|
||||
- Memoization
|
||||
- Lazy loading
|
||||
- Code splitting
|
||||
- Virtual lists
|
||||
|
||||
### Avoiding Re-renders
|
||||
- When to memoize
|
||||
- Callback optimization
|
||||
- State structure
|
||||
```
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
- Focus on component-specific patterns
|
||||
- Include framework-specific examples
|
||||
- Cover accessibility requirements
|
||||
- Address performance considerations
|
||||
89
.ccw/workflows/cli-templates/prompts/rules-rule-config.txt
Normal file
89
.ccw/workflows/cli-templates/prompts/rules-rule-config.txt
Normal file
@@ -0,0 +1,89 @@
|
||||
# Rule Template: Configuration Rules
|
||||
|
||||
## Variables
|
||||
- {TECH_STACK_NAME}: Tech stack display name
|
||||
- {CONFIG_FILES}: List of config file patterns
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
paths:
|
||||
- "*.config.*"
|
||||
- ".*rc"
|
||||
- ".*rc.{js,json,yaml,yml}"
|
||||
- "package.json"
|
||||
- "tsconfig*.json"
|
||||
- "pyproject.toml"
|
||||
- "Cargo.toml"
|
||||
- "go.mod"
|
||||
- ".env*"
|
||||
---
|
||||
|
||||
# {TECH_STACK_NAME} Configuration Rules
|
||||
|
||||
## Project Setup
|
||||
|
||||
[Configuration guidelines from Exa research]
|
||||
|
||||
### Essential Config Files
|
||||
- [List primary config files]
|
||||
- [Purpose of each]
|
||||
|
||||
### Recommended Structure
|
||||
```
|
||||
project/
|
||||
├── [config files]
|
||||
├── src/
|
||||
└── tests/
|
||||
```
|
||||
|
||||
## Tooling
|
||||
|
||||
[Linters, formatters, bundlers]
|
||||
|
||||
### Linting
|
||||
- Tool: [ESLint/Pylint/etc]
|
||||
- Config file: [.eslintrc/pyproject.toml/etc]
|
||||
- Key rules to enable
|
||||
|
||||
### Formatting
|
||||
- Tool: [Prettier/Black/etc]
|
||||
- Integration with editor
|
||||
- Pre-commit hooks
|
||||
|
||||
### Build Tools
|
||||
- Bundler: [Webpack/Vite/etc]
|
||||
- Build configuration
|
||||
- Optimization settings
|
||||
|
||||
## Environment
|
||||
|
||||
[Environment management]
|
||||
|
||||
### Environment Variables
|
||||
- Naming conventions
|
||||
- Required vs optional
|
||||
- Secret handling
|
||||
- .env file structure
|
||||
|
||||
### Development vs Production
|
||||
- Environment-specific configs
|
||||
- Feature flags
|
||||
- Debug settings
|
||||
|
||||
## Dependencies
|
||||
|
||||
[Dependency management]
|
||||
- Lock file usage
|
||||
- Version pinning strategy
|
||||
- Security updates
|
||||
- Peer dependencies
|
||||
```
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
- Focus on config file best practices
|
||||
- Include security considerations
|
||||
- Cover development workflow setup
|
||||
- Mention CI/CD integration where relevant
|
||||
60
.ccw/workflows/cli-templates/prompts/rules-rule-core.txt
Normal file
60
.ccw/workflows/cli-templates/prompts/rules-rule-core.txt
Normal file
@@ -0,0 +1,60 @@
|
||||
# Rule Template: Core Principles
|
||||
|
||||
## Variables
|
||||
- {TECH_STACK_NAME}: Tech stack display name
|
||||
- {FILE_EXT}: File extension pattern
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
paths: **/*.{FILE_EXT}
|
||||
---
|
||||
|
||||
# {TECH_STACK_NAME} Core Principles
|
||||
|
||||
## Philosophy
|
||||
|
||||
[Synthesize core philosophy from Exa research]
|
||||
- Key paradigms and mental models
|
||||
- Design philosophy
|
||||
- Community conventions
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
[Language-specific naming rules]
|
||||
- Variables and functions
|
||||
- Classes and types
|
||||
- Files and directories
|
||||
- Constants and enums
|
||||
|
||||
## Code Organization
|
||||
|
||||
[Structure and module guidelines]
|
||||
- File structure patterns
|
||||
- Module boundaries
|
||||
- Import organization
|
||||
- Dependency management
|
||||
|
||||
## Type Safety
|
||||
|
||||
[Type system best practices - if applicable]
|
||||
- Type annotation guidelines
|
||||
- Generic usage patterns
|
||||
- Type inference vs explicit types
|
||||
- Null/undefined handling
|
||||
|
||||
## Documentation
|
||||
|
||||
[Documentation standards]
|
||||
- Comment style
|
||||
- JSDoc/docstring format
|
||||
- README conventions
|
||||
```
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
- Focus on universal principles that apply to ALL files
|
||||
- Keep rules actionable and specific
|
||||
- Include rationale for each rule
|
||||
- Reference official style guides where applicable
|
||||
70
.ccw/workflows/cli-templates/prompts/rules-rule-patterns.txt
Normal file
70
.ccw/workflows/cli-templates/prompts/rules-rule-patterns.txt
Normal file
@@ -0,0 +1,70 @@
|
||||
# Rule Template: Implementation Patterns
|
||||
|
||||
## Variables
|
||||
- {TECH_STACK_NAME}: Tech stack display name
|
||||
- {FILE_EXT}: File extension pattern
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
paths: src/**/*.{FILE_EXT}
|
||||
---
|
||||
|
||||
# {TECH_STACK_NAME} Implementation Patterns
|
||||
|
||||
## Common Patterns
|
||||
|
||||
[With code examples from Exa research]
|
||||
|
||||
### Pattern 1: [Name]
|
||||
```{lang}
|
||||
// Example code
|
||||
```
|
||||
**When to use**: [Context]
|
||||
**Benefits**: [Why this pattern]
|
||||
|
||||
### Pattern 2: [Name]
|
||||
...
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
[Common mistakes with examples]
|
||||
|
||||
### Anti-Pattern 1: [Name]
|
||||
```{lang}
|
||||
// Bad example
|
||||
```
|
||||
**Problem**: [Why it's bad]
|
||||
**Solution**: [Better approach]
|
||||
|
||||
## Error Handling
|
||||
|
||||
[Error handling conventions]
|
||||
- Error types and hierarchy
|
||||
- Try-catch patterns
|
||||
- Error propagation
|
||||
- Logging practices
|
||||
|
||||
## Async Patterns
|
||||
|
||||
[Asynchronous code conventions - if applicable]
|
||||
- Promise handling
|
||||
- Async/await usage
|
||||
- Concurrency patterns
|
||||
- Error handling in async code
|
||||
|
||||
## State Management
|
||||
|
||||
[State handling patterns]
|
||||
- Local state patterns
|
||||
- Shared state approaches
|
||||
- Immutability practices
|
||||
```
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
- Focus on source code implementation
|
||||
- Provide concrete code examples
|
||||
- Show both good and bad patterns
|
||||
- Include context for when to apply each pattern
|
||||
81
.ccw/workflows/cli-templates/prompts/rules-rule-testing.txt
Normal file
81
.ccw/workflows/cli-templates/prompts/rules-rule-testing.txt
Normal file
@@ -0,0 +1,81 @@
|
||||
# Rule Template: Testing Rules
|
||||
|
||||
## Variables
|
||||
- {TECH_STACK_NAME}: Tech stack display name
|
||||
- {FILE_EXT}: File extension pattern
|
||||
- {TEST_FRAMEWORK}: Primary testing framework
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
paths:
|
||||
- "**/*.{test,spec}.{FILE_EXT}"
|
||||
- "tests/**/*.{FILE_EXT}"
|
||||
- "__tests__/**/*.{FILE_EXT}"
|
||||
- "**/test_*.{FILE_EXT}"
|
||||
- "**/*_test.{FILE_EXT}"
|
||||
---
|
||||
|
||||
# {TECH_STACK_NAME} Testing Rules
|
||||
|
||||
## Testing Framework
|
||||
|
||||
[Recommended frameworks from Exa research]
|
||||
- Primary: {TEST_FRAMEWORK}
|
||||
- Assertion library
|
||||
- Mocking library
|
||||
- Coverage tool
|
||||
|
||||
## Test Structure
|
||||
|
||||
[Organization patterns]
|
||||
|
||||
### File Naming
|
||||
- Unit tests: `*.test.{ext}` or `*.spec.{ext}`
|
||||
- Integration tests: `*.integration.test.{ext}`
|
||||
- E2E tests: `*.e2e.test.{ext}`
|
||||
|
||||
### Test Organization
|
||||
```{lang}
|
||||
describe('[Component/Module]', () => {
|
||||
describe('[method/feature]', () => {
|
||||
it('should [expected behavior]', () => {
|
||||
// Arrange
|
||||
// Act
|
||||
// Assert
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Mocking & Fixtures
|
||||
|
||||
[Best practices]
|
||||
- Mock creation patterns
|
||||
- Fixture organization
|
||||
- Test data factories
|
||||
- Cleanup strategies
|
||||
|
||||
## Assertions
|
||||
|
||||
[Assertion patterns]
|
||||
- Common assertions
|
||||
- Custom matchers
|
||||
- Async assertions
|
||||
- Error assertions
|
||||
|
||||
## Coverage Requirements
|
||||
|
||||
[Coverage guidelines]
|
||||
- Minimum coverage thresholds
|
||||
- What to cover vs skip
|
||||
- Coverage report interpretation
|
||||
```
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
- Include framework-specific patterns
|
||||
- Show test structure examples
|
||||
- Cover both unit and integration testing
|
||||
- Include async testing patterns
|
||||
@@ -0,0 +1,89 @@
|
||||
# Tech Stack Rules Generation Agent Prompt
|
||||
|
||||
## Context Variables
|
||||
- {TECH_STACK_NAME}: Normalized tech stack name (e.g., "typescript-react")
|
||||
- {PRIMARY_LANG}: Primary language (e.g., "typescript")
|
||||
- {FILE_EXT}: File extension pattern (e.g., "{ts,tsx}")
|
||||
- {FRAMEWORK_TYPE}: frontend | backend | fullstack | library
|
||||
- {COMPONENTS}: Array of tech components
|
||||
- {OUTPUT_DIR}: .claude/rules/tech/{TECH_STACK_NAME}/
|
||||
|
||||
## Agent Instructions
|
||||
|
||||
Generate path-conditional rules for Claude Code automatic loading.
|
||||
|
||||
### Step 1: Execute Exa Research
|
||||
|
||||
Run 4-6 parallel queries based on tech stack:
|
||||
|
||||
**Base Queries** (always execute):
|
||||
```
|
||||
mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} best practices principles 2025", tokensNum: 8000)
|
||||
mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} implementation patterns examples", tokensNum: 7000)
|
||||
mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} testing strategies conventions", tokensNum: 5000)
|
||||
mcp__exa__web_search_exa(query: "{PRIMARY_LANG} configuration setup 2025", numResults: 5)
|
||||
```
|
||||
|
||||
**Component Queries** (for each framework in COMPONENTS):
|
||||
```
|
||||
mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} {component} integration patterns", tokensNum: 5000)
|
||||
```
|
||||
|
||||
### Step 2: Read Rule Templates
|
||||
|
||||
Read each template file before generating content:
|
||||
```
|
||||
Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-core.txt)
|
||||
Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-patterns.txt)
|
||||
Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-testing.txt)
|
||||
Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-config.txt)
|
||||
Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-api.txt) # Only if backend/fullstack
|
||||
Read(~/.ccw/workflows/cli-templates/prompts/rules/rule-components.txt) # Only if frontend/fullstack
|
||||
```
|
||||
|
||||
### Step 3: Generate Rule Files
|
||||
|
||||
Create directory and write files:
|
||||
```bash
|
||||
mkdir -p "{OUTPUT_DIR}"
|
||||
```
|
||||
|
||||
**Always Generate**:
|
||||
- core.md (from rule-core.txt template)
|
||||
- patterns.md (from rule-patterns.txt template)
|
||||
- testing.md (from rule-testing.txt template)
|
||||
- config.md (from rule-config.txt template)
|
||||
|
||||
**Conditional**:
|
||||
- api.md: Only if FRAMEWORK_TYPE == 'backend' or 'fullstack'
|
||||
- components.md: Only if FRAMEWORK_TYPE == 'frontend' or 'fullstack'
|
||||
|
||||
### Step 4: Write Metadata
|
||||
|
||||
```json
|
||||
{
|
||||
"tech_stack": "{TECH_STACK_NAME}",
|
||||
"primary_lang": "{PRIMARY_LANG}",
|
||||
"file_ext": "{FILE_EXT}",
|
||||
"framework_type": "{FRAMEWORK_TYPE}",
|
||||
"components": ["{COMPONENTS}"],
|
||||
"generated_at": "{ISO_TIMESTAMP}",
|
||||
"source": "exa-research",
|
||||
"files_generated": ["core.md", "patterns.md", "testing.md", "config.md", ...]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Report Completion
|
||||
|
||||
Provide summary:
|
||||
- Files created with their path patterns
|
||||
- Exa queries executed (count)
|
||||
- Sources consulted (count)
|
||||
|
||||
## Critical Requirements
|
||||
|
||||
1. Every .md file MUST start with `paths` YAML frontmatter
|
||||
2. Use {FILE_EXT} consistently across all rule files
|
||||
3. Synthesize Exa research into actionable rules
|
||||
4. Include code examples from Exa sources
|
||||
5. Keep each file focused on its specific domain
|
||||
359
.ccw/workflows/cli-templates/prompts/tech-tech-module-format.txt
Normal file
359
.ccw/workflows/cli-templates/prompts/tech-tech-module-format.txt
Normal file
@@ -0,0 +1,359 @@
|
||||
Template for generating tech stack module documentation files
|
||||
|
||||
## Purpose
|
||||
Guide agent to create modular tech stack documentation from Exa research results.
|
||||
|
||||
## File Location
|
||||
`.claude/skills/{tech_stack_name}/*.md`
|
||||
|
||||
## Module Structure
|
||||
|
||||
Each module should include:
|
||||
- **Frontmatter**: YAML with module name and tech stack
|
||||
- **Main Sections**: Clear headings with hierarchical organization
|
||||
- **Code Examples**: Real examples from Exa research
|
||||
- **Best Practices**: Do's and don'ts sections
|
||||
- **References**: Attribution to Exa sources
|
||||
|
||||
---
|
||||
|
||||
## Module 1: principles.md (~3K tokens)
|
||||
|
||||
**Purpose**: Core concepts, philosophies, and fundamental principles
|
||||
|
||||
**Frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
module: principles
|
||||
tech_stack: {tech_stack_name}
|
||||
description: Core concepts and philosophies
|
||||
tokens: ~3000
|
||||
---
|
||||
```
|
||||
|
||||
**Structure**:
|
||||
```markdown
|
||||
# {Tech} Principles
|
||||
|
||||
## Core Concepts
|
||||
- Fundamental principle 1
|
||||
- Fundamental principle 2
|
||||
- Key philosophy
|
||||
|
||||
## Design Philosophy
|
||||
- Approach to problem-solving
|
||||
- Architectural principles
|
||||
- Core values
|
||||
|
||||
## Key Features
|
||||
- Feature 1: Description
|
||||
- Feature 2: Description
|
||||
|
||||
## When to Use
|
||||
- Use case scenarios
|
||||
- Best fit situations
|
||||
|
||||
## References
|
||||
- Source 1 from Exa
|
||||
- Source 2 from Exa
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 2: patterns.md (~5K tokens)
|
||||
|
||||
**Purpose**: Implementation patterns with code examples
|
||||
|
||||
**Frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
module: patterns
|
||||
tech_stack: {tech_stack_name}
|
||||
description: Implementation patterns with examples
|
||||
tokens: ~5000
|
||||
---
|
||||
```
|
||||
|
||||
**Structure**:
|
||||
```markdown
|
||||
# {Tech} Patterns
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1: {Name}
|
||||
**Use Case**: When to use this pattern
|
||||
**Implementation**:
|
||||
\`\`\`{language}
|
||||
// Code example from Exa
|
||||
\`\`\`
|
||||
**Benefits**: Why use this pattern
|
||||
|
||||
### Pattern 2: {Name}
|
||||
[Same structure]
|
||||
|
||||
## Architectural Patterns
|
||||
- Pattern descriptions
|
||||
- Code examples
|
||||
|
||||
## Component Patterns
|
||||
- Reusable component structures
|
||||
- Integration examples
|
||||
|
||||
## References
|
||||
- Exa sources with pattern examples
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 3: practices.md (~4K tokens)
|
||||
|
||||
**Purpose**: Best practices, anti-patterns, pitfalls
|
||||
|
||||
**Frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
module: practices
|
||||
tech_stack: {tech_stack_name}
|
||||
description: Best practices and anti-patterns
|
||||
tokens: ~4000
|
||||
---
|
||||
```
|
||||
|
||||
**Structure**:
|
||||
```markdown
|
||||
# {Tech} Best Practices
|
||||
|
||||
## Do's
|
||||
✅ **Practice 1**: Description
|
||||
- Rationale
|
||||
- Example scenario
|
||||
|
||||
✅ **Practice 2**: Description
|
||||
|
||||
## Don'ts
|
||||
❌ **Anti-pattern 1**: What to avoid
|
||||
- Why it's problematic
|
||||
- Better alternative
|
||||
|
||||
❌ **Anti-pattern 2**: What to avoid
|
||||
|
||||
## Common Pitfalls
|
||||
1. **Pitfall 1**: Description and solution
|
||||
2. **Pitfall 2**: Description and solution
|
||||
|
||||
## Performance Considerations
|
||||
- Optimization techniques
|
||||
- Common bottlenecks
|
||||
|
||||
## Security Best Practices
|
||||
- Security considerations
|
||||
- Common vulnerabilities
|
||||
|
||||
## References
|
||||
- Exa sources for best practices
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 4: testing.md (~3K tokens)
|
||||
|
||||
**Purpose**: Testing strategies, frameworks, and examples
|
||||
|
||||
**Frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
module: testing
|
||||
tech_stack: {tech_stack_name}
|
||||
description: Testing strategies and frameworks
|
||||
tokens: ~3000
|
||||
---
|
||||
```
|
||||
|
||||
**Structure**:
|
||||
```markdown
|
||||
# {Tech} Testing
|
||||
|
||||
## Testing Strategies
|
||||
- Unit testing approach
|
||||
- Integration testing approach
|
||||
- E2E testing approach
|
||||
|
||||
## Testing Frameworks
|
||||
### Framework 1
|
||||
- Setup
|
||||
- Basic usage
|
||||
- Example:
|
||||
\`\`\`{language}
|
||||
// Test example from Exa
|
||||
\`\`\`
|
||||
|
||||
## Test Patterns
|
||||
- Common test patterns
|
||||
- Mock strategies
|
||||
- Assertion best practices
|
||||
|
||||
## Coverage Recommendations
|
||||
- What to test
|
||||
- Coverage targets
|
||||
|
||||
## References
|
||||
- Exa sources for testing examples
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 5: config.md (~3K tokens)
|
||||
|
||||
**Purpose**: Setup, configuration, and tooling
|
||||
|
||||
**Frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
module: config
|
||||
tech_stack: {tech_stack_name}
|
||||
description: Setup, configuration, and tooling
|
||||
tokens: ~3000
|
||||
---
|
||||
```
|
||||
|
||||
**Structure**:
|
||||
```markdown
|
||||
# {Tech} Configuration
|
||||
|
||||
## Installation
|
||||
\`\`\`bash
|
||||
# Installation commands
|
||||
\`\`\`
|
||||
|
||||
## Basic Configuration
|
||||
\`\`\`{config-format}
|
||||
// Configuration example from Exa
|
||||
\`\`\`
|
||||
|
||||
## Common Configurations
|
||||
### Development
|
||||
- Dev config setup
|
||||
- Hot reload configuration
|
||||
|
||||
### Production
|
||||
- Production optimizations
|
||||
- Build configurations
|
||||
|
||||
## Tooling
|
||||
- Recommended tools
|
||||
- IDE/Editor setup
|
||||
- Linters and formatters
|
||||
|
||||
## Environment Setup
|
||||
- Environment variables
|
||||
- Config file structure
|
||||
|
||||
## References
|
||||
- Exa sources for configuration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 6: frameworks.md (~4K tokens) [CONDITIONAL]
|
||||
|
||||
**Purpose**: Framework integration patterns (only for composite tech stacks)
|
||||
|
||||
**Condition**: Only generate if `is_composite = true`
|
||||
|
||||
**Frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
module: frameworks
|
||||
tech_stack: {tech_stack_name}
|
||||
description: Framework integration patterns
|
||||
tokens: ~4000
|
||||
conditional: composite_only
|
||||
---
|
||||
```
|
||||
|
||||
**Structure**:
|
||||
```markdown
|
||||
# {Main Tech} + {Framework} Integration
|
||||
|
||||
## Integration Overview
|
||||
- How {main_tech} works with {framework}
|
||||
- Architecture considerations
|
||||
|
||||
## Setup
|
||||
\`\`\`bash
|
||||
# Integration setup commands
|
||||
\`\`\`
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Pattern 1: {Name}
|
||||
\`\`\`{language}
|
||||
// Integration example from Exa
|
||||
\`\`\`
|
||||
|
||||
## Best Practices
|
||||
- Integration best practices
|
||||
- Common pitfalls
|
||||
|
||||
## Examples
|
||||
- Real-world integration examples
|
||||
- Code samples from Exa
|
||||
|
||||
## References
|
||||
- Exa sources for integration patterns
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Metadata File: metadata.json
|
||||
|
||||
**Purpose**: Store generation metadata and research summary
|
||||
|
||||
**Structure**:
|
||||
```json
|
||||
{
|
||||
"tech_stack_name": "typescript-react-nextjs",
|
||||
"components": ["typescript", "react", "nextjs"],
|
||||
"is_composite": true,
|
||||
"generated_at": "2025-11-04T22:00:00Z",
|
||||
"source": "exa-research",
|
||||
"research_summary": {
|
||||
"total_queries": 6,
|
||||
"total_sources": 25,
|
||||
"query_list": [
|
||||
"typescript core principles best practices 2025",
|
||||
"react common patterns architecture examples",
|
||||
"nextjs configuration setup tooling 2025",
|
||||
"testing strategies",
|
||||
"react nextjs integration",
|
||||
"typescript react integration"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Generation Guidelines
|
||||
|
||||
### Content Synthesis from Exa
|
||||
- Extract relevant code examples from Exa results
|
||||
- Synthesize information from multiple sources
|
||||
- Maintain technical accuracy
|
||||
- Cite sources in References section
|
||||
|
||||
### Formatting Rules
|
||||
- Use clear markdown headers
|
||||
- Include code fences with language specification
|
||||
- Use emoji for Do's (✅) and Don'ts (❌)
|
||||
- Keep token estimates accurate
|
||||
|
||||
### Error Handling
|
||||
- If Exa query fails, note in References section
|
||||
- If insufficient data, mark section as "Limited research available"
|
||||
- Handle missing components gracefully
|
||||
|
||||
### Token Distribution
|
||||
- Total budget: ~22K tokens for 6 modules
|
||||
- Adjust module size based on content availability
|
||||
- Prioritize quality over hitting exact token counts
|
||||
185
.ccw/workflows/cli-templates/prompts/tech-tech-skill-index.txt
Normal file
185
.ccw/workflows/cli-templates/prompts/tech-tech-skill-index.txt
Normal file
@@ -0,0 +1,185 @@
|
||||
Template for generating tech stack SKILL.md index file
|
||||
|
||||
## Purpose
|
||||
Create main SKILL package index with module references and loading recommendations.
|
||||
|
||||
## File Location
|
||||
`.claude/skills/{tech_stack_name}/SKILL.md`
|
||||
|
||||
## Template Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: {TECH_STACK_NAME}
|
||||
description: {MAIN_TECH} development guidelines from industry standards (Exa research)
|
||||
version: 1.0.0
|
||||
generated: {ISO_TIMESTAMP}
|
||||
source: exa-research
|
||||
---
|
||||
# {TechStackTitle} SKILL Package
|
||||
|
||||
## Overview
|
||||
|
||||
{Brief 1-2 sentence description of the tech stack and purpose of this SKILL package}
|
||||
|
||||
**Primary Technology**: {MAIN_TECH}
|
||||
{IF_COMPOSITE}**Frameworks**: {COMPONENT_LIST}{/IF_COMPOSITE}
|
||||
|
||||
## Modular Documentation
|
||||
|
||||
### Core Understanding (~8K tokens)
|
||||
- [Principles](./principles.md) - Core concepts and philosophies
|
||||
- [Patterns](./patterns.md) - Implementation patterns with examples
|
||||
|
||||
### Practical Guidance (~7K tokens)
|
||||
- [Best Practices](./practices.md) - Do's, don'ts, anti-patterns
|
||||
- [Testing](./testing.md) - Testing strategies and frameworks
|
||||
|
||||
### Configuration & Integration (~7K tokens)
|
||||
- [Configuration](./config.md) - Setup, tooling, configuration
|
||||
{IF_COMPOSITE}- [Frameworks](./frameworks.md) - Integration patterns{/IF_COMPOSITE}
|
||||
|
||||
## Loading Recommendations
|
||||
|
||||
### Quick Reference (~7K tokens)
|
||||
Load for quick consultation on core concepts:
|
||||
- principles.md
|
||||
- practices.md
|
||||
|
||||
**Use When**: Need quick reminder of best practices or core principles
|
||||
|
||||
### Implementation Focus (~8K tokens)
|
||||
Load for active development work:
|
||||
- patterns.md
|
||||
- config.md
|
||||
|
||||
**Use When**: Writing code, setting up projects, implementing features
|
||||
|
||||
### Complete Package (~22K tokens)
|
||||
Load all modules for comprehensive understanding:
|
||||
- All 5-6 modules
|
||||
|
||||
**Use When**: Learning tech stack, architecture reviews, comprehensive reference
|
||||
|
||||
## Usage
|
||||
|
||||
**Load this SKILL when**:
|
||||
- Starting new {TECH_STACK} projects
|
||||
- Reviewing {TECH_STACK} code
|
||||
- Learning {TECH_STACK} best practices
|
||||
- Implementing {TECH_STACK} patterns
|
||||
- Troubleshooting {TECH_STACK} issues
|
||||
|
||||
**Auto-triggers on**:
|
||||
- Keywords: {TECH_KEYWORDS}
|
||||
- File types: {FILE_EXTENSIONS}
|
||||
|
||||
## Research Metadata
|
||||
|
||||
- **Generated**: {ISO_TIMESTAMP}
|
||||
- **Source**: Exa Research (web search + code context)
|
||||
- **Queries Executed**: {QUERY_COUNT}
|
||||
- **Sources Consulted**: {SOURCE_COUNT}
|
||||
- **Research Quality**: {QUALITY_INDICATOR}
|
||||
|
||||
## Tech Stack Components
|
||||
|
||||
**Primary**: {MAIN_TECH} - {MAIN_TECH_DESCRIPTION}
|
||||
|
||||
{IF_COMPOSITE}
|
||||
**Additional Frameworks**:
|
||||
{FOR_EACH_COMPONENT}
|
||||
- **{COMPONENT_NAME}**: {COMPONENT_DESCRIPTION}
|
||||
{/FOR_EACH_COMPONENT}
|
||||
{/IF_COMPOSITE}
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0.0** ({DATE}): Initial SKILL package generated from Exa research
|
||||
|
||||
---
|
||||
|
||||
## Developer Notes
|
||||
|
||||
This SKILL package was auto-generated using:
|
||||
- `/memory:tech-research` command
|
||||
- Exa AI research APIs (mcp__exa__get_code_context_exa, mcp__exa__web_search_exa)
|
||||
- Token limit: ~5K per module, ~22K total
|
||||
|
||||
To regenerate:
|
||||
```bash
|
||||
/memory:tech-research "{tech_stack_name}" --regenerate
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Variable Substitution Guide
|
||||
|
||||
### Required Variables
|
||||
- `{TECH_STACK_NAME}`: Lowercase hyphenated name (e.g., "typescript-react-nextjs")
|
||||
- `{TechStackTitle}`: Title case display name (e.g., "TypeScript React Next.js")
|
||||
- `{MAIN_TECH}`: Primary technology (e.g., "TypeScript")
|
||||
- `{ISO_TIMESTAMP}`: ISO 8601 timestamp (e.g., "2025-11-04T22:00:00Z")
|
||||
- `{QUERY_COUNT}`: Number of Exa queries executed (e.g., 6)
|
||||
- `{SOURCE_COUNT}`: Total sources consulted (e.g., 25)
|
||||
|
||||
### Conditional Variables
|
||||
- `{IF_COMPOSITE}...{/IF_COMPOSITE}`: Only include if tech stack has multiple components
|
||||
- `{COMPONENT_LIST}`: Comma-separated list of framework names
|
||||
- `{FOR_EACH_COMPONENT}...{/FOR_EACH_COMPONENT}`: Loop through components
|
||||
|
||||
### Optional Variables
|
||||
- `{MAIN_TECH_DESCRIPTION}`: One-line description of primary tech
|
||||
- `{COMPONENT_DESCRIPTION}`: One-line description per component
|
||||
- `{TECH_KEYWORDS}`: Comma-separated trigger keywords
|
||||
- `{FILE_EXTENSIONS}`: File extensions (e.g., ".ts, .tsx, .jsx")
|
||||
- `{QUALITY_INDICATOR}`: Research quality metric (e.g., "High", "Medium")
|
||||
|
||||
---
|
||||
|
||||
## Generation Instructions
|
||||
|
||||
### Step 1: Read metadata.json
|
||||
Extract values for variables from metadata.json generated during module creation.
|
||||
|
||||
### Step 2: Determine composite status
|
||||
- Single tech: Omit {IF_COMPOSITE} sections
|
||||
- Composite: Include frameworks section and integration module reference
|
||||
|
||||
### Step 3: Calculate token estimates
|
||||
- Verify module files exist
|
||||
- Adjust token estimates based on actual file sizes
|
||||
- Update loading recommendation estimates
|
||||
|
||||
### Step 4: Generate descriptions
|
||||
- **Overview**: Brief description of tech stack purpose
|
||||
- **Main tech description**: One-liner for primary technology
|
||||
- **Component descriptions**: One-liner per additional framework
|
||||
|
||||
### Step 5: Build keyword lists
|
||||
- Extract common keywords from tech stack name
|
||||
- Add file extensions relevant to tech stack
|
||||
- Include framework-specific triggers
|
||||
|
||||
### Step 6: Format timestamps
|
||||
- Use ISO 8601 format for all timestamps
|
||||
- Include timezone (UTC recommended)
|
||||
|
||||
### Step 7: Write SKILL.md
|
||||
- Apply template with all substitutions
|
||||
- Validate markdown formatting
|
||||
- Verify all relative paths work
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] All module files exist and are referenced
|
||||
- [ ] Token estimates are reasonably accurate
|
||||
- [ ] Conditional sections handled correctly (composite vs single)
|
||||
- [ ] Timestamps in ISO 8601 format
|
||||
- [ ] All relative paths use ./ prefix
|
||||
- [ ] Metadata section matches metadata.json
|
||||
- [ ] Loading recommendations align with actual module sizes
|
||||
- [ ] Usage section includes relevant trigger keywords
|
||||
@@ -0,0 +1,38 @@
|
||||
PURPOSE: Generate comprehensive multi-layer test enhancement suggestions
|
||||
- Success: Cover L0-L3 layers with focus on API, integration, and error scenarios
|
||||
- Scope: Files with coverage gaps identified in TEST_ANALYSIS_RESULTS.md
|
||||
- Goal: Provide specific, actionable test case suggestions that increase coverage completeness
|
||||
|
||||
TASK:
|
||||
• L1 (Unit Tests): Suggest edge cases, boundary conditions, error paths, state transitions
|
||||
• L2.1 (Integration): Suggest module interaction patterns, dependency injection scenarios
|
||||
• L2.2 (API Contracts): Suggest request/response test cases, validation, status codes, error responses
|
||||
• L2.4 (External APIs): Suggest mock strategies, failure scenarios, timeout handling, retry logic
|
||||
• L2.5 (Failure Modes): Suggest exception hierarchies, error propagation, recovery strategies
|
||||
• Cross-cutting: Suggest performance test cases, security considerations
|
||||
|
||||
MODE: analysis
|
||||
|
||||
CONTEXT: @.workflow/active/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md
|
||||
Memory: Project type, test framework, existing test patterns, coverage gaps
|
||||
|
||||
EXPECTED: Markdown report with structured test enhancement suggestions organized by:
|
||||
1. File-level test requirements (per file needing tests)
|
||||
2. Layer-specific test cases (L1, L2.1, L2.2, L2.4, L2.5)
|
||||
3. Each suggestion includes:
|
||||
- Test type and layer (e.g., "L2.2 API Contract Test")
|
||||
- Specific test case description (e.g., "POST /api/users - Invalid email format")
|
||||
- Expected behavior (e.g., "Returns 400 with validation error message")
|
||||
- Dependencies/mocks needed (e.g., "Mock email service")
|
||||
- Success criteria (e.g., "Status 400, error.field === 'email'")
|
||||
4. Test ordering/dependencies (which tests should run first)
|
||||
5. Integration test strategies (how components interact)
|
||||
6. Error scenario matrix (all failure modes covered)
|
||||
|
||||
CONSTRAINTS:
|
||||
- Focus on identified coverage gaps from TEST_ANALYSIS_RESULTS.md
|
||||
- Prioritize API tests, integration tests, and error scenarios
|
||||
- No code generation - suggestions only with sufficient detail for implementation
|
||||
- Consider project conventions and existing test patterns
|
||||
- Each suggestion should be actionable and specific (not generic)
|
||||
- Output format: Markdown with clear section headers
|
||||
@@ -0,0 +1,179 @@
|
||||
PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
|
||||
TASK:
|
||||
• Read test-context-package.json to understand coverage gaps and framework
|
||||
• Study implementation context from source session summaries
|
||||
• Analyze existing test patterns and conventions
|
||||
• Design test requirements for missing coverage
|
||||
• Generate actionable test generation strategy
|
||||
MODE: analysis
|
||||
CONTEXT: @test-context-package.json @../../../{source-session-id}/.summaries/*.md
|
||||
EXPECTED: Comprehensive test analysis document (gemini-test-analysis.md) with test requirements, scenarios, and generation strategy
|
||||
RULES:
|
||||
- Focus on test requirements and strategy, NOT code generation
|
||||
- Study existing test patterns for consistency
|
||||
- Prioritize critical business logic tests
|
||||
- Specify clear test scenarios and coverage targets
|
||||
- Identify all dependencies requiring mocks
|
||||
- Output ONLY test analysis and generation strategy
|
||||
|
||||
## ANALYSIS REQUIREMENTS
|
||||
|
||||
### 1. Implementation Understanding
|
||||
- Load all implementation summaries from source session
|
||||
- Understand implemented features, APIs, and business logic
|
||||
- Extract key functions, classes, and modules
|
||||
- Identify integration points and dependencies
|
||||
|
||||
### 2. Existing Test Pattern Analysis
|
||||
- Study existing test files for patterns and conventions
|
||||
- Identify test structure (describe/it, test suites, fixtures)
|
||||
- Analyze assertion patterns and mocking strategies
|
||||
- Extract test setup/teardown patterns
|
||||
|
||||
### 3. Coverage Gap Assessment
|
||||
For each file in missing_tests[], analyze:
|
||||
- File purpose and functionality
|
||||
- Public APIs requiring test coverage
|
||||
- Critical paths and edge cases
|
||||
- Integration points requiring tests
|
||||
- Priority: high (core logic), medium (utilities), low (helpers)
|
||||
|
||||
### 4. Test Requirements Specification
|
||||
For each missing test file, specify:
|
||||
- Test scope: What needs to be tested
|
||||
- Test scenarios: Happy path, error cases, edge cases, integration
|
||||
- Test data: Required fixtures, mocks, test data
|
||||
- Dependencies: External services, databases, APIs to mock
|
||||
- Coverage targets: Functions/methods requiring tests
|
||||
|
||||
### 5. Test Generation Strategy
|
||||
- Determine test generation approach for each file
|
||||
- Identify reusable test patterns from existing tests
|
||||
- Plan test data and fixture requirements
|
||||
- Define mocking strategy for dependencies
|
||||
- Specify expected test file structure
|
||||
|
||||
## EXPECTED OUTPUT FORMAT
|
||||
|
||||
Write comprehensive analysis to gemini-test-analysis.md:
|
||||
|
||||
# Test Generation Analysis
|
||||
|
||||
## 1. Implementation Context Summary
|
||||
- **Source Session**: {source_session_id}
|
||||
- **Implemented Features**: {feature_summary}
|
||||
- **Changed Files**: {list_of_implementation_files}
|
||||
- **Tech Stack**: {technologies_used}
|
||||
|
||||
## 2. Test Coverage Assessment
|
||||
- **Existing Tests**: {count} files
|
||||
- **Missing Tests**: {count} files
|
||||
- **Coverage Percentage**: {percentage}%
|
||||
- **Priority Breakdown**:
|
||||
- High Priority: {count} files (core business logic)
|
||||
- Medium Priority: {count} files (utilities, helpers)
|
||||
- Low Priority: {count} files (configuration, constants)
|
||||
|
||||
## 3. Existing Test Pattern Analysis
|
||||
- **Test Framework**: {framework_name_and_version}
|
||||
- **File Naming Convention**: {pattern}
|
||||
- **Test Structure**: {describe_it_or_other}
|
||||
- **Assertion Style**: {expect_assert_should}
|
||||
- **Mocking Strategy**: {mocking_framework_and_patterns}
|
||||
- **Setup/Teardown**: {beforeEach_afterEach_patterns}
|
||||
- **Test Data**: {fixtures_factories_builders}
|
||||
|
||||
## 4. Test Requirements by File
|
||||
|
||||
### File: {implementation_file_path}
|
||||
**Test File**: {suggested_test_file_path}
|
||||
**Priority**: {high|medium|low}
|
||||
|
||||
#### Scope
|
||||
- {description_of_what_needs_testing}
|
||||
|
||||
#### Test Scenarios
|
||||
1. **Happy Path Tests**
|
||||
- {scenario_1}
|
||||
- {scenario_2}
|
||||
|
||||
2. **Error Handling Tests**
|
||||
- {error_scenario_1}
|
||||
- {error_scenario_2}
|
||||
|
||||
3. **Edge Case Tests**
|
||||
- {edge_case_1}
|
||||
- {edge_case_2}
|
||||
|
||||
4. **Integration Tests** (if applicable)
|
||||
- {integration_scenario_1}
|
||||
- {integration_scenario_2}
|
||||
|
||||
#### Test Data & Fixtures
|
||||
- {required_test_data}
|
||||
- {required_mocks}
|
||||
- {required_fixtures}
|
||||
|
||||
#### Dependencies to Mock
|
||||
- {external_service_1}
|
||||
- {external_service_2}
|
||||
|
||||
#### Coverage Targets
|
||||
- Function: {function_name} - {test_requirements}
|
||||
- Function: {function_name} - {test_requirements}
|
||||
|
||||
---
|
||||
[Repeat for each missing test file]
|
||||
---
|
||||
|
||||
## 5. Test Generation Strategy
|
||||
|
||||
### Overall Approach
|
||||
- {strategy_description}
|
||||
|
||||
### Test Generation Order
|
||||
1. {file_1} - {rationale}
|
||||
2. {file_2} - {rationale}
|
||||
3. {file_3} - {rationale}
|
||||
|
||||
### Reusable Patterns
|
||||
- {pattern_1_from_existing_tests}
|
||||
- {pattern_2_from_existing_tests}
|
||||
|
||||
### Test Data Strategy
|
||||
- {approach_to_test_data_and_fixtures}
|
||||
|
||||
### Mocking Strategy
|
||||
- {approach_to_mocking_dependencies}
|
||||
|
||||
### Quality Criteria
|
||||
- Code coverage target: {percentage}%
|
||||
- Test scenarios per function: {count}
|
||||
- Integration test coverage: {approach}
|
||||
|
||||
## 6. Implementation Targets
|
||||
|
||||
**Purpose**: Identify new test files to create
|
||||
|
||||
**Format**: New test files only (no existing files to modify)
|
||||
|
||||
**Test Files to Create**:
|
||||
1. **Target**: `tests/auth/TokenValidator.test.ts`
|
||||
- **Type**: Create new test file
|
||||
- **Purpose**: Test TokenValidator class
|
||||
- **Scenarios**: 15 test cases covering validation logic, error handling, edge cases
|
||||
- **Dependencies**: Mock JWT library, test fixtures for tokens
|
||||
|
||||
2. **Target**: `tests/middleware/errorHandler.test.ts`
|
||||
- **Type**: Create new test file
|
||||
- **Purpose**: Test error handling middleware
|
||||
- **Scenarios**: 8 test cases for different error types and response formats
|
||||
- **Dependencies**: Mock Express req/res/next, error fixtures
|
||||
|
||||
[List all test files to create]
|
||||
|
||||
## 7. Success Metrics
|
||||
- **Test Coverage Goal**: {target_percentage}%
|
||||
- **Test Quality**: All scenarios covered (happy, error, edge, integration)
|
||||
- **Convention Compliance**: Follow existing test patterns
|
||||
- **Maintainability**: Clear test descriptions, reusable fixtures
|
||||
@@ -0,0 +1,95 @@
|
||||
# AI Prompt: Universal Creative Exploration Template (Chinese Output)
|
||||
|
||||
## I. CORE DIRECTIVE
|
||||
You are an **Innovative Problem-Solving Catalyst**. Approach tasks with creative thinking, explore multiple solution paths, and generate novel approaches while maintaining practical viability. Responses **MUST** be in **Chinese (中文)**.
|
||||
|
||||
## II. CORE CAPABILITIES & THINKING MODE
|
||||
**Capabilities**: Divergent thinking, pattern recognition, creative synthesis, constraint reframing, rapid prototyping, contextual adaptation, elegant simplicity, future-oriented design
|
||||
|
||||
**Thinking Mode**: Exploratory & open-minded, adaptive & flexible, synthesis-driven, innovation-focused
|
||||
|
||||
## III. EXPLORATION PHASES
|
||||
**Divergent Phase**: Multiple perspectives, analogies & metaphors, constraint questioning, alternative approaches (3+), what-if scenarios
|
||||
**Convergent Phase**: Pattern integration, practical viability, elegant simplicity, context optimization, future proofing
|
||||
**Validation Phase**: Constraint compliance, risk assessment, proof of concept, iterative refinement, documentation
|
||||
|
||||
## IV. QUALITY STANDARDS
|
||||
**Innovation**: Novelty, elegance, effectiveness, flexibility, insight, viability
|
||||
**Process**: Exploration breadth, synthesis quality, justification clarity, alternatives documented
|
||||
|
||||
## V. RESPONSE STRUCTURE (Output in Chinese)
|
||||
|
||||
---
|
||||
|
||||
### 0. 创造性思考过程 (Creative Thinking Process)
|
||||
* **问题重构**: 从多个角度理解和重新定义问题
|
||||
* **灵感来源**: 识别可借鉴的模式、类比或跨领域经验
|
||||
* **可能性空间**: 探索不同解决方案的可能性
|
||||
* **约束与自由**: 识别硬性约束与创新空间
|
||||
* **综合策略**: 规划如何整合不同思路形成最优方案
|
||||
|
||||
### 1. 问题深度理解 (Deep Problem Understanding)
|
||||
* **表层需求**: 明确的功能和非功能需求
|
||||
* **隐含目标**: 未明说但重要的用户期望和体验目标
|
||||
* **约束条件**: 必须遵守的技术和业务约束
|
||||
* **机会空间**: 可以创新和优化的领域
|
||||
|
||||
### 2. 多角度探索 (Multi-Perspective Exploration)
|
||||
* **视角1-3**: 从不同角度分析问题，每个视角包含：核心洞察、解决思路、优势与局限
|
||||
|
||||
### 3. 跨领域类比 (Cross-Domain Analogies)
|
||||
* **类比1-2**: 相关领域或模式，说明如何应用到当前问题
|
||||
|
||||
### 4. 候选方案生成 (Solution Candidates - 2-3个)
|
||||
* **方案A/B/C**: 每个方案包含：核心思路、关键特点、优势、潜在挑战、适用场景
|
||||
|
||||
### 5. 方案综合与优化 (Solution Synthesis & Optimization)
|
||||
* **选择理由**: 为什么选择或综合某些方案
|
||||
* **综合策略**: 如何结合不同方案的优点
|
||||
* **简化优化**: 如何使方案更简洁优雅
|
||||
* **创新点**: 方案的独特价值和创新之处
|
||||
|
||||
### 6. 实施细节与代码 (Implementation Details & Code)
|
||||
* **架构设计**: 清晰的结构设计
|
||||
* **核心实现**: 关键功能的实现
|
||||
* **扩展点**: 预留的扩展和定制接口
|
||||
* **优雅之处**: 设计中的巧妙和优雅元素
|
||||
|
||||
### 7. 验证与迭代 (Validation & Iteration)
|
||||
* **快速验证**: 如何快速验证核心假设
|
||||
* **迭代路径**: 从MVP到完整方案的演进路径
|
||||
* **反馈机制**: 如何收集反馈并改进
|
||||
* **风险应对**: 主要风险和应对策略
|
||||
|
||||
### 8. 替代方案记录 (Alternative Approaches)
|
||||
* **未采纳方案**: 列出其他考虑过的方案
|
||||
* **未来可能性**: 可能在未来更合适的方案
|
||||
* **经验教训**: 从探索过程中学到的洞察
|
||||
|
||||
### 9. 总结与展望 (Summary & Future Vision)
|
||||
* **核心价值**: 该方案的核心价值和创新点
|
||||
* **关键决策**: 重要的设计决策及其理由
|
||||
* **扩展可能**: 未来可能的扩展方向
|
||||
* **开放性**: 留下的开放问题和探索空间
|
||||
|
||||
---
|
||||
|
||||
## VI. STYLE & CONSTRAINTS
|
||||
**Style**: Exploratory & open, insightful & thoughtful, enthusiastic & positive, clear & inspiring, balanced & practical
|
||||
|
||||
**Core Constraints**:
|
||||
- Practical viability - innovation must be implementable
|
||||
- Constraint awareness - creativity within boundaries
|
||||
- Value-driven - innovation must add real value
|
||||
- Simplicity preference - elegant solutions over complex ones
|
||||
- Documentation - alternative approaches must be recorded
|
||||
- Justification - creative choices must be reasoned
|
||||
- Iterative mindset - embrace refinement and evolution
|
||||
|
||||
## VII. CREATIVE THINKING TECHNIQUES (Optional)
|
||||
**Toolkit**: First principles thinking, inversion, constraint removal, analogical reasoning, combination & synthesis, abstraction ladder, pattern languages, what-if scenarios
|
||||
|
||||
**Application**: Select 2-3 techniques, apply during divergent phase, document insights, inform synthesis
|
||||
|
||||
## VIII. FINAL VALIDATION
|
||||
Before finalizing, verify: Multiple perspectives explored, 2-3 distinct approaches considered, cross-domain analogies identified, solution elegance pursued, practical constraints respected, innovation points articulated, alternatives documented, implementation viable, future extensibility considered, rationale clear
|
||||
@@ -0,0 +1,92 @@
|
||||
# AI Prompt: Universal Rigorous Execution Template (Chinese Output)
|
||||
|
||||
## I. CORE DIRECTIVE
|
||||
You are a **Precision-Driven Expert System**. Execute tasks with rigorous accuracy, systematic validation, and adherence to standards. Responses **MUST** be in **Chinese (中文)**.
|
||||
|
||||
## II. CORE CAPABILITIES & THINKING MODE
|
||||
**Capabilities**: Systematic methodology, specification adherence, validation & verification, edge case handling, error prevention, formal reasoning, documentation excellence, quality assurance
|
||||
|
||||
**Thinking Mode**: Rigorous & methodical, defensive & cautious, standards-driven, traceable & auditable
|
||||
|
||||
## III. EXECUTION CHECKLIST
|
||||
**Before Starting**: Clarify requirements, identify standards, plan validation, assess risks
|
||||
**During Execution**: Follow patterns, validate continuously, handle edge cases, maintain consistency, document decisions
|
||||
**After Completion**: Comprehensive testing, code review, backward compatibility, documentation update
|
||||
|
||||
## IV. QUALITY STANDARDS
|
||||
**Code**: Correctness, robustness, maintainability, performance, security, testability
|
||||
**Process**: Repeatability, traceability, reversibility, incremental progress
|
||||
|
||||
## V. RESPONSE STRUCTURE (Output in Chinese)
|
||||
|
||||
---
|
||||
|
||||
### 0. 规范性思考过程 (Rigorous Thinking Process)
|
||||
* **任务理解**: 明确任务目标、范围和约束条件
|
||||
* **标准识别**: 确定适用的规范、最佳实践和质量标准
|
||||
* **风险分析**: 识别潜在问题、边界条件和失败模式
|
||||
* **验证计划**: 定义成功标准和验证检查点
|
||||
* **执行策略**: 制定系统化、可追溯的实施方案
|
||||
|
||||
### 1. 需求分析与验证 (Requirement Analysis & Validation)
|
||||
* **核心需求**: 列出所有明确的功能和非功能需求
|
||||
* **隐式约束**: 识别未明确说明但必须遵守的约束
|
||||
* **边界条件**: 明确输入范围、特殊情况和异常场景
|
||||
* **验证标准**: 定义可测试的成功标准
|
||||
|
||||
### 2. 标准与模式分析 (Standards & Pattern Analysis)
|
||||
* **适用标准**: 列出相关编码规范、设计模式、最佳实践
|
||||
* **现有模式**: 识别项目中类似的成功实现
|
||||
* **依赖关系**: 分析与现有代码的集成点和依赖
|
||||
* **兼容性要求**: 确保向后兼容和接口稳定性
|
||||
|
||||
### 3. 详细实施方案 (Detailed Implementation Plan)
|
||||
* **分解步骤**: 将任务分解为小的、可验证的步骤
|
||||
* **关键决策**: 记录所有重要的技术决策及其理由
|
||||
* **边界处理**: 说明如何处理边界条件和错误情况
|
||||
* **验证点**: 在每个步骤设置验证检查点
|
||||
|
||||
### 4. 实施细节与代码 (Implementation Details & Code)
|
||||
* **核心逻辑**: 实现主要功能,确保正确性
|
||||
* **错误处理**: 完善的异常捕获和错误处理
|
||||
* **输入验证**: 严格的输入校验和边界检查
|
||||
* **代码注释**: 关键逻辑的清晰注释说明
|
||||
|
||||
### 5. 测试与验证 (Testing & Validation)
|
||||
* **单元测试**: 覆盖所有主要功能和边界条件
|
||||
* **集成测试**: 验证与现有系统的集成
|
||||
* **边界测试**: 测试极端情况和异常输入
|
||||
* **回归测试**: 确保未破坏现有功能
|
||||
|
||||
### 6. 质量检查清单 (Quality Checklist)
|
||||
- [ ] 功能完整性: 所有需求都已实现
|
||||
- [ ] 规范遵循: 符合代码规范和最佳实践
|
||||
- [ ] 边界处理: 所有边界条件都已处理
|
||||
- [ ] 错误处理: 完善的异常处理机制
|
||||
- [ ] 向后兼容: 未破坏现有功能
|
||||
- [ ] 文档完整: 代码注释和文档齐全
|
||||
- [ ] 测试覆盖: 全面的测试覆盖
|
||||
- [ ] 性能优化: 符合性能要求
|
||||
|
||||
### 7. 总结与建议 (Summary & Recommendations)
|
||||
* **实施总结**: 简要总结完成的工作
|
||||
* **关键决策**: 重申重要技术决策
|
||||
* **后续建议**: 提出改进和优化建议
|
||||
* **风险提示**: 指出需要关注的潜在问题
|
||||
|
||||
---
|
||||
|
||||
## VI. STYLE & CONSTRAINTS
|
||||
**Style**: Formal & professional, precise & unambiguous, evidence-based, defensive & cautious, structured & systematic
|
||||
|
||||
**Core Constraints**:
|
||||
- Zero tolerance for errors - correctness is paramount
|
||||
- Standards compliance - follow established conventions
|
||||
- Complete validation - all assumptions must be validated
|
||||
- Comprehensive testing - all paths must be tested
|
||||
- Full documentation - all decisions must be documented
|
||||
- Backward compatibility - existing functionality is sacred
|
||||
- No shortcuts - quality cannot be compromised
|
||||
|
||||
## VII. FINAL VALIDATION
|
||||
Before finalizing, verify: All requirements addressed, edge cases handled, standards followed, decisions documented, code tested, documentation complete, backward compatibility maintained, quality standards met
|
||||
@@ -0,0 +1,28 @@
|
||||
Assess the technical feasibility of a workflow implementation plan.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Evaluate implementation complexity and required skills
|
||||
□ Validate all technical dependencies and prerequisites
|
||||
□ Assess the proposed code structure and integration patterns
|
||||
□ Verify the completeness of the testing strategy
|
||||
|
||||
## REQUIRED TECHNICAL ANALYSIS
|
||||
1. **Implementation Complexity**: Evaluate code difficulty and required skills.
|
||||
2. **Technical Dependencies**: Review libraries, versions, and build systems.
|
||||
3. **Code Structure**: Assess file organization, naming, and modularity.
|
||||
4. **Testing Completeness**: Evaluate test coverage, types, and gaps.
|
||||
5. **Execution Readiness**: Validate control flow, context, and file targets.
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- **Technical Assessment Report**: Grades for implementation, complexity, and quality.
|
||||
- **Detailed Technical Findings**: Blocking issues, performance concerns, and improvements.
|
||||
- **Implementation Recommendations**: Prerequisites, best practices, and refactoring.
|
||||
- **Risk Mitigation**: Technical, dependency, integration, and quality risks.
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Implementation complexity and feasibility have been thoroughly evaluated
|
||||
□ All technical dependencies and prerequisites are validated
|
||||
□ The proposed code structure aligns with project standards
|
||||
□ The testing plan is complete and adequate for the proposed changes
|
||||
|
||||
Focus: Technical execution details, code quality concerns, and implementation feasibility.
|
||||
@@ -0,0 +1,28 @@
|
||||
Cross-validate strategic (Gemini) and technical (Codex) assessments.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Identify both consensus and conflict between the two analyses
|
||||
□ Synthesize a unified risk profile and recommendation set
|
||||
□ Resolve conflicting suggestions with a balanced approach
|
||||
□ Frame final decisions as clear choices for the user
|
||||
|
||||
## REQUIRED CROSS-VALIDATION ANALYSIS
|
||||
1. **Consensus Identification**: Find where both analyses agree.
|
||||
2. **Conflict Resolution**: Analyze and resolve discrepancies.
|
||||
3. **Risk Level Synthesis**: Combine risk assessments into a single profile.
|
||||
4. **Recommendation Integration**: Synthesize recommendations into a unified plan.
|
||||
5. **Quality Assurance Framework**: Establish combined quality metrics.
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- **Cross-Validation Summary**: Overall grade, confidence score, and risk profile.
|
||||
- **Synthesis Report**: Consensus areas, conflict areas, and integrated recommendations.
|
||||
- **User Approval Framework**: A clear breakdown of changes for user approval.
|
||||
- **Modification Categories**: Classify changes by type (e.g., Task Structure, Technical).
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Both consensus and conflict between analyses are identified and documented
|
||||
□ Risks and recommendations are synthesized into a single, coherent plan
|
||||
□ Conflicting points are resolved with balanced, well-reasoned proposals
|
||||
□ Final output is structured to facilitate clear user decisions
|
||||
|
||||
Focus: A balanced integration of strategic and technical perspectives to produce a single, actionable plan.
|
||||
@@ -0,0 +1,27 @@
|
||||
Validate the strategic and architectural soundness of a workflow implementation plan.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Evaluate the plan against high-level system architecture
|
||||
□ Assess the logic of the task breakdown and dependencies
|
||||
□ Verify alignment with stated business objectives and success criteria
|
||||
□ Identify strategic risks, not just low-level technical ones
|
||||
|
||||
## REQUIRED STRATEGIC ANALYSIS
|
||||
1. **Architectural Soundness**: Assess design coherence and pattern consistency.
|
||||
2. **Task Decomposition Logic**: Review task breakdown, granularity, and completeness.
|
||||
3. **Dependency Coherence**: Analyze task interdependencies and logical flow.
|
||||
4. **Business Alignment**: Validate against business objectives and requirements.
|
||||
5. **Strategic Risk Identification**: Identify architectural, resource, and timeline risks.
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
- **Strategic Assessment Report**: Grades for architecture, decomposition, and business alignment.
|
||||
- **Detailed Recommendations**: Critical issues, improvements, and alternative approaches.
|
||||
- **Action Items**: A prioritized list of changes (Immediate, Short-term, Long-term).
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ The plan's architectural soundness has been thoroughly assessed
|
||||
□ Task decomposition and dependencies are logical and coherent
|
||||
□ The plan is confirmed to be in alignment with business goals
|
||||
□ Strategic risks are identified with clear recommendations
|
||||
|
||||
Focus: High-level strategic concerns, business alignment, and long-term architectural implications.
|
||||
@@ -0,0 +1,224 @@
|
||||
Generate ANALYSIS_RESULTS.md with comprehensive solution design and technical analysis.
|
||||
|
||||
## OUTPUT FILE STRUCTURE
|
||||
|
||||
### Required Sections
|
||||
|
||||
```markdown
|
||||
# Technical Analysis & Solution Design
|
||||
|
||||
## Executive Summary
|
||||
- **Analysis Focus**: {core_problem_or_improvement_area}
|
||||
- **Analysis Timestamp**: {timestamp}
|
||||
- **Tools Used**: {analysis_tools}
|
||||
- **Overall Assessment**: {feasibility_score}/5 - {recommendation_status}
|
||||
|
||||
---
|
||||
|
||||
## 1. Current State Analysis
|
||||
|
||||
### Architecture Overview
|
||||
- **Existing Patterns**: {key_architectural_patterns}
|
||||
- **Code Structure**: {current_codebase_organization}
|
||||
- **Integration Points**: {system_integration_touchpoints}
|
||||
- **Technical Debt Areas**: {identified_debt_with_impact}
|
||||
|
||||
### Compatibility & Dependencies
|
||||
- **Framework Alignment**: {framework_compatibility_assessment}
|
||||
- **Dependency Analysis**: {critical_dependencies_and_risks}
|
||||
- **Migration Considerations**: {backward_compatibility_concerns}
|
||||
|
||||
### Critical Findings
|
||||
- **Strengths**: {what_works_well}
|
||||
- **Gaps**: {missing_capabilities_or_issues}
|
||||
- **Risks**: {identified_technical_and_business_risks}
|
||||
|
||||
---
|
||||
|
||||
## 2. Proposed Solution Design
|
||||
|
||||
### Core Architecture Principles
|
||||
- **Design Philosophy**: {key_design_principles}
|
||||
- **Architectural Approach**: {chosen_architectural_pattern_with_rationale}
|
||||
- **Scalability Strategy**: {how_solution_scales}
|
||||
|
||||
### System Design
|
||||
- **Component Architecture**: {high_level_component_design}
|
||||
- **Data Flow**: {data_flow_patterns_and_state_management}
|
||||
- **API Design**: {interface_contracts_and_specifications}
|
||||
- **Integration Strategy**: {how_components_integrate}
|
||||
|
||||
### Key Design Decisions
|
||||
1. **Decision**: {critical_design_choice}
|
||||
- **Rationale**: {why_this_approach}
|
||||
- **Alternatives Considered**: {other_options_and_tradeoffs}
|
||||
- **Impact**: {implications_on_architecture}
|
||||
|
||||
2. **Decision**: {another_critical_choice}
|
||||
- **Rationale**: {reasoning}
|
||||
- **Alternatives Considered**: {tradeoffs}
|
||||
- **Impact**: {consequences}
|
||||
|
||||
### Technical Specifications
|
||||
- **Technology Stack**: {chosen_technologies_with_justification}
|
||||
- **Code Organization**: {module_structure_and_patterns}
|
||||
- **Testing Strategy**: {testing_approach_and_coverage}
|
||||
- **Performance Targets**: {performance_requirements_and_benchmarks}
|
||||
|
||||
---
|
||||
|
||||
## 3. Implementation Strategy
|
||||
|
||||
### Development Approach
|
||||
- **Core Implementation Pattern**: {primary_implementation_strategy}
|
||||
- **Module Dependencies**: {dependency_graph_and_order}
|
||||
- **Quality Assurance**: {qa_approach_and_validation}
|
||||
|
||||
### Code Modification Targets
|
||||
**Purpose**: Specific code locations for modification AND new files to create
|
||||
|
||||
**Identified Targets**:
|
||||
1. **Target**: `src/module/File.ts:function:45-52`
|
||||
- **Type**: Modify existing
|
||||
- **Modification**: {what_to_change}
|
||||
- **Rationale**: {why_change_needed}
|
||||
|
||||
2. **Target**: `src/module/NewFile.ts`
|
||||
- **Type**: Create new file
|
||||
- **Purpose**: {file_purpose}
|
||||
- **Rationale**: {why_new_file_needed}
|
||||
|
||||
**Format Rules**:
|
||||
- Existing files: `file:function:lines` (with line numbers)
|
||||
- New files: `file` (no function or lines)
|
||||
- Unknown lines: `file:function:*`
|
||||
|
||||
### Feasibility Assessment
|
||||
- **Technical Complexity**: {complexity_rating_and_analysis}
|
||||
- **Performance Impact**: {expected_performance_characteristics}
|
||||
- **Resource Requirements**: {development_resources_needed}
|
||||
- **Maintenance Burden**: {ongoing_maintenance_considerations}
|
||||
|
||||
### Risk Mitigation
|
||||
- **Technical Risks**: {implementation_risks_and_mitigation}
|
||||
- **Integration Risks**: {compatibility_challenges_and_solutions}
|
||||
- **Performance Risks**: {performance_concerns_and_strategies}
|
||||
- **Security Risks**: {security_vulnerabilities_and_controls}
|
||||
|
||||
---
|
||||
|
||||
## 4. Solution Optimization
|
||||
|
||||
### Performance Optimization
|
||||
- **Optimization Strategies**: {key_performance_improvements}
|
||||
- **Caching Strategy**: {caching_approach_and_invalidation}
|
||||
- **Resource Management**: {resource_utilization_optimization}
|
||||
- **Bottleneck Mitigation**: {identified_bottlenecks_and_solutions}
|
||||
|
||||
### Security Enhancements
|
||||
- **Security Model**: {authentication_authorization_approach}
|
||||
- **Data Protection**: {data_security_and_encryption}
|
||||
- **Vulnerability Mitigation**: {known_vulnerabilities_and_controls}
|
||||
- **Compliance**: {regulatory_and_compliance_considerations}
|
||||
|
||||
### Code Quality
|
||||
- **Code Standards**: {coding_conventions_and_patterns}
|
||||
- **Testing Coverage**: {test_strategy_and_coverage_goals}
|
||||
- **Documentation**: {documentation_requirements}
|
||||
- **Maintainability**: {maintainability_practices}
|
||||
|
||||
---
|
||||
|
||||
## 5. Critical Success Factors
|
||||
|
||||
### Technical Requirements
|
||||
- **Must Have**: {essential_technical_capabilities}
|
||||
- **Should Have**: {important_but_not_critical_features}
|
||||
- **Nice to Have**: {optional_enhancements}
|
||||
|
||||
### Quality Metrics
|
||||
- **Performance Benchmarks**: {measurable_performance_targets}
|
||||
- **Code Quality Standards**: {quality_metrics_and_thresholds}
|
||||
- **Test Coverage Goals**: {testing_coverage_requirements}
|
||||
- **Security Standards**: {security_compliance_requirements}
|
||||
|
||||
### Success Validation
|
||||
- **Acceptance Criteria**: {how_to_validate_success}
|
||||
- **Testing Strategy**: {validation_testing_approach}
|
||||
- **Monitoring Plan**: {production_monitoring_strategy}
|
||||
- **Rollback Plan**: {failure_recovery_strategy}
|
||||
|
||||
---
|
||||
|
||||
## 6. Analysis Confidence & Recommendations
|
||||
|
||||
### Assessment Scores
|
||||
- **Conceptual Integrity**: {score}/5 - {brief_assessment}
|
||||
- **Architectural Soundness**: {score}/5 - {brief_assessment}
|
||||
- **Technical Feasibility**: {score}/5 - {brief_assessment}
|
||||
- **Implementation Readiness**: {score}/5 - {brief_assessment}
|
||||
- **Overall Confidence**: {overall_score}/5
|
||||
|
||||
### Final Recommendation
|
||||
**Status**: {PROCEED|PROCEED_WITH_MODIFICATIONS|RECONSIDER|REJECT}
|
||||
|
||||
**Rationale**: {clear_explanation_of_recommendation}
|
||||
|
||||
**Critical Prerequisites**: {what_must_be_resolved_before_proceeding}
|
||||
|
||||
---
|
||||
|
||||
## 7. Reference Information
|
||||
|
||||
### Tool Analysis Summary
|
||||
- **Gemini Insights**: {key_architectural_and_pattern_insights}
|
||||
- **Codex Validation**: {technical_feasibility_and_implementation_notes}
|
||||
- **Consensus Points**: {agreements_between_tools}
|
||||
- **Conflicting Views**: {disagreements_and_resolution}
|
||||
|
||||
### Context & Resources
|
||||
- **Analysis Context**: {context_package_reference}
|
||||
- **Documentation References**: {relevant_documentation}
|
||||
- **Related Patterns**: {similar_implementations_in_codebase}
|
||||
- **External Resources**: {external_references_and_best_practices}
|
||||
```
|
||||
|
||||
## CONTENT REQUIREMENTS
|
||||
|
||||
### Analysis Priority Sources
|
||||
1. **PRIMARY**: Individual role analysis.md files (system-architect, ui-designer, etc.) - technical details, ADRs, decision context
|
||||
2. **SECONDARY**: role analysis documents - multi-perspective requirements and design specs
|
||||
3. **REFERENCE**: guidance-specification.md - discussion context
|
||||
|
||||
### Focus Areas
|
||||
- **SOLUTION IMPROVEMENTS**: How to enhance current design
|
||||
- **KEY DESIGN DECISIONS**: Critical choices with rationale, alternatives, tradeoffs
|
||||
- **CRITICAL INSIGHTS**: Non-obvious findings, risks, opportunities
|
||||
- **OPTIMIZATION**: Performance, security, code quality recommendations
|
||||
|
||||
### Exclusions
|
||||
- ❌ Task lists or implementation steps
|
||||
- ❌ Code examples or snippets
|
||||
- ❌ Project management timelines
|
||||
- ❌ Resource allocation details
|
||||
|
||||
## OUTPUT VALIDATION
|
||||
|
||||
### Completeness Checklist
|
||||
□ All 7 sections present with content
|
||||
□ Executive Summary with feasibility score
|
||||
□ Current State Analysis with findings
|
||||
□ Solution Design with 2+ key decisions
|
||||
□ Implementation Strategy with code targets
|
||||
□ Optimization recommendations in 3 areas
|
||||
□ Confidence scores with final recommendation
|
||||
□ Reference information included
|
||||
|
||||
### Quality Standards
|
||||
□ Design decisions include rationale and alternatives
|
||||
□ Code targets specify file:function:lines format
|
||||
□ Risk assessment with mitigation strategies
|
||||
□ Quantified scores (X/5) for all assessments
|
||||
□ Clear PROCEED/RECONSIDER/REJECT recommendation
|
||||
|
||||
Focus: Solution-focused technical analysis emphasizing design decisions and critical insights.
|
||||
@@ -0,0 +1,176 @@
|
||||
Validate technical feasibility and identify implementation risks for proposed solution design.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Read context-package.json and gemini-solution-design.md
|
||||
□ Assess complexity, validate technology choices
|
||||
□ Evaluate performance and security implications
|
||||
□ Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT
|
||||
□ Write output to specified .workflow/active/{session_id}/.process/ path
|
||||
|
||||
## PREREQUISITE ANALYSIS
|
||||
|
||||
### Required Input Files
|
||||
1. **context-package.json**: Task requirements, source files, tech stack
|
||||
2. **gemini-solution-design.md**: Proposed solution design and architecture
|
||||
3. **workflow-session.json**: Session state and context
|
||||
4. **CLAUDE.md**: Project standards and conventions
|
||||
|
||||
### Analysis Dependencies
|
||||
- Review Gemini's proposed solution design
|
||||
- Validate against actual codebase capabilities
|
||||
- Assess implementation complexity realistically
|
||||
- Identify gaps between design and execution
|
||||
|
||||
## REQUIRED VALIDATION
|
||||
|
||||
### 1. Feasibility Assessment
|
||||
- **Complexity Rating**: Rate technical complexity (1-5 scale)
|
||||
- 1: Trivial - straightforward implementation
|
||||
- 2: Simple - well-known patterns
|
||||
- 3: Moderate - some challenges
|
||||
- 4: Complex - significant challenges
|
||||
- 5: Very Complex - high risk, major unknowns
|
||||
|
||||
- **Resource Requirements**: Estimate development effort
|
||||
- Development time (hours/days/weeks)
|
||||
- Required expertise level
|
||||
- Infrastructure needs
|
||||
|
||||
- **Technology Compatibility**: Validate proposed tech stack
|
||||
- Framework version compatibility
|
||||
- Library maturity and support
|
||||
- Integration with existing systems
|
||||
|
||||
### 2. Risk Analysis
|
||||
- **Implementation Risks**: Technical challenges and blockers
|
||||
- Unknown implementation patterns
|
||||
- Missing capabilities or APIs
|
||||
- Breaking changes to existing code
|
||||
|
||||
- **Integration Challenges**: System integration concerns
|
||||
- Data format compatibility
|
||||
- API contract changes
|
||||
- Dependency conflicts
|
||||
|
||||
- **Performance Concerns**: Performance and scalability risks
|
||||
- Resource consumption (CPU, memory, I/O)
|
||||
- Latency and throughput impact
|
||||
- Caching and optimization needs
|
||||
|
||||
- **Security Concerns**: Security vulnerabilities and threats
|
||||
- Authentication/authorization gaps
|
||||
- Data exposure risks
|
||||
- Compliance violations
|
||||
|
||||
### 3. Implementation Validation
|
||||
- **Development Approach**: Validate proposed implementation strategy
|
||||
- Verify module dependency order
|
||||
- Assess incremental development feasibility
|
||||
- Evaluate testing approach
|
||||
|
||||
- **Quality Standards**: Validate quality requirements
|
||||
- Test coverage achievability
|
||||
- Performance benchmark realism
|
||||
- Documentation completeness
|
||||
|
||||
- **Maintenance Implications**: Long-term sustainability
|
||||
- Code maintainability assessment
|
||||
- Technical debt evaluation
|
||||
- Evolution and extensibility
|
||||
|
||||
### 4. Code Target Verification
|
||||
Review Gemini's proposed code targets:
|
||||
- **Validate existing targets**: Confirm file:function:lines exist
|
||||
- **Assess new file targets**: Evaluate necessity and placement
|
||||
- **Identify missing targets**: Suggest additional modification points
|
||||
- **Refine target specifications**: Provide more precise line numbers if possible
|
||||
|
||||
### 5. Recommendations
|
||||
- **Must-Have Requirements**: Critical requirements for success
|
||||
- **Optimization Opportunities**: Performance and quality improvements
|
||||
- **Security Controls**: Essential security measures
|
||||
- **Risk Mitigation**: Strategies to reduce identified risks
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
|
||||
### Output File
|
||||
**Path**: `.workflow/active/{session_id}/.process/codex-feasibility-validation.md`
|
||||
**Format**: Follow structure from `~/.ccw/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt`
|
||||
|
||||
### Required Sections
|
||||
Focus on these sections from the template:
|
||||
- Executive Summary (with Codex perspective)
|
||||
- Current State Analysis (validation findings)
|
||||
- Implementation Strategy (feasibility assessment)
|
||||
- Solution Optimization (risk mitigation)
|
||||
- Confidence Scores (technical feasibility focus)
|
||||
|
||||
### Content Guidelines
|
||||
- ✅ Focus on technical feasibility and risk assessment
|
||||
- ✅ Verify code targets from Gemini's design
|
||||
- ✅ Provide concrete risk mitigation strategies
|
||||
- ✅ Quantify complexity and effort estimates
|
||||
- ❌ Do NOT create task breakdowns
|
||||
- ❌ Do NOT provide step-by-step implementation guides
|
||||
- ❌ Do NOT include code examples
|
||||
|
||||
## VALIDATION METHODOLOGY
|
||||
|
||||
### Complexity Scoring
|
||||
Rate each aspect on 1-5 scale:
|
||||
- Technical Complexity
|
||||
- Integration Complexity
|
||||
- Performance Risk
|
||||
- Security Risk
|
||||
- Maintenance Burden
|
||||
|
||||
### Risk Classification
|
||||
- **LOW**: Minor issues, easily addressable
|
||||
- **MEDIUM**: Manageable challenges with clear mitigation
|
||||
- **HIGH**: Significant concerns requiring major mitigation
|
||||
- **CRITICAL**: Fundamental viability threats
|
||||
|
||||
### Feasibility Judgment
|
||||
- **PROCEED**: Technically feasible with acceptable risk
|
||||
- **PROCEED_WITH_MODIFICATIONS**: Feasible but needs adjustments
|
||||
- **RECONSIDER**: High risk, major changes needed
|
||||
- **REJECT**: Not feasible with current approach
|
||||
|
||||
## CONTEXT INTEGRATION
|
||||
|
||||
### Gemini Analysis Integration
|
||||
- Review proposed architecture and design decisions
|
||||
- Validate assumptions and technology choices
|
||||
- Cross-check code targets against actual codebase
|
||||
- Assess realism of performance targets
|
||||
|
||||
### Codebase Reality Check
|
||||
- Verify existing code capabilities
|
||||
- Identify actual technical constraints
|
||||
- Assess team skill compatibility
|
||||
- Evaluate infrastructure readiness
|
||||
|
||||
### Session Context
|
||||
- Consider session history and previous decisions
|
||||
- Align with project architecture standards
|
||||
- Respect existing patterns and conventions
|
||||
|
||||
## EXECUTION MODE
|
||||
|
||||
**Mode**: Analysis with write permission for output file
|
||||
**CLI Tool**: Codex with --skip-git-repo-check -s danger-full-access
|
||||
**Timeout**: 60-90 minutes for complex tasks
|
||||
**Output**: Single file codex-feasibility-validation.md
|
||||
**Trigger**: Only for complex tasks (>6 modules)
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ context-package.json and gemini-solution-design.md read
|
||||
□ Complexity rated on 1-5 scale with justification
|
||||
□ All risk categories assessed (technical, integration, performance, security)
|
||||
□ Code targets verified and refined
|
||||
□ Risk mitigation strategies provided
|
||||
□ Resource requirements estimated
|
||||
□ Final feasibility judgment (PROCEED/RECONSIDER/REJECT)
|
||||
□ Output written to .workflow/active/{session_id}/.process/codex-feasibility-validation.md
|
||||
|
||||
Focus: Technical feasibility validation with realistic risk assessment and mitigation strategies.
|
||||
@@ -0,0 +1,131 @@
|
||||
Analyze and design optimal solution with comprehensive architecture evaluation and design decisions.
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Read context-package.json to understand task requirements, source files, tech stack
|
||||
□ Analyze current architecture patterns and code structure
|
||||
□ Propose solution design with key decisions and rationale
|
||||
□ Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS
|
||||
□ Write output to specified .workflow/active/{session_id}/.process/ path
|
||||
|
||||
## ANALYSIS PRIORITY
|
||||
|
||||
### Source Hierarchy
|
||||
1. **PRIMARY**: Individual role analysis.md files (system-architect, ui-designer, data-architect, etc.)
|
||||
- Technical details and implementation considerations
|
||||
- Architecture Decision Records (ADRs)
|
||||
- Design decision context and rationale
|
||||
|
||||
2. **SECONDARY**: role analysis documents
|
||||
- Integrated requirements across roles
|
||||
- Cross-role alignment and dependencies
|
||||
- Unified feature specifications
|
||||
|
||||
3. **REFERENCE**: guidance-specification.md
|
||||
- Discussion context and background
|
||||
- Initial problem framing
|
||||
|
||||
## REQUIRED ANALYSIS
|
||||
|
||||
### 1. Current State Assessment
|
||||
- Identify existing architectural patterns and code structure
|
||||
- Map integration points and dependencies
|
||||
- Evaluate technical debt and pain points
|
||||
- Assess framework compatibility and constraints
|
||||
|
||||
### 2. Solution Design
|
||||
- Propose core architecture principles and approach
|
||||
- Design component architecture and data flow
|
||||
- Specify API contracts and integration strategy
|
||||
- Define technology stack with justification
|
||||
|
||||
### 3. Key Design Decisions
|
||||
For each critical decision:
|
||||
- **Decision**: What is being decided
|
||||
- **Rationale**: Why this approach
|
||||
- **Alternatives Considered**: Other options and their tradeoffs
|
||||
- **Impact**: Implications on architecture, performance, maintainability
|
||||
|
||||
Minimum 2 key decisions required.
|
||||
|
||||
### 4. Code Modification Targets
|
||||
Identify specific code locations for changes:
|
||||
- **Existing files**: `file:function:lines` format (e.g., `src/auth/login.ts:validateUser:45-52`)
|
||||
- **New files**: `file` only (e.g., `src/auth/PasswordReset.ts`)
|
||||
- **Unknown lines**: `file:function:*` (e.g., `src/auth/service.ts:refreshToken:*`)
|
||||
|
||||
For each target:
|
||||
- Type: Modify existing | Create new
|
||||
- Modification/Purpose: What changes needed
|
||||
- Rationale: Why this target
|
||||
|
||||
### 5. Critical Insights
|
||||
- Strengths: What works well in current/proposed design
|
||||
- Gaps: Missing capabilities or concerns
|
||||
- Risks: Technical, integration, performance, security
|
||||
- Optimization Opportunities: Performance, security, code quality
|
||||
|
||||
### 6. Feasibility Assessment
|
||||
- Technical Complexity: Rating and analysis
|
||||
- Performance Impact: Expected characteristics
|
||||
- Resource Requirements: Development effort
|
||||
- Maintenance Burden: Ongoing considerations
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
|
||||
### Output File
|
||||
**Path**: `.workflow/active/{session_id}/.process/gemini-solution-design.md`
|
||||
**Format**: Follow structure from `~/.ccw/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt`
|
||||
|
||||
### Required Sections
|
||||
- Executive Summary with feasibility score
|
||||
- Current State Analysis
|
||||
- Proposed Solution Design with 2+ key decisions
|
||||
- Implementation Strategy with code targets
|
||||
- Solution Optimization (performance, security, quality)
|
||||
- Critical Success Factors
|
||||
- Confidence Scores with recommendation
|
||||
|
||||
### Content Guidelines
|
||||
- ✅ Focus on solution improvements and key design decisions
|
||||
- ✅ Include rationale, alternatives, and tradeoffs for decisions
|
||||
- ✅ Provide specific code targets in correct format
|
||||
- ✅ Quantify assessments with scores (X/5)
|
||||
- ❌ Do NOT create task lists or implementation steps
|
||||
- ❌ Do NOT include code examples or snippets
|
||||
- ❌ Do NOT create project management timelines
|
||||
|
||||
## CONTEXT INTEGRATION
|
||||
|
||||
### Session Context
|
||||
- Load context-package.json for task requirements
|
||||
- Reference workflow-session.json for session state
|
||||
- Review CLAUDE.md for project standards
|
||||
|
||||
### Brainstorm Context
|
||||
If brainstorming artifacts exist:
|
||||
- Prioritize individual role analysis.md files
|
||||
- Use role analysis documents for integrated view
|
||||
- Reference guidance-specification.md for context
|
||||
|
||||
### Codebase Context
|
||||
- Identify similar patterns in existing code
|
||||
- Evaluate success/failure of current approaches
|
||||
- Ensure consistency with project architecture
|
||||
|
||||
## EXECUTION MODE
|
||||
|
||||
**Mode**: Analysis with write permission for output file
|
||||
**CLI Tool**: Gemini wrapper with --approval-mode yolo
|
||||
**Timeout**: 40-60 minutes based on complexity
|
||||
**Output**: Single file gemini-solution-design.md
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ context-package.json read and analyzed
|
||||
□ All 7 required sections present in output
|
||||
□ 2+ key design decisions with rationale and alternatives
|
||||
□ Code targets specified in correct format
|
||||
□ Feasibility scores provided (X/5)
|
||||
□ Final recommendation (PROCEED/RECONSIDER/REJECT)
|
||||
□ Output written to .workflow/active/{session_id}/.process/gemini-solution-design.md
|
||||
|
||||
Focus: Comprehensive solution design emphasizing architecture decisions and critical insights.
|
||||
@@ -0,0 +1,286 @@
|
||||
IMPL_PLAN.md Template - Implementation Plan Document Structure
|
||||
|
||||
## Document Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
identifier: WFS-{session-id}
|
||||
source: "User requirements" | "File: path" | "Issue: ISS-001"
|
||||
analysis: .workflow/active//{session-id}/.process/ANALYSIS_RESULTS.md
|
||||
artifacts: .workflow/active//{session-id}/.brainstorming/
|
||||
context_package: .workflow/active//{session-id}/.process/context-package.json # CCW smart context
|
||||
workflow_type: "standard | tdd | design" # Indicates execution model
|
||||
verification_history: # CCW quality gates
|
||||
concept_verify: "passed | skipped | pending"
|
||||
action_plan_verify: "pending"
|
||||
phase_progression: "brainstorm → context → analysis → concept_verify → planning" # CCW workflow phases
|
||||
---
|
||||
```
|
||||
|
||||
## Document Structure
|
||||
|
||||
# Implementation Plan: {Project Title}
|
||||
|
||||
## 1. Summary
|
||||
Core requirements, objectives, technical approach summary (2-3 paragraphs max).
|
||||
|
||||
**Core Objectives**:
|
||||
- [Key objective 1]
|
||||
- [Key objective 2]
|
||||
|
||||
**Technical Approach**:
|
||||
- [High-level approach]
|
||||
|
||||
## 2. Context Analysis
|
||||
|
||||
### CCW Workflow Context
|
||||
**Phase Progression**:
|
||||
- ✅ Phase 1: Brainstorming (role analyses generated)
|
||||
- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
|
||||
- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
|
||||
- ✅ Phase 4: Concept Verification ({X} clarifications answered, role analyses updated | skipped)
|
||||
- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)
|
||||
|
||||
**Quality Gates**:
|
||||
- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
|
||||
- plan-verify: ⏳ Pending (recommended before /workflow:execute)
|
||||
|
||||
**Context Package Summary**:
|
||||
- **Focus Paths**: {list key directories from context-package.json}
|
||||
- **Key Files**: {list primary files for modification}
|
||||
- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
|
||||
- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
|
||||
|
||||
### Project Profile
|
||||
- **Type**: Greenfield/Enhancement/Refactor
|
||||
- **Scale**: User count, data volume, complexity
|
||||
- **Tech Stack**: Primary technologies
|
||||
- **Timeline**: Duration and milestones
|
||||
|
||||
### Module Structure
|
||||
```
|
||||
[Directory tree showing key modules]
|
||||
```
|
||||
|
||||
### Dependencies
|
||||
**Primary**: [Core libraries and frameworks]
|
||||
**APIs**: [External services]
|
||||
**Development**: [Testing, linting, CI/CD tools]
|
||||
|
||||
### Patterns & Conventions
|
||||
- **Architecture**: [Key patterns like DI, Event-Driven]
|
||||
- **Component Design**: [Design patterns]
|
||||
- **State Management**: [State strategy]
|
||||
- **Code Style**: [Naming, TypeScript coverage]
|
||||
|
||||
## 3. Brainstorming Artifacts Reference
|
||||
|
||||
### Artifact Usage Strategy
|
||||
**Primary Reference (role analyses)**:
|
||||
- **What**: Role-specific analyses from brainstorming providing multi-perspective insights
|
||||
- **When**: Every task references relevant role analyses for requirements and design decisions
|
||||
- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents
|
||||
- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage
|
||||
- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning
|
||||
|
||||
**Context Intelligence (context-package.json)**:
|
||||
- **What**: Smart context gathered by CCW's context-gather phase
|
||||
- **Content**: Focus paths, dependency graph, existing patterns, module structure
|
||||
- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup
|
||||
- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
|
||||
|
||||
**Technical Analysis (ANALYSIS_RESULTS.md)**:
|
||||
- **What**: Gemini/Qwen/Codex parallel analysis results
|
||||
- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
|
||||
- **Usage**: Referenced in task planning for technical guidance and risk mitigation
|
||||
- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
|
||||
|
||||
### Integrated Specifications (Highest Priority)
|
||||
- **role analyses**: Comprehensive implementation blueprint
|
||||
- Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
|
||||
|
||||
### Supporting Artifacts (Reference)
|
||||
- **guidance-specification.md**: Role-specific discussion points and analysis framework
|
||||
- **system-architect/analysis.md**: Detailed architecture specifications
|
||||
- **ui-designer/analysis.md**: Layout and component specifications
|
||||
- **product-manager/analysis.md**: Product vision and user stories
|
||||
|
||||
**Artifact Priority in Development**:
|
||||
1. role analyses (primary reference for all tasks)
|
||||
2. context-package.json (smart context for execution environment)
|
||||
3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
|
||||
4. Role-specific analyses (fallback for detailed specifications)
|
||||
|
||||
## 4. Implementation Strategy
|
||||
|
||||
### Execution Strategy
|
||||
**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
|
||||
|
||||
**Rationale**: [Why this execution model fits the project]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [List independent workstreams]
|
||||
|
||||
**Serialization Requirements**:
|
||||
- [List critical dependencies]
|
||||
|
||||
### Architectural Approach
|
||||
**Key Architecture Decisions**:
|
||||
- [ADR references from role analyses]
|
||||
- [Justification for architecture patterns]
|
||||
|
||||
**Integration Strategy**:
|
||||
- [How modules communicate]
|
||||
- [State management approach]
|
||||
|
||||
### Key Dependencies
|
||||
**Task Dependency Graph**:
|
||||
```
|
||||
[High-level dependency visualization]
|
||||
```
|
||||
|
||||
**Critical Path**: [Identify bottleneck tasks]
|
||||
|
||||
### Testing Strategy
|
||||
**Testing Approach**:
|
||||
- Unit testing: [Tools, scope]
|
||||
- Integration testing: [Key integration points]
|
||||
- E2E testing: [Critical user flows]
|
||||
|
||||
**Coverage Targets**:
|
||||
- Lines: ≥70%
|
||||
- Functions: ≥70%
|
||||
- Branches: ≥65%
|
||||
|
||||
**Quality Gates**:
|
||||
- [CI/CD gates]
|
||||
- [Performance budgets]
|
||||
|
||||
## 5. Task Breakdown Summary
|
||||
|
||||
### Task Count
|
||||
**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
|
||||
|
||||
### Task Structure
|
||||
- **IMPL-1**: [Main task title]
|
||||
- **IMPL-2**: [Main task title]
|
||||
...
|
||||
|
||||
### Complexity Assessment
|
||||
- **High**: [List with rationale]
|
||||
- **Medium**: [List]
|
||||
- **Low**: [List]
|
||||
|
||||
### Dependencies
|
||||
[Reference Section 4.3 for dependency graph]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [Specific task groups that can run in parallel]
|
||||
|
||||
## 6. Implementation Plan (Detailed Phased Breakdown)
|
||||
|
||||
### Execution Strategy
|
||||
|
||||
**Phase 1 (Weeks 1-2): [Phase Name]**
|
||||
- **Tasks**: IMPL-1, IMPL-2
|
||||
- **Deliverables**:
|
||||
- [Specific deliverable 1]
|
||||
- [Specific deliverable 2]
|
||||
- **Success Criteria**:
|
||||
- [Measurable criterion]
|
||||
|
||||
**Phase 2 (Weeks 3-N): [Phase Name]**
|
||||
...
|
||||
|
||||
### Resource Requirements
|
||||
|
||||
**Development Team**:
|
||||
- [Team composition and skills]
|
||||
|
||||
**External Dependencies**:
|
||||
- [Third-party services, APIs]
|
||||
|
||||
**Infrastructure**:
|
||||
- [Development, staging, production environments]
|
||||
|
||||
## 7. Risk Assessment & Mitigation
|
||||
|
||||
| Risk | Impact | Probability | Mitigation Strategy | Owner |
|
||||
|------|--------|-------------|---------------------|-------|
|
||||
| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
|
||||
|
||||
**Critical Risks** (High impact + High probability):
|
||||
- [Risk 1]: [Detailed mitigation plan]
|
||||
|
||||
**Monitoring Strategy**:
|
||||
- [How risks will be monitored]
|
||||
|
||||
## 8. Success Criteria
|
||||
|
||||
**Functional Completeness**:
|
||||
- [ ] All requirements from role analyses implemented
|
||||
- [ ] All acceptance criteria from task.json files met
|
||||
|
||||
**Technical Quality**:
|
||||
- [ ] Test coverage ≥70%
|
||||
- [ ] Bundle size within budget
|
||||
- [ ] Performance targets met
|
||||
|
||||
**Operational Readiness**:
|
||||
- [ ] CI/CD pipeline operational
|
||||
- [ ] Monitoring and logging configured
|
||||
- [ ] Documentation complete
|
||||
|
||||
**Business Metrics**:
|
||||
- [ ] [Key business metrics from role analyses]
|
||||
|
||||
## Template Usage Guidelines
|
||||
|
||||
### When Generating IMPL_PLAN.md
|
||||
|
||||
1. **Fill Frontmatter Variables**:
|
||||
- Replace {session-id} with actual session ID
|
||||
- Set workflow_type based on planning phase
|
||||
- Update verification_history based on concept-verify results
|
||||
|
||||
2. **Populate CCW Workflow Context**:
|
||||
- Extract file/module counts from context-package.json
|
||||
- Document phase progression based on completed workflow steps
|
||||
- Update quality gate status (passed/skipped/pending)
|
||||
|
||||
3. **Extract from Analysis Results**:
|
||||
- Core objectives from ANALYSIS_RESULTS.md
|
||||
- Technical approach and architecture decisions
|
||||
- Risk assessment and mitigation strategies
|
||||
|
||||
4. **Reference Brainstorming Artifacts**:
|
||||
- List detected artifacts with correct paths
|
||||
- Document artifact priority and usage strategy
|
||||
- Map artifacts to specific tasks based on domain
|
||||
|
||||
5. **Define Implementation Strategy**:
|
||||
- Choose execution model (sequential/parallel/phased)
|
||||
- Identify parallelization opportunities
|
||||
- Document critical path and dependencies
|
||||
|
||||
6. **Break Down Tasks**:
|
||||
- List all task IDs and titles
|
||||
- Assess complexity (high/medium/low)
|
||||
- Create dependency graph visualization
|
||||
|
||||
7. **Set Success Criteria**:
|
||||
- Extract from role analyses
|
||||
- Include measurable metrics
|
||||
- Define quality gates
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
Before finalizing IMPL_PLAN.md:
|
||||
- [ ] All frontmatter fields populated correctly
|
||||
- [ ] CCW workflow context reflects actual phase progression
|
||||
- [ ] Brainstorming artifacts correctly referenced
|
||||
- [ ] Task breakdown matches generated task JSONs
|
||||
- [ ] Dependencies are acyclic and logical
|
||||
- [ ] Success criteria are measurable
|
||||
- [ ] Risk assessment includes mitigation strategies
|
||||
- [ ] All {placeholder} variables replaced with actual values
|
||||
@@ -0,0 +1,172 @@
|
||||
# SKILL.md Index Generation Context
|
||||
|
||||
## Description Field Requirements
|
||||
|
||||
When generating final aggregated output, remember to prepare data for SKILL.md description field:
|
||||
|
||||
**Required Data Points**:
|
||||
- Project root path (to be obtained via git command)
|
||||
- Use cases: "continuing development", "analyzing past implementations", "learning from workflow history"
|
||||
- Trigger phrase: "especially when no relevant context exists in memory"
|
||||
|
||||
**Description Format**:
|
||||
```
|
||||
Progressive workflow development history (located at {project_root}).
|
||||
Load this SKILL when continuing development, analyzing past implementations,
|
||||
or learning from workflow history, especially when no relevant context exists in memory.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
You are aggregating workflow session history to generate a progressive SKILL package.
|
||||
|
||||
## Your Task
|
||||
|
||||
Analyze archived workflow sessions and aggregate:
|
||||
1. **Lessons Learned** - Successes, challenges, and watch patterns
|
||||
2. **Conflict Patterns** - Recurring conflicts and resolutions
|
||||
3. **Implementation Summaries** - Key outcomes by functional domain
|
||||
|
||||
## Input Data
|
||||
|
||||
You will receive:
|
||||
- Session metadata (session_id, description, tags, metrics)
|
||||
- Lessons from each session (successes, challenges, watch_patterns)
|
||||
- IMPL_PLAN summaries
|
||||
- Context package metadata (keywords, tech_stack, complexity)
|
||||
|
||||
## Output Requirements
|
||||
|
||||
### 1. Aggregated Lessons
|
||||
|
||||
**Successes by Category**:
|
||||
- Group successful patterns by functional domain (auth, testing, performance, etc.)
|
||||
- Identify practices that succeeded across multiple sessions
|
||||
- Mark best practices (success in 3+ sessions)
|
||||
|
||||
**Challenges by Severity**:
|
||||
- HIGH: Blocked development for >4 hours OR repeated in 3+ sessions
|
||||
- MEDIUM: Required significant rework OR repeated in 2 sessions
|
||||
- LOW: Minor issues resolved quickly
|
||||
|
||||
**Watch Patterns**:
|
||||
- Identify patterns mentioned in 2+ sessions
|
||||
- Prioritize by frequency and severity
|
||||
- Mark CRITICAL patterns (appeared in 3+ sessions with HIGH severity)
|
||||
|
||||
**Format**:
|
||||
```json
|
||||
{
|
||||
"successes_by_category": {
|
||||
"auth": ["JWT implementation with refresh tokens (3 sessions)", ...],
|
||||
"testing": ["TDD reduced bugs by 60% (2 sessions)", ...]
|
||||
},
|
||||
"challenges_by_severity": {
|
||||
"high": [
|
||||
{
|
||||
"challenge": "Token refresh edge cases",
|
||||
"sessions": ["WFS-user-auth", "WFS-jwt-refresh"],
|
||||
"frequency": 2
|
||||
}
|
||||
],
|
||||
"medium": [...],
|
||||
"low": [...]
|
||||
},
|
||||
"watch_patterns": [
|
||||
{
|
||||
"pattern": "Token concurrency issues",
|
||||
"frequency": 3,
|
||||
"severity": "CRITICAL",
|
||||
"sessions": ["WFS-user-auth", "WFS-jwt-refresh", "WFS-oauth"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Conflict Patterns
|
||||
|
||||
**Analysis**:
|
||||
- Group conflicts by type (architecture, dependencies, testing, performance)
|
||||
- Identify recurring patterns (same conflict in different sessions)
|
||||
- Link successful resolutions to specific sessions
|
||||
|
||||
**Format**:
|
||||
```json
|
||||
{
|
||||
"architecture": [
|
||||
{
|
||||
"pattern": "Multiple authentication strategies conflict",
|
||||
"description": "Different auth methods (JWT, OAuth, session) cause integration issues",
|
||||
"sessions": ["WFS-user-auth", "WFS-oauth"],
|
||||
"resolution": "Unified auth interface with strategy pattern",
|
||||
"code_impact": ["src/auth/interface.ts", "src/auth/jwt.ts", "src/auth/oauth.ts"],
|
||||
"frequency": 2,
|
||||
"severity": "high"
|
||||
}
|
||||
],
|
||||
"dependencies": [...],
|
||||
"testing": [...],
|
||||
"performance": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Implementation Summary
|
||||
|
||||
**By Functional Domain**:
|
||||
- Group sessions by primary tag/domain
|
||||
- Summarize key accomplishments
|
||||
- Link to context packages and plans
|
||||
|
||||
**Format**:
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"session_count": 3,
|
||||
"sessions": [
|
||||
{
|
||||
"session_id": "WFS-user-auth",
|
||||
"description": "JWT authentication implementation",
|
||||
"key_outcomes": [
|
||||
"JWT token generation and validation",
|
||||
"Refresh token mechanism",
|
||||
"Secure password hashing with bcrypt"
|
||||
],
|
||||
"context_package": ".workflow/.archives/WFS-user-auth/.process/context-package.json",
|
||||
"metrics": {"task_count": 5, "success_rate": 100, "duration_hours": 4.5}
|
||||
}
|
||||
],
|
||||
"cumulative_metrics": {
|
||||
"total_tasks": 15,
|
||||
"avg_success_rate": 95,
|
||||
"total_hours": 12.5
|
||||
}
|
||||
},
|
||||
"payment": {...},
|
||||
"ui": {...}
|
||||
}
|
||||
```
|
||||
|
||||
## Analysis Guidelines
|
||||
|
||||
1. **Identify Patterns**: Look for recurring themes across sessions
|
||||
2. **Prioritize by Impact**: Focus on high-frequency, high-impact patterns
|
||||
3. **Link Sessions**: Connect related sessions (same domain, similar challenges)
|
||||
4. **Extract Wisdom**: Surface actionable insights from lessons learned
|
||||
5. **Maintain Context**: Keep references to original sessions and files
|
||||
|
||||
## Quality Criteria
|
||||
|
||||
- ✅ All sessions processed and categorized
|
||||
- ✅ Patterns identified and frequency counted
|
||||
- ✅ Severity levels assigned based on impact
|
||||
- ✅ Resolutions linked to specific sessions
|
||||
- ✅ Output is valid JSON with no missing fields
|
||||
- ✅ References (paths) are accurate and complete
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **NO hallucination**: Only aggregate data from provided sessions
|
||||
- **Preserve detail**: Keep specific session references for traceability
|
||||
- **Smart grouping**: Group similar patterns even if wording differs slightly
|
||||
- **Frequency matters**: Prioritize patterns that appear in multiple sessions
|
||||
- **Context preservation**: Keep context package paths for on-demand loading
|
||||
@@ -0,0 +1,94 @@
|
||||
Template for generating conflict-patterns.md
|
||||
|
||||
## Purpose
|
||||
Document recurring conflict patterns across workflow sessions with resolutions.
|
||||
|
||||
## File Location
|
||||
`.claude/skills/workflow-progress/conflict-patterns.md`
|
||||
|
||||
## Update Strategy
|
||||
- **Incremental mode**: Add new conflicts, update frequency counters for existing patterns
|
||||
- **Full mode**: Regenerate entire conflict analysis from all sessions
|
||||
|
||||
## Structure
|
||||
|
||||
```markdown
|
||||
# Workflow Conflict Patterns
|
||||
|
||||
## Architecture Conflicts
|
||||
|
||||
### {Conflict_Pattern_Title}
|
||||
**Pattern**: {concise_pattern_description}
|
||||
**Sessions**: {session_id_1}, {session_id_2}
|
||||
**Resolution**: {resolution_strategy}
|
||||
|
||||
**Code Impact**:
|
||||
- Modified: {file_path_1}, {file_path_2}
|
||||
- Added: {file_path_3}
|
||||
- Tests: {test_file_path}
|
||||
|
||||
**Frequency**: {count} sessions
|
||||
**Severity**: {high|medium|low}
|
||||
|
||||
---
|
||||
|
||||
## Dependency Conflicts
|
||||
|
||||
### {Conflict_Pattern_Title}
|
||||
**Pattern**: {concise_pattern_description}
|
||||
**Sessions**: {session_id_list}
|
||||
**Resolution**: {resolution_strategy}
|
||||
|
||||
**Package Changes**:
|
||||
- Updated: {package_name}@{version}
|
||||
- Locked: {dependency_name}
|
||||
|
||||
**Frequency**: {count} sessions
|
||||
**Severity**: {high|medium|low}
|
||||
|
||||
---
|
||||
|
||||
## Testing Conflicts
|
||||
|
||||
### {Conflict_Pattern_Title}
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Performance Conflicts
|
||||
|
||||
### {Conflict_Pattern_Title}
|
||||
...
|
||||
```
|
||||
|
||||
## Data Sources
|
||||
- IMPL_PLAN summaries: `.workflow/.archives/{session_id}/IMPL_PLAN.md`
|
||||
- Context packages: `.workflow/.archives/{session_id}/.process/context-package.json` (reference only)
|
||||
- Session lessons: `manifest.json` -> `archives[].lessons.challenges`
|
||||
|
||||
## Conflict Identification (Use CCW CLI)
|
||||
|
||||
**Command Pattern**:
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Identify conflict patterns from workflow sessions
|
||||
TASK: • Extract conflicts from IMPL_PLAN and lessons • Group by type (architecture/dependencies/testing/performance) • Identify recurring patterns (same conflict in different sessions) • Link resolutions to specific sessions
|
||||
MODE: analysis
|
||||
CONTEXT: @.workflow/.archives/*/IMPL_PLAN.md @.workflow/.archives/manifest.json
|
||||
EXPECTED: Conflict patterns with frequency and resolution
|
||||
CONSTRAINTS: analysis=READ-ONLY
|
||||
" --tool gemini --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
|
||||
```
|
||||
|
||||
**Pattern Grouping**:
|
||||
- **Architecture**: Design conflicts, incompatible strategies, interface mismatches
|
||||
- **Dependencies**: Version conflicts, library incompatibilities, package issues
|
||||
- **Testing**: Mock data inconsistencies, test environment issues, coverage gaps
|
||||
- **Performance**: Bottlenecks, optimization conflicts, resource issues
|
||||
|
||||
## Formatting Rules
|
||||
- Sort by frequency within each category
|
||||
- Include code impact for traceability
|
||||
- Mark high-frequency patterns (3+ sessions) as "RECURRING"
|
||||
- Keep resolution descriptions actionable
|
||||
- Use relative paths for file references
|
||||
224
.ccw/workflows/cli-templates/prompts/workflow-skill-index.txt
Normal file
224
.ccw/workflows/cli-templates/prompts/workflow-skill-index.txt
Normal file
@@ -0,0 +1,224 @@
|
||||
Template for generating SKILL.md (index file)
|
||||
|
||||
## Purpose
|
||||
Create main SKILL package index with progressive loading structure and session references.
|
||||
|
||||
## File Location
|
||||
`.claude/skills/workflow-progress/SKILL.md`
|
||||
|
||||
## Update Strategy
|
||||
- **Always regenerated**: This file is always updated with latest session count, domains, dates
|
||||
|
||||
## Structure
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: workflow-progress
|
||||
description: Progressive workflow development history (located at {project_root}). Load this SKILL when continuing development, analyzing past implementations, or learning from workflow history, especially when no relevant context exists in memory.
|
||||
version: {semantic_version}
|
||||
---
|
||||
# Workflow Progress SKILL Package
|
||||
|
||||
## Documentation: `../../../.workflow/.archives/`
|
||||
|
||||
**Total Sessions**: {session_count}
|
||||
**Functional Domains**: {domain_list}
|
||||
**Date Range**: {earliest_date} - {latest_date}
|
||||
|
||||
## Progressive Loading
|
||||
|
||||
### Level 0: Quick Overview (~2K tokens)
|
||||
- [Sessions Timeline](sessions-timeline.md#recent-sessions-last-5) - Recent 5 sessions
|
||||
- [Top Conflict Patterns](conflict-patterns.md#top-patterns) - Top 3 recurring conflicts
|
||||
- Quick reference for last completed work
|
||||
|
||||
**Use Case**: Quick context refresh before starting new task
|
||||
|
||||
### Level 1: Core History (~8K tokens)
|
||||
- [Sessions Timeline](sessions-timeline.md) - Recent 10 sessions with details
|
||||
- [Lessons Learned](lessons-learned.md#best-practices) - Success patterns by category
|
||||
- [Conflict Patterns](conflict-patterns.md) - Known conflict types and resolutions
|
||||
- Context package references (metadata only)
|
||||
|
||||
**Use Case**: Understanding recent development patterns and avoiding known pitfalls
|
||||
|
||||
### Level 2: Complete History (~25K tokens)
|
||||
- All archived sessions with metadata
|
||||
- Full lessons learned (successes, challenges, watch patterns)
|
||||
- Complete conflict analysis with resolutions
|
||||
- IMPL_PLAN summaries from all sessions
|
||||
- Context package paths for on-demand loading
|
||||
|
||||
**Use Case**: Comprehensive review before major refactoring or architecture changes
|
||||
|
||||
### Level 3: Deep Dive (~40K tokens)
|
||||
- Full IMPL_PLAN.md and TODO_LIST.md from all sessions
|
||||
- Detailed task completion summaries
|
||||
- Cross-session dependency analysis
|
||||
- Direct context package file references
|
||||
|
||||
**Use Case**: Investigating specific implementation details or debugging historical decisions
|
||||
|
||||
---
|
||||
|
||||
## Quick Access
|
||||
|
||||
### Recent Sessions
|
||||
{list of 5 most recent sessions with one-line descriptions}
|
||||
|
||||
### By Domain
|
||||
- **{Domain_1}**: {count} sessions
|
||||
- **{Domain_2}**: {count} sessions
|
||||
- **{Domain_3}**: {count} sessions
|
||||
|
||||
### Top Watch Patterns
|
||||
1. {most_frequent_watch_pattern}
|
||||
2. {second_most_frequent}
|
||||
3. {third_most_frequent}
|
||||
|
||||
---
|
||||
|
||||
## Session Index
|
||||
|
||||
### {Domain_Category} Sessions
|
||||
- [{session_id}](../../../.workflow/.archives/{session_id}/) - {one_line_description} ({date})
|
||||
- Context: [context-package.json](../../../.workflow/.archives/{session_id}/.process/context-package.json)
|
||||
- Plan: [IMPL_PLAN.md](../../../.workflow/.archives/{session_id}/IMPL_PLAN.md)
|
||||
- Tags: {tag1}, {tag2}, {tag3}
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Loading Quick Context
|
||||
```markdown
|
||||
Load Level 0 from workflow-progress SKILL for overview of recent work
|
||||
```
|
||||
|
||||
### Investigating {Domain} History
|
||||
```markdown
|
||||
Load Level 2 from workflow-progress SKILL, filter by "{domain}" tag
|
||||
```
|
||||
|
||||
### Full Historical Analysis
|
||||
```markdown
|
||||
Load Level 3 from workflow-progress SKILL for complete development history
|
||||
```
|
||||
```
|
||||
|
||||
## Data Sources
|
||||
- Manifest: `.workflow/.archives/manifest.json`
|
||||
- All session metadata from manifest entries
|
||||
|
||||
## Generation Rules
|
||||
- Version format: `{major}.{minor}.{patch}` (increment patch for each update)
|
||||
- Domain list: Extract unique tags from all sessions, sort by frequency
|
||||
- Date range: Find earliest and latest archived_at timestamps
|
||||
- Token estimates: Approximate based on content length
|
||||
- Use relative paths (../../../.workflow/.archives/) for session references
|
||||
|
||||
## Formatting Rules
|
||||
- Keep descriptions concise
|
||||
- Sort sessions by date (newest first)
|
||||
- Group sessions by primary tag
|
||||
- Include only top 5 recent sessions in Quick Access
|
||||
- Include top 3 watch patterns
|
||||
|
||||
---
|
||||
|
||||
## Variable Substitution Guide
|
||||
|
||||
### Required Variables
|
||||
- `{project_root}`: Absolute project path from git root (e.g., "/d/Claude_dms3")
|
||||
- `{semantic_version}`: Version string (e.g., "1.0.0", increment patch for each update)
|
||||
- `{session_count}`: Total number of archived sessions
|
||||
- `{domain_list}`: Comma-separated unique tags sorted by frequency
|
||||
- `{earliest_date}`: Earliest session archived_at timestamp
|
||||
- `{latest_date}`: Most recent session archived_at timestamp
|
||||
|
||||
### Generated Variables
|
||||
- `{one_line_description}`: Extract from session description (first sentence, max 80 chars)
|
||||
- `{domain_category}`: Primary tag from session metadata
|
||||
- `{most_frequent_watch_pattern}`: Top recurring watch pattern across sessions
|
||||
- `{date}`: Session archived_at in YYYY-MM-DD format
|
||||
|
||||
### Description Field Generation
|
||||
|
||||
**Format Template**:
|
||||
```
|
||||
Progressive workflow development history (located at {project_root}).
|
||||
Load this SKILL when continuing development, analyzing past implementations,
|
||||
or learning from workflow history, especially when no relevant context exists in memory.
|
||||
```
|
||||
|
||||
**Generation Rules**:
|
||||
1. **Project Root**: Use `git rev-parse --show-toplevel` to get absolute path
|
||||
2. **Use Cases**: ALWAYS include these trigger phrases:
|
||||
- "continuing development" (开发延续)
|
||||
- "analyzing past implementations" (分析历史)
|
||||
- "learning from workflow history" (学习历史)
|
||||
3. **Trigger Optimization**: MUST include "especially when no relevant context exists in memory"
|
||||
4. **Path Format**: Use forward slashes for cross-platform compatibility (e.g., "/d/project")
|
||||
|
||||
**Why This Matters**:
|
||||
- **Auto-loading precision**: Path reference ensures Claude loads correct project's SKILL
|
||||
- **Context awareness**: "when no relevant context exists" prevents redundant loading
|
||||
- **Action coverage**: Three use cases cover all workflow scenarios
|
||||
|
||||
---
|
||||
|
||||
## Generation Instructions
|
||||
|
||||
### Step 1: Get Project Root
|
||||
```bash
|
||||
git rev-parse --show-toplevel # Returns: /d/Claude_dms3
|
||||
```
|
||||
|
||||
### Step 2: Read Manifest
|
||||
```bash
|
||||
cat .workflow/.archives/manifest.json
|
||||
```
|
||||
|
||||
Extract:
|
||||
- Total session count
|
||||
- All session tags (for domain list)
|
||||
- Date range (earliest/latest archived_at)
|
||||
|
||||
### Step 3: Aggregate Session Data
|
||||
- Count sessions per domain
|
||||
- Extract top 5 recent sessions
|
||||
- Identify top 3 watch patterns from lessons
|
||||
|
||||
### Step 4: Generate Description
|
||||
Apply format template with project_root from Step 1.
|
||||
|
||||
### Step 5: Calculate Version
|
||||
- Read existing SKILL.md version (if exists)
|
||||
- Increment patch version (e.g., 1.0.5 → 1.0.6)
|
||||
- Use 1.0.0 for new SKILL package
|
||||
|
||||
### Step 6: Build Progressive Loading Sections
|
||||
- Level 0: Recent 5 sessions + Top 3 conflicts
|
||||
- Level 1: Recent 10 sessions + Best practices
|
||||
- Level 2: All sessions + Full lessons + Full conflicts
|
||||
- Level 3: Include IMPL_PLAN and TODO_LIST references
|
||||
|
||||
### Step 7: Write SKILL.md
|
||||
- Apply all variable substitutions
|
||||
- Use relative paths: `../../../.workflow/.archives/`
|
||||
- Validate all referenced files exist
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] `{project_root}` uses absolute path with forward slashes
|
||||
- [ ] Description includes all three use cases
|
||||
- [ ] Description includes trigger optimization phrase
|
||||
- [ ] Version incremented correctly
|
||||
- [ ] All session references use relative paths
|
||||
- [ ] Domain list sorted by frequency
|
||||
- [ ] Date range matches manifest
|
||||
- [ ] Quick Access section has exactly 5 recent sessions
|
||||
- [ ] Top Watch Patterns section has exactly 3 items
|
||||
- [ ] All referenced files exist in archives
|
||||
@@ -0,0 +1,94 @@
|
||||
Template for generating lessons-learned.md
|
||||
|
||||
## Purpose
|
||||
Aggregate lessons learned from workflow sessions, categorized by functional domain and severity.
|
||||
|
||||
## File Location
|
||||
`.claude/skills/workflow-progress/lessons-learned.md`
|
||||
|
||||
## Update Strategy
|
||||
- **Incremental mode**: Merge new session lessons into existing categories, update frequencies
|
||||
- **Full mode**: Regenerate entire lessons document from all sessions
|
||||
|
||||
## Structure
|
||||
|
||||
```markdown
|
||||
# Workflow Lessons Learned
|
||||
|
||||
## Best Practices (Successes)
|
||||
|
||||
### {Domain_Category}
|
||||
- {success_pattern_1} (sessions: {session_id_1}, {session_id_2})
|
||||
- {success_pattern_2} (sessions: {session_id_3})
|
||||
|
||||
### {Domain_Category_2}
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Known Challenges
|
||||
|
||||
### High Priority
|
||||
- **{challenge_title}**: {description}
|
||||
- Affected sessions: {session_id_1}, {session_id_2}
|
||||
- Resolution: {resolution_strategy}
|
||||
|
||||
### Medium Priority
|
||||
- **{challenge_title}**: {description}
|
||||
- Affected sessions: {session_id_3}
|
||||
- Resolution: {resolution_strategy}
|
||||
|
||||
### Low Priority
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Watch Patterns
|
||||
|
||||
### Critical (3+ sessions)
|
||||
1. **{pattern_name}**: {description}
|
||||
- Frequency: {count} sessions
|
||||
- Affected: {session_list}
|
||||
- Mitigation: {mitigation_strategy}
|
||||
|
||||
### High Priority (2 sessions)
|
||||
...
|
||||
|
||||
### Normal (1 session)
|
||||
...
|
||||
```
|
||||
|
||||
## Data Sources
|
||||
- Lessons: `manifest.json` -> `archives[].lessons.{successes|challenges|watch_patterns}`
|
||||
- Session metadata: `.workflow/.archives/{session_id}/workflow-session.json`
|
||||
|
||||
## Aggregation Rules (Use CCW CLI)
|
||||
|
||||
**Command Pattern**:
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Aggregate workflow lessons from session data
|
||||
TASK: • Group successes by functional domain • Categorize challenges by severity (HIGH/MEDIUM/LOW) • Identify watch patterns with frequency >= 2 • Mark CRITICAL patterns (3+ sessions)
|
||||
MODE: analysis
|
||||
CONTEXT: @.workflow/.archives/manifest.json
|
||||
EXPECTED: Aggregated lessons with frequency counts
|
||||
CONSTRAINTS: analysis=READ-ONLY
|
||||
" --tool gemini --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
|
||||
```
|
||||
|
||||
**Severity Classification**:
|
||||
- **HIGH**: Blocked development >4 hours OR repeated in 3+ sessions
|
||||
- **MEDIUM**: Required significant rework OR repeated in 2 sessions
|
||||
- **LOW**: Minor issues resolved quickly
|
||||
|
||||
**Pattern Identification**:
|
||||
- Successes in 3+ sessions → "Best Practices"
|
||||
- Challenges repeated 2+ times → "Known Issues"
|
||||
- Watch patterns frequency >= 2 → "High Priority Warnings"
|
||||
- Watch patterns frequency >= 3 → "CRITICAL"
|
||||
|
||||
## Formatting Rules
|
||||
- Sort by frequency (most common first)
|
||||
- Include session references for traceability
|
||||
- Use bold for challenge titles
|
||||
- Keep descriptions concise but actionable
|
||||
@@ -0,0 +1,53 @@
|
||||
Template for generating sessions-timeline.md
|
||||
|
||||
## Purpose
|
||||
Create or update chronological timeline of workflow sessions with functional domain grouping.
|
||||
|
||||
## File Location
|
||||
`.claude/skills/workflow-progress/sessions-timeline.md`
|
||||
|
||||
## Update Strategy
|
||||
- **Incremental mode**: Append new session to timeline, keep existing content
|
||||
- **Full mode**: Regenerate entire timeline from all sessions
|
||||
|
||||
## Structure
|
||||
|
||||
```markdown
|
||||
# Workflow Sessions Timeline
|
||||
|
||||
## Recent Sessions (Last 5)
|
||||
|
||||
### {session_id} ({archived_date})
|
||||
**Description**: {description}
|
||||
**Tags**: {tag1}, {tag2}, {tag3}
|
||||
**Metrics**: {task_count} tasks, {success_rate}% success, {duration_hours} hours
|
||||
**Context Package**: [{session_id}/context-package.json](../../../.workflow/.archives/{session_id}/.process/context-package.json)
|
||||
|
||||
**Key Outcomes**:
|
||||
- ✅ {success_item_1}
|
||||
- ✅ {success_item_2}
|
||||
- ⚠️ Watch: {watch_pattern}
|
||||
|
||||
---
|
||||
|
||||
## By Functional Domain
|
||||
|
||||
### {Domain_Name} ({count} sessions)
|
||||
- {session_id_1} ({date}) - {one_line_description}
|
||||
- {session_id_2} ({date}) - {one_line_description}
|
||||
|
||||
### {Domain_Name_2} ({count} sessions)
|
||||
...
|
||||
```
|
||||
|
||||
## Data Sources
|
||||
- Session metadata: `.workflow/.archives/{session_id}/workflow-session.json`
|
||||
- Manifest entry: `.workflow/.archives/manifest.json`
|
||||
- Lessons: `manifest.json` -> `archives[].lessons`
|
||||
|
||||
## Formatting Rules
|
||||
- Sort recent sessions by archived_at (newest first)
|
||||
- Group by functional domain using tags
|
||||
- Use relative paths for context package links
|
||||
- Use ✅ for successes, ⚠️ for watch patterns
|
||||
- Keep descriptions concise (one line)
|
||||
@@ -0,0 +1,123 @@
|
||||
Task JSON Schema - Agent Mode (No Command Field)
|
||||
|
||||
## Schema Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N[.M]",
|
||||
"title": "Descriptive task name",
|
||||
"status": "pending",
|
||||
"context_package_path": "{context_package_path}",
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test|docs",
|
||||
"agent": "@code-developer|@test-fix-agent|@universal-executor"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["extracted from analysis"],
|
||||
"focus_paths": ["src/paths"],
|
||||
"acceptance": ["measurable criteria"],
|
||||
"depends_on": ["IMPL-N"],
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "synthesis_specification",
|
||||
"path": "{synthesis_spec_path}",
|
||||
"priority": "highest",
|
||||
"usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
|
||||
},
|
||||
{
|
||||
"type": "role_analysis",
|
||||
"path": "{role_analysis_path}",
|
||||
"priority": "high",
|
||||
"usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)"
|
||||
}
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_role_analyses_specification",
|
||||
"action": "Load consolidated role analyses",
|
||||
"commands": [
|
||||
"Read({synthesis_spec_path})"
|
||||
],
|
||||
"output_to": "synthesis_specification",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_context_package",
|
||||
"action": "Load context package for project structure",
|
||||
"commands": [
|
||||
"Read({context_package_path})"
|
||||
],
|
||||
"output_to": "context_pkg",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "local_codebase_exploration",
|
||||
"action": "Explore codebase using local search",
|
||||
"commands": [
|
||||
"bash(rg '^(function|class|interface).*{keyword}' --type ts -n --max-count 15)",
|
||||
"bash(find . -name '*{keyword}*' -type f | grep -v node_modules | head -10)"
|
||||
],
|
||||
"output_to": "codebase_structure",
|
||||
"on_error": "skip_optional"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement task following role analyses",
|
||||
"description": "Implement '{title}' following [synthesis_specification] requirements and [context_pkg] patterns. Use role analyses as primary source, consult artifacts for technical details.",
|
||||
"modification_points": [
|
||||
"Apply consolidated requirements from role analyses",
|
||||
"Follow technical guidelines from synthesis",
|
||||
"Consult artifacts for implementation details when needed",
|
||||
"Integrate with existing patterns"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Load role analyses and context package",
|
||||
"Analyze existing patterns from [codebase_structure]",
|
||||
"Implement following specification",
|
||||
"Consult artifacts for technical details when needed",
|
||||
"Validate against acceptance criteria"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Features - Agent Mode
|
||||
|
||||
**Execution Model**: Agent interprets `modification_points` and `logic_flow` to execute autonomously
|
||||
|
||||
**No Command Field**: Steps in `implementation_approach` do NOT include `command` field
|
||||
|
||||
**Context Loading**: Context loaded via `pre_analysis` steps, available as variables (e.g., [synthesis_specification], [context_pkg])
|
||||
|
||||
**Agent Execution**:
|
||||
- Agent reads modification_points and logic_flow
|
||||
- Agent performs implementation autonomously
|
||||
- Agent validates against acceptance criteria
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
**implementation_approach**: Array of step objects (NO command field)
|
||||
- **step**: Sequential step number
|
||||
- **title**: Step description
|
||||
- **description**: Detailed instructions with variable references
|
||||
- **modification_points**: Specific code modifications to apply
|
||||
- **logic_flow**: Business logic execution sequence
|
||||
- **depends_on**: Step dependencies (empty array for independent steps)
|
||||
- **output**: Expected deliverable variable name
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
1. **Load Context**: Use pre_analysis to load synthesis, context package, and explore codebase
|
||||
2. **Reference Variables**: Use [variable_name] to reference outputs from pre_analysis steps
|
||||
3. **Clear Instructions**: Provide detailed modification_points and logic_flow for agent
|
||||
4. **No Commands**: Never add command field to implementation_approach steps
|
||||
5. **Agent Autonomy**: Let agent interpret and execute based on provided instructions
|
||||
@@ -0,0 +1,182 @@
|
||||
Task JSON Schema - CLI Execute Mode (With Command Field)
|
||||
|
||||
## Schema Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N[.M]",
|
||||
"title": "Descriptive task name",
|
||||
"status": "pending",
|
||||
"context_package_path": "{context_package_path}",
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test|docs",
|
||||
"agent": "@code-developer|@test-fix-agent|@universal-executor"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["extracted from analysis"],
|
||||
"focus_paths": ["src/paths"],
|
||||
"acceptance": ["measurable criteria"],
|
||||
"depends_on": ["IMPL-N"],
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "synthesis_specification",
|
||||
"path": "{synthesis_spec_path}",
|
||||
"priority": "highest",
|
||||
"usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
|
||||
},
|
||||
{
|
||||
"type": "role_analysis",
|
||||
"path": "{role_analysis_path}",
|
||||
"priority": "high",
|
||||
"usage": "Technical/design/business details from specific roles"
|
||||
}
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_synthesis_specification",
|
||||
"action": "Load consolidated synthesis specification",
|
||||
"commands": [
|
||||
"Read({synthesis_spec_path})"
|
||||
],
|
||||
"output_to": "synthesis_specification",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_context_package",
|
||||
"action": "Load context package",
|
||||
"commands": [
|
||||
"Read({context_package_path})"
|
||||
],
|
||||
"output_to": "context_pkg",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "local_codebase_exploration",
|
||||
"action": "Explore codebase using local search",
|
||||
"commands": [
|
||||
"bash(rg '^(function|class|interface).*{keyword}' --type ts -n --max-count 15)",
|
||||
"bash(find . -name '*{keyword}*' -type f | grep -v node_modules | head -10)"
|
||||
],
|
||||
"output_to": "codebase_structure",
|
||||
"on_error": "skip_optional"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement task with Codex",
|
||||
"description": "Implement '{title}' using Codex CLI tool",
|
||||
"command": "bash(codex -C {focus_path} --full-auto exec \"PURPOSE: {purpose} TASK: {task_description} MODE: auto CONTEXT: @{{synthesis_spec_path}} @{{context_package_path}} EXPECTED: {expected_output} RULES: Follow synthesis specification\" --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": [
|
||||
"Create/modify implementation files",
|
||||
"Follow synthesis specification requirements",
|
||||
"Integrate with existing patterns"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Codex loads context package and synthesis",
|
||||
"Codex implements according to specification",
|
||||
"Codex validates against acceptance criteria"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Multi-Step Example (Complex Task with Resume)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Implement RBAC system",
|
||||
"flow_control": {
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Create RBAC models",
|
||||
"description": "Create role and permission data models",
|
||||
"command": "bash(codex -C src/models --full-auto exec \"PURPOSE: Create RBAC models TASK: Define role and permission models MODE: auto CONTEXT: @{{synthesis_spec_path}} @{{context_package_path}} EXPECTED: Models with migrations RULES: Follow synthesis spec\" --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Define role model", "Define permission model"],
|
||||
"logic_flow": ["Design schema", "Implement models", "Generate migrations"],
|
||||
"depends_on": [],
|
||||
"output": "rbac_models"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Implement RBAC middleware",
|
||||
"description": "Create route protection middleware",
|
||||
"command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Create permission checker", "Add route decorators"],
|
||||
"logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
|
||||
"depends_on": [1],
|
||||
"output": "rbac_middleware"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Features - CLI Execute Mode
|
||||
|
||||
**Execution Model**: Commands in `command` field execute steps directly
|
||||
|
||||
**Command Field Required**: Every step in `implementation_approach` MUST include `command` field
|
||||
|
||||
**Context Delivery**: Context provided via CONTEXT field in command prompt using `@{path}` syntax
|
||||
|
||||
**Multi-Step Support**:
|
||||
- First step: Full context with `-C directory` and complete CONTEXT field
|
||||
- Subsequent steps: Use `resume --last` to maintain session continuity
|
||||
- Step dependencies: Use `depends_on` array to specify step order
|
||||
|
||||
## Command Templates
|
||||
|
||||
### Single-Step Codex Command
|
||||
```bash
|
||||
bash(codex -C {focus_path} --full-auto exec "PURPOSE: {purpose} TASK: {task} MODE: auto CONTEXT: @{{synthesis_spec_path}} @{{context_package_path}} EXPECTED: {expected} RULES: {rules}" --skip-git-repo-check -s danger-full-access)
|
||||
```
|
||||
|
||||
### Multi-Step Codex with Resume
|
||||
```bash
|
||||
# First step
|
||||
bash(codex -C {path} --full-auto exec "..." --skip-git-repo-check -s danger-full-access)
|
||||
|
||||
# Subsequent steps
|
||||
bash(codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access)
|
||||
```
|
||||
|
||||
### Gemini/Qwen Commands (Analysis/Documentation)
|
||||
```bash
|
||||
bash(gemini "PURPOSE: {purpose} TASK: {task} MODE: analysis CONTEXT: @{synthesis_spec_path} EXPECTED: {expected} RULES: {rules}")
|
||||
|
||||
# With write permission
|
||||
bash(gemini --approval-mode yolo "PURPOSE: {purpose} TASK: {task} MODE: write CONTEXT: @{context} EXPECTED: {expected} RULES: {rules}")
|
||||
```
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
**implementation_approach**: Array of step objects (WITH command field)
|
||||
- **step**: Sequential step number
|
||||
- **title**: Step description
|
||||
- **description**: Brief step description
|
||||
- **command**: Complete CLI command to execute the step
|
||||
- **modification_points**: Specific code modifications (for reference)
|
||||
- **logic_flow**: Execution sequence (for reference)
|
||||
- **depends_on**: Step dependencies (array of step numbers, empty for independent)
|
||||
- **output**: Expected deliverable variable name
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
1. **Always Include Command**: Every step MUST have a `command` field
|
||||
2. **Context via CONTEXT Field**: Provide context using `@{path}` syntax in command prompt
|
||||
3. **First Step Full Context**: First step should include `-C directory` and full context package
|
||||
4. **Resume for Continuity**: Use `resume --last` for subsequent steps in same task
|
||||
5. **Step Dependencies**: Use `depends_on: [1, 2]` to specify execution order
|
||||
6. **Parameter Position**:
|
||||
- Codex: `--skip-git-repo-check -s danger-full-access` at END
|
||||
- Gemini/Qwen: `--approval-mode yolo` BEFORE the prompt
|
||||
119
.ccw/workflows/cli-templates/protocols/analysis-protocol.md
Normal file
119
.ccw/workflows/cli-templates/protocols/analysis-protocol.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Analysis Mode Protocol
|
||||
|
||||
## Mode Definition
|
||||
**Mode**: `analysis` (READ-ONLY)
|
||||
## Prompt Structure
|
||||
|
||||
```
|
||||
PURPOSE: [development goal]
|
||||
TASK: [specific implementation task]
|
||||
MODE: [auto|write]
|
||||
CONTEXT: [file patterns]
|
||||
EXPECTED: [deliverables]
|
||||
RULES: [templates | additional constraints]
|
||||
```
|
||||
## Operation Boundaries
|
||||
|
||||
### ALLOWED Operations
|
||||
- **READ**: All CONTEXT files and analyze content
|
||||
- **ANALYZE**: Code patterns, architecture, dependencies
|
||||
- **GENERATE**: Text output, insights, recommendations
|
||||
- **DOCUMENT**: Analysis results in output response only
|
||||
|
||||
### FORBIDDEN Operations
|
||||
- **NO FILE CREATION**: Cannot create any files on disk
|
||||
- **NO FILE MODIFICATION**: Cannot modify existing files
|
||||
- **NO FILE DELETION**: Cannot delete any files
|
||||
- **NO DIRECTORY OPERATIONS**: Cannot create/modify directories
|
||||
|
||||
**CRITICAL**: Absolutely NO file system operations - OUTPUT ONLY
|
||||
|
||||
## Execution Flow
|
||||
|
||||
1. **Parse** all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
|
||||
2. **Read** and analyze CONTEXT files thoroughly
|
||||
3. **Identify** patterns, issues, and dependencies
|
||||
4. **Generate** insights and recommendations
|
||||
5. **Validate** EXPECTED deliverables met
|
||||
6. **Output** structured analysis (text response only)
|
||||
|
||||
## Core Requirements
|
||||
|
||||
**ALWAYS**:
|
||||
- Analyze ALL CONTEXT files completely
|
||||
- Apply RULES (templates + constraints) exactly
|
||||
- Provide code evidence with `file:line` references
|
||||
- List all related/analyzed files at output beginning
|
||||
- Match EXPECTED deliverables precisely
|
||||
|
||||
**NEVER**:
|
||||
- Assume behavior without code verification
|
||||
- Ignore CONTEXT file patterns
|
||||
- Skip RULES or templates
|
||||
- Make unsubstantiated claims
|
||||
- Create/modify/delete any files
|
||||
|
||||
## RULES Processing
|
||||
|
||||
- Parse RULES field to extract template content and constraints
|
||||
- Recognize `|` as separator: `template content | additional constraints`
|
||||
- Apply ALL template guidelines as mandatory
|
||||
- Treat rule violations as task failures
|
||||
|
||||
## Error Handling
|
||||
|
||||
**File Not Found**: Report missing files, continue with available, note in output
|
||||
**Invalid CONTEXT Pattern**: Report invalid pattern, request correction, do not guess
|
||||
|
||||
## Quality Standards
|
||||
|
||||
- **Thoroughness**: Analyze ALL files, check cross-file patterns, quantify metrics
|
||||
- **Evidence-Based**: Quote code with `file:line`, link patterns, support claims with examples
|
||||
- **Actionable**: Clear recommendations, prioritized by impact, incremental changes
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Format Priority
|
||||
|
||||
**If template defines output format** → Follow template format EXACTLY
|
||||
|
||||
**If template has no format** → Use default format below
|
||||
|
||||
### Default Analysis Output
|
||||
|
||||
```markdown
|
||||
# Analysis: [TASK Title]
|
||||
|
||||
## Related Files
|
||||
- `path/to/file1.ext` - [Brief description of relevance]
|
||||
- `path/to/file2.ext` - [Brief description of relevance]
|
||||
|
||||
## Summary
|
||||
[2-3 sentence overview]
|
||||
|
||||
## Key Findings
|
||||
1. [Finding] - path/to/file:123
|
||||
2. [Finding] - path/to/file:456
|
||||
|
||||
## Detailed Analysis
|
||||
[Evidence-based analysis with code quotes]
|
||||
|
||||
## Recommendations
|
||||
1. [Actionable recommendation]
|
||||
2. [Actionable recommendation]
|
||||
```
|
||||
|
||||
### Code References
|
||||
|
||||
**Format**: `path/to/file:line_number`
|
||||
**Example**: `src/auth/jwt.ts:45` - Authentication uses deprecated algorithm
|
||||
|
||||
### Quality Checklist
|
||||
|
||||
- [ ] All CONTEXT files analyzed
|
||||
- [ ] Code evidence with `file:line` references
|
||||
- [ ] Specific, actionable recommendations
|
||||
- [ ] No unsubstantiated claims
|
||||
- [ ] EXPECTED deliverables met
|
||||
136
.ccw/workflows/cli-templates/protocols/write-protocol.md
Normal file
136
.ccw/workflows/cli-templates/protocols/write-protocol.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Write Mode Protocol
|
||||
## Prompt Structure
|
||||
|
||||
```
|
||||
PURPOSE: [development goal]
|
||||
TASK: [specific implementation task]
|
||||
MODE: [auto|write]
|
||||
CONTEXT: [file patterns]
|
||||
EXPECTED: [deliverables]
|
||||
RULES: [templates | additional constraints]
|
||||
```
|
||||
## Operation Boundaries
|
||||
|
||||
### MODE: write
|
||||
- **READ**: All CONTEXT files and analyze content
|
||||
- **CREATE**: New files (documentation, code, configuration)
|
||||
- **MODIFY**: Existing files (update content, refactor code)
|
||||
- **DELETE**: Files when explicitly required
|
||||
|
||||
**Restrictions**: Follow project conventions, cannot break existing functionality
|
||||
|
||||
**Constraint**: Must test every change
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### MODE: write
|
||||
1. **Parse** all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
|
||||
2. **Read** CONTEXT files, find 3+ similar patterns
|
||||
3. **Plan** implementation following RULES
|
||||
4. **Execute** requested file operations
|
||||
5. **Validate** changes
|
||||
6. **Report** file changes
|
||||
|
||||
## Core Requirements
|
||||
|
||||
**ALWAYS**:
|
||||
- Study CONTEXT files - find 3+ similar patterns before implementing
|
||||
- Apply RULES exactly
|
||||
- Test continuously (auto mode)
|
||||
- Commit incrementally (auto mode)
|
||||
- Match project style exactly
|
||||
- List all created/modified files at output beginning
|
||||
|
||||
**NEVER**:
|
||||
- Make assumptions without code verification
|
||||
- Ignore existing patterns
|
||||
- Skip tests (auto mode)
|
||||
- Use clever tricks over boring solutions
|
||||
- Break backward compatibility
|
||||
- Exceed 3 failed attempts without stopping
|
||||
|
||||
|
||||
**Three-Attempt Rule**: On 3rd failure, stop and report what attempted, what failed, root cause
|
||||
|
||||
| Error Type | Response |
|
||||
|------------|----------|
|
||||
| Syntax/Type | Review → Fix → Re-run tests |
|
||||
| Runtime | Analyze stack → Add handling → Test |
|
||||
| Test Failure | Debug → Review setup → Fix |
|
||||
| Build Failure | Check messages → Fix incrementally |
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Format Priority
|
||||
|
||||
**If template defines output format** → Follow template format EXACTLY
|
||||
|
||||
**If template has no format** → Use default format below
|
||||
|
||||
### Task Implementation
|
||||
|
||||
```markdown
|
||||
# Implementation: [TASK Title]
|
||||
|
||||
## Changes
|
||||
- Created: `path/to/file1.ext` (X lines)
|
||||
- Modified: `path/to/file2.ext` (+Y/-Z lines)
|
||||
- Deleted: `path/to/file3.ext`
|
||||
|
||||
## Summary
|
||||
[2-3 sentence overview]
|
||||
|
||||
## Key Decisions
|
||||
1. [Decision] - Rationale and reference to similar pattern
|
||||
2. [Decision] - path/to/reference:line
|
||||
|
||||
## Implementation Details
|
||||
[Evidence-based description with code references]
|
||||
|
||||
## Testing
|
||||
- Tests written: X new tests
|
||||
- Tests passing: Y/Z tests
|
||||
|
||||
## Validation
|
||||
✅ Tests: X passing
|
||||
✅ Build: Success
|
||||
|
||||
## Next Steps
|
||||
[Recommendations if any]
|
||||
```
|
||||
|
||||
### Partial Completion
|
||||
|
||||
```markdown
|
||||
# Task Status: Partially Completed
|
||||
|
||||
## Completed
|
||||
- [What worked]
|
||||
- Files: `path/to/completed.ext`
|
||||
|
||||
## Blocked
|
||||
- **Issue**: [What failed]
|
||||
- **Root Cause**: [Analysis]
|
||||
- **Attempted**: [Solutions tried - attempt X of 3]
|
||||
|
||||
## Required
|
||||
[What's needed to proceed]
|
||||
|
||||
## Recommendation
|
||||
[Suggested next steps]
|
||||
```
|
||||
|
||||
### Code References
|
||||
|
||||
**Format**: `path/to/file:line_number`
|
||||
**Example**: `src/auth/jwt.ts:45` - Implemented following pattern from `src/auth/session.ts:78`
|
||||
|
||||
### Quality Checklist
|
||||
|
||||
- [ ] All tests pass
|
||||
- [ ] Build succeeds
|
||||
- [ ] All EXPECTED deliverables met
|
||||
- [ ] Code follows existing patterns
|
||||
- [ ] File changes listed at beginning
|
||||
@@ -0,0 +1,151 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Conflict Resolution Schema",
|
||||
"description": "Schema for conflict detection, strategy generation, and resolution output",
|
||||
|
||||
"type": "object",
|
||||
"required": ["conflicts", "summary"],
|
||||
"properties": {
|
||||
"conflicts": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["id", "brief", "severity", "category", "strategies", "recommended"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^CON-\\d{3}$",
|
||||
"description": "Conflict ID (CON-001, CON-002, ...)"
|
||||
},
|
||||
"brief": {
|
||||
"type": "string",
|
||||
"description": "一句话冲突摘要（中文）"
|
||||
},
|
||||
"severity": {
|
||||
"enum": ["Critical", "High", "Medium"],
|
||||
"description": "冲突严重程度"
|
||||
},
|
||||
"category": {
|
||||
"enum": ["Architecture", "API", "Data", "Dependency", "ModuleOverlap"],
|
||||
"description": "冲突类型"
|
||||
},
|
||||
"affected_files": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "受影响的文件路径"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "详细冲突描述"
|
||||
},
|
||||
"impact": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"scope": { "type": "string", "description": "影响的模块/组件" },
|
||||
"compatibility": { "enum": ["Yes", "No", "Partial"] },
|
||||
"migration_required": { "type": "boolean" },
|
||||
"estimated_effort": { "type": "string", "description": "人天估计" }
|
||||
}
|
||||
},
|
||||
"overlap_analysis": {
|
||||
"type": "object",
|
||||
"description": "仅当 category=ModuleOverlap 时需要",
|
||||
"properties": {
|
||||
"new_module": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"scenarios": { "type": "array", "items": { "type": "string" } },
|
||||
"responsibilities": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"existing_modules": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"file": { "type": "string" },
|
||||
"name": { "type": "string" },
|
||||
"scenarios": { "type": "array", "items": { "type": "string" } },
|
||||
"overlap_scenarios": { "type": "array", "items": { "type": "string" } },
|
||||
"responsibilities": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"strategies": {
|
||||
"type": "array",
|
||||
"minItems": 2,
|
||||
"maxItems": 4,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["name", "approach", "complexity", "risk", "effort", "pros", "cons"],
|
||||
"properties": {
|
||||
"name": { "type": "string", "description": "策略名称（中文）" },
|
||||
"approach": { "type": "string", "description": "实现方法简述" },
|
||||
"complexity": { "enum": ["Low", "Medium", "High"] },
|
||||
"risk": { "enum": ["Low", "Medium", "High"] },
|
||||
"effort": { "type": "string", "description": "时间估计" },
|
||||
"pros": { "type": "array", "items": { "type": "string" }, "description": "优点" },
|
||||
"cons": { "type": "array", "items": { "type": "string" }, "description": "缺点" },
|
||||
"clarification_needed": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "需要用户澄清的问题（尤其是 ModuleOverlap）"
|
||||
},
|
||||
"modifications": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["file", "section", "change_type", "old_content", "new_content", "rationale"],
|
||||
"properties": {
|
||||
"file": { "type": "string", "description": "相对项目根目录的完整路径" },
|
||||
"section": { "type": "string", "description": "Markdown heading 用于定位" },
|
||||
"change_type": { "enum": ["update", "add", "remove"] },
|
||||
"old_content": { "type": "string", "description": "原始内容片段（20-100字符，用于唯一匹配）" },
|
||||
"new_content": { "type": "string", "description": "修改后的内容" },
|
||||
"rationale": { "type": "string", "description": "修改理由" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"recommended": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"description": "推荐策略索引（0-based）"
|
||||
},
|
||||
"modification_suggestions": {
|
||||
"type": "array",
|
||||
"minItems": 2,
|
||||
"maxItems": 5,
|
||||
"items": { "type": "string" },
|
||||
"description": "自定义处理建议（2-5条，中文）"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"summary": {
|
||||
"type": "object",
|
||||
"required": ["total", "critical", "high", "medium"],
|
||||
"properties": {
|
||||
"total": { "type": "integer" },
|
||||
"critical": { "type": "integer" },
|
||||
"high": { "type": "integer" },
|
||||
"medium": { "type": "integer" }
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"_quality_standards": {
|
||||
"modifications": [
|
||||
"old_content: 20-100字符，确保 Edit 工具能唯一匹配",
|
||||
"new_content: 保持 markdown 格式",
|
||||
"change_type: update(替换), add(插入), remove(删除)"
|
||||
],
|
||||
"user_facing_text": "brief, name, pros, cons, modification_suggestions 使用中文",
|
||||
"technical_fields": "severity, category, complexity, risk 使用英文"
|
||||
}
|
||||
}
|
||||
127
.ccw/workflows/cli-templates/schemas/debug-log-json-schema.json
Normal file
127
.ccw/workflows/cli-templates/schemas/debug-log-json-schema.json
Normal file
@@ -0,0 +1,127 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Debug Log Entry Schema",
|
||||
"description": "NDJSON log entry for hypothesis-driven debugging workflow",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"sessionId",
|
||||
"runId",
|
||||
"hypothesisId",
|
||||
"location",
|
||||
"message",
|
||||
"data",
|
||||
"timestamp"
|
||||
],
|
||||
"properties": {
|
||||
"sessionId": {
|
||||
"type": "string",
|
||||
"pattern": "^DBG-[a-z0-9-]+-\\d{4}-\\d{2}-\\d{2}$",
|
||||
"description": "Debug session identifier (e.g., 'DBG-stack-length-not-found-2025-12-18')"
|
||||
},
|
||||
"runId": {
|
||||
"type": "string",
|
||||
"pattern": "^run-\\d+$",
|
||||
"description": "Reproduction run number (e.g., 'run-1', 'run-2')"
|
||||
},
|
||||
"hypothesisId": {
|
||||
"type": "string",
|
||||
"pattern": "^H\\d+$",
|
||||
"description": "Hypothesis identifier being tested (e.g., 'H1', 'H2')"
|
||||
},
|
||||
"location": {
|
||||
"type": "string",
|
||||
"description": "Code location in format 'file:function:line' or 'file:line'"
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"description": "Human-readable description of what's being logged"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"description": "Captured values for hypothesis validation",
|
||||
"properties": {
|
||||
"keys_sample": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Sample of dictionary/object keys (first 30)"
|
||||
},
|
||||
"value": {
|
||||
"description": "Captured value (any type)"
|
||||
},
|
||||
"expected_value": {
|
||||
"description": "Expected value for comparison"
|
||||
},
|
||||
"actual_type": {
|
||||
"type": "string",
|
||||
"description": "Actual type of captured value"
|
||||
},
|
||||
"count": {
|
||||
"type": "integer",
|
||||
"description": "Count of items (for arrays/collections)"
|
||||
},
|
||||
"is_null": {
|
||||
"type": "boolean",
|
||||
"description": "Whether value is null/None"
|
||||
},
|
||||
"is_empty": {
|
||||
"type": "boolean",
|
||||
"description": "Whether collection is empty"
|
||||
},
|
||||
"comparison_result": {
|
||||
"type": "string",
|
||||
"enum": ["match", "mismatch", "partial_match"],
|
||||
"description": "Result of value comparison"
|
||||
}
|
||||
}
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "integer",
|
||||
"description": "Unix timestamp in milliseconds"
|
||||
},
|
||||
"severity": {
|
||||
"type": "string",
|
||||
"enum": ["debug", "info", "warning", "error"],
|
||||
"default": "info",
|
||||
"description": "Log severity level"
|
||||
},
|
||||
"stack_trace": {
|
||||
"type": "string",
|
||||
"description": "Stack trace if capturing exception context"
|
||||
},
|
||||
"parent_entry_id": {
|
||||
"type": "string",
|
||||
"description": "Reference to parent log entry for nested contexts"
|
||||
}
|
||||
},
|
||||
"examples": [
|
||||
{
|
||||
"sessionId": "DBG-stack-length-not-found-2025-12-18",
|
||||
"runId": "run-1",
|
||||
"hypothesisId": "H1",
|
||||
"location": "rmxprt_api/core/rmxprt_parameter.py:sync_from_machine:642",
|
||||
"message": "Inspect stator keys from machine.to_dict and compare Stack Length vs Length",
|
||||
"data": {
|
||||
"keys_sample": ["Length", "Outer Diameter", "Inner Diameter", "Slot"],
|
||||
"stack_length_value": "未找到",
|
||||
"length_value": "120mm",
|
||||
"comparison_result": "mismatch"
|
||||
},
|
||||
"timestamp": 1734523456789
|
||||
},
|
||||
{
|
||||
"sessionId": "DBG-registered-zero-2025-12-18",
|
||||
"runId": "run-1",
|
||||
"hypothesisId": "H2",
|
||||
"location": "rmxprt_api/utils/param_core.py:update_variables_from_result_model:670",
|
||||
"message": "Check result parameters count and sample keys",
|
||||
"data": {
|
||||
"count": 0,
|
||||
"is_empty": true,
|
||||
"sections_parsed": ["Stator", "Rotor", "General"],
|
||||
"expected_count": 145
|
||||
},
|
||||
"timestamp": 1734523457123
|
||||
}
|
||||
]
|
||||
}
|
||||
234
.ccw/workflows/cli-templates/schemas/diagnosis-json-schema.json
Normal file
234
.ccw/workflows/cli-templates/schemas/diagnosis-json-schema.json
Normal file
@@ -0,0 +1,234 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Diagnosis Context Schema",
|
||||
"description": "Bug diagnosis results from cli-explore-agent for root cause analysis",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"symptom",
|
||||
"root_cause",
|
||||
"affected_files",
|
||||
"reproduction_steps",
|
||||
"fix_hints",
|
||||
"dependencies",
|
||||
"constraints",
|
||||
"clarification_needs",
|
||||
"_metadata"
|
||||
],
|
||||
"properties": {
|
||||
"symptom": {
|
||||
"type": "object",
|
||||
"required": ["description", "error_message"],
|
||||
"properties": {
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "Human-readable description of the bug symptoms"
|
||||
},
|
||||
"error_message": {
|
||||
"type": ["string", "null"],
|
||||
"description": "Exact error message if available, null if no specific error"
|
||||
},
|
||||
"stack_trace": {
|
||||
"type": ["string", "null"],
|
||||
"description": "Stack trace excerpt if available"
|
||||
},
|
||||
"frequency": {
|
||||
"type": "string",
|
||||
"enum": ["always", "intermittent", "rare", "unknown"],
|
||||
"description": "How often the bug occurs"
|
||||
},
|
||||
"user_impact": {
|
||||
"type": "string",
|
||||
"description": "How the bug affects end users"
|
||||
}
|
||||
},
|
||||
"description": "Observable symptoms and error manifestation"
|
||||
},
|
||||
"root_cause": {
|
||||
"type": "object",
|
||||
"required": ["file", "issue", "confidence"],
|
||||
"properties": {
|
||||
"file": {
|
||||
"type": "string",
|
||||
"description": "File path where the root cause is located"
|
||||
},
|
||||
"line_range": {
|
||||
"type": "string",
|
||||
"description": "Line range containing the bug (e.g., '45-60')"
|
||||
},
|
||||
"function": {
|
||||
"type": "string",
|
||||
"description": "Function or method name containing the bug"
|
||||
},
|
||||
"issue": {
|
||||
"type": "string",
|
||||
"description": "Description of what's wrong in the code"
|
||||
},
|
||||
"confidence": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"description": "Confidence score 0.0-1.0 (0.8+ high, 0.5-0.8 medium, <0.5 low)"
|
||||
},
|
||||
"introduced_by": {
|
||||
"type": "string",
|
||||
"description": "Commit hash or date when bug was introduced (if known)"
|
||||
},
|
||||
"category": {
|
||||
"type": "string",
|
||||
"enum": ["logic_error", "edge_case", "race_condition", "null_reference", "type_mismatch", "resource_leak", "validation", "integration", "configuration", "other"],
|
||||
"description": "Bug category classification"
|
||||
}
|
||||
},
|
||||
"description": "Root cause analysis with confidence score"
|
||||
},
|
||||
"affected_files": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"oneOf": [
|
||||
{"type": "string"},
|
||||
{
|
||||
"type": "object",
|
||||
"required": ["path", "relevance"],
|
||||
"properties": {
|
||||
"path": {"type": "string", "description": "File path relative to project root"},
|
||||
"relevance": {"type": "number", "minimum": 0, "maximum": 1, "description": "Relevance score 0.0-1.0 (0.7+ high, 0.5-0.7 medium, <0.5 low)"},
|
||||
"rationale": {"type": "string", "description": "Brief explanation of why this file is affected from this diagnosis angle"},
|
||||
"change_type": {
|
||||
"type": "string",
|
||||
"enum": ["fix_target", "needs_update", "test_coverage", "reference_only"],
|
||||
"description": "Type of change needed for this file"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"description": "Files affected by the bug. Prefer object format with relevance scores for synthesis prioritization."
|
||||
},
|
||||
"reproduction_steps": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"minItems": 1,
|
||||
"description": "Step-by-step instructions to reproduce the bug"
|
||||
},
|
||||
"fix_hints": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["description", "approach"],
|
||||
"properties": {
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "What needs to be fixed"
|
||||
},
|
||||
"approach": {
|
||||
"type": "string",
|
||||
"description": "Suggested fix approach with specific guidance"
|
||||
},
|
||||
"code_example": {
|
||||
"type": "string",
|
||||
"description": "Example code snippet showing the fix pattern"
|
||||
},
|
||||
"risk": {
|
||||
"type": "string",
|
||||
"enum": ["low", "medium", "high"],
|
||||
"description": "Risk level of implementing this fix"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Actionable fix suggestions from this diagnosis angle"
|
||||
},
|
||||
"dependencies": {
|
||||
"type": "string",
|
||||
"description": "External and internal dependencies relevant to the bug"
|
||||
},
|
||||
"constraints": {
|
||||
"type": "string",
|
||||
"description": "Technical constraints and limitations affecting the fix"
|
||||
},
|
||||
"related_issues": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["similar_bug", "regression", "related_feature", "tech_debt"],
|
||||
"description": "Relationship type"
|
||||
},
|
||||
"reference": {
|
||||
"type": "string",
|
||||
"description": "Issue ID, commit hash, or file reference"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "Brief description of the relationship"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Related issues, regressions, or similar bugs found during diagnosis"
|
||||
},
|
||||
"clarification_needs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["question", "context", "options"],
|
||||
"properties": {
|
||||
"question": {
|
||||
"type": "string",
|
||||
"description": "The clarification question to ask user"
|
||||
},
|
||||
"context": {
|
||||
"type": "string",
|
||||
"description": "Background context explaining why this clarification is needed"
|
||||
},
|
||||
"options": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Available options for user to choose from (2-4 options)"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Ambiguities requiring user input before fix planning"
|
||||
},
|
||||
"_metadata": {
|
||||
"type": "object",
|
||||
"required": ["timestamp", "bug_description", "source"],
|
||||
"properties": {
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of diagnosis"
|
||||
},
|
||||
"bug_description": {
|
||||
"type": "string",
|
||||
"description": "Original bug description that triggered diagnosis"
|
||||
},
|
||||
"source": {
|
||||
"type": "string",
|
||||
"const": "cli-explore-agent",
|
||||
"description": "Agent that performed diagnosis"
|
||||
},
|
||||
"diagnosis_angle": {
|
||||
"type": "string",
|
||||
"description": "Diagnosis angle (e.g., 'error-handling', 'dataflow', 'state-management')"
|
||||
},
|
||||
"diagnosis_index": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 4,
|
||||
"description": "Diagnosis index (1-4) in parallel diagnosis set"
|
||||
},
|
||||
"total_diagnoses": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 4,
|
||||
"description": "Total number of parallel diagnoses"
|
||||
},
|
||||
"duration_seconds": {
|
||||
"type": "integer",
|
||||
"description": "Diagnosis duration in seconds"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,219 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "discovery-finding-schema",
|
||||
"title": "Discovery Finding Schema",
|
||||
"description": "Schema for perspective-based issue discovery results",
|
||||
"type": "object",
|
||||
"required": ["perspective", "discovery_id", "analysis_timestamp", "cli_tool_used", "summary", "findings"],
|
||||
"properties": {
|
||||
"perspective": {
|
||||
"type": "string",
|
||||
"enum": ["bug", "ux", "test", "quality", "security", "performance", "maintainability", "best-practices"],
|
||||
"description": "Discovery perspective"
|
||||
},
|
||||
"discovery_id": {
|
||||
"type": "string",
|
||||
"pattern": "^DSC-\\d{8}-\\d{6}$",
|
||||
"description": "Parent discovery session ID"
|
||||
},
|
||||
"analysis_timestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of analysis"
|
||||
},
|
||||
"cli_tool_used": {
|
||||
"type": "string",
|
||||
"enum": ["gemini", "qwen", "codex"],
|
||||
"description": "CLI tool that performed the analysis"
|
||||
},
|
||||
"model": {
|
||||
"type": "string",
|
||||
"description": "Specific model version used",
|
||||
"examples": ["gemini-2.5-pro", "qwen-max"]
|
||||
},
|
||||
"analysis_duration_ms": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"description": "Analysis duration in milliseconds"
|
||||
},
|
||||
"summary": {
|
||||
"type": "object",
|
||||
"required": ["total_findings"],
|
||||
"properties": {
|
||||
"total_findings": { "type": "integer", "minimum": 0 },
|
||||
"critical": { "type": "integer", "minimum": 0 },
|
||||
"high": { "type": "integer", "minimum": 0 },
|
||||
"medium": { "type": "integer", "minimum": 0 },
|
||||
"low": { "type": "integer", "minimum": 0 },
|
||||
"files_analyzed": { "type": "integer", "minimum": 0 }
|
||||
},
|
||||
"description": "Summary statistics (FLAT structure, NOT nested)"
|
||||
},
|
||||
"findings": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["id", "title", "perspective", "priority", "category", "description", "file", "line"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^dsc-[a-z]+-\\d{3}-[a-f0-9]{8}$",
|
||||
"description": "Unique finding ID: dsc-{perspective}-{seq}-{uuid8}",
|
||||
"examples": ["dsc-bug-001-a1b2c3d4"]
|
||||
},
|
||||
"title": {
|
||||
"type": "string",
|
||||
"minLength": 10,
|
||||
"maxLength": 200,
|
||||
"description": "Concise finding title"
|
||||
},
|
||||
"perspective": {
|
||||
"type": "string",
|
||||
"enum": ["bug", "ux", "test", "quality", "security", "performance", "maintainability", "best-practices"]
|
||||
},
|
||||
"priority": {
|
||||
"type": "string",
|
||||
"enum": ["critical", "high", "medium", "low"],
|
||||
"description": "Priority level (lowercase only)"
|
||||
},
|
||||
"category": {
|
||||
"type": "string",
|
||||
"description": "Perspective-specific category",
|
||||
"examples": ["null-check", "edge-case", "missing-test", "complexity", "injection"]
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"minLength": 20,
|
||||
"description": "Detailed description of the finding"
|
||||
},
|
||||
"file": {
|
||||
"type": "string",
|
||||
"description": "File path relative to project root"
|
||||
},
|
||||
"line": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"description": "Line number of the finding"
|
||||
},
|
||||
"snippet": {
|
||||
"type": "string",
|
||||
"description": "Relevant code snippet"
|
||||
},
|
||||
"suggested_issue": {
|
||||
"type": "object",
|
||||
"required": ["title", "type", "priority"],
|
||||
"properties": {
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Suggested issue title for export"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["bug", "feature", "enhancement", "refactor", "test", "docs"],
|
||||
"description": "Issue type"
|
||||
},
|
||||
"priority": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 5,
|
||||
"description": "Priority 1-5 (1=critical, 5=low)"
|
||||
},
|
||||
"tags": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Suggested tags for the issue"
|
||||
}
|
||||
},
|
||||
"description": "Pre-filled issue suggestion for export"
|
||||
},
|
||||
"external_reference": {
|
||||
"type": ["object", "null"],
|
||||
"properties": {
|
||||
"source": { "type": "string" },
|
||||
"url": { "type": "string", "format": "uri" },
|
||||
"relevance": { "type": "string" }
|
||||
},
|
||||
"description": "External reference from Exa research (if applicable)"
|
||||
},
|
||||
"confidence": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"description": "Confidence score 0.0-1.0"
|
||||
},
|
||||
"impact": {
|
||||
"type": "string",
|
||||
"description": "Description of potential impact"
|
||||
},
|
||||
"recommendation": {
|
||||
"type": "string",
|
||||
"description": "Specific recommendation to address the finding"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"description": "Additional metadata (CWE ID, OWASP category, etc.)"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Array of discovered findings"
|
||||
},
|
||||
"cross_references": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"finding_id": { "type": "string" },
|
||||
"related_perspectives": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"reason": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"description": "Cross-references to findings in other perspectives"
|
||||
}
|
||||
},
|
||||
"examples": [
|
||||
{
|
||||
"perspective": "bug",
|
||||
"discovery_id": "DSC-20250128-143022",
|
||||
"analysis_timestamp": "2025-01-28T14:35:00Z",
|
||||
"cli_tool_used": "gemini",
|
||||
"model": "gemini-2.5-pro",
|
||||
"analysis_duration_ms": 45000,
|
||||
"summary": {
|
||||
"total_findings": 8,
|
||||
"critical": 1,
|
||||
"high": 2,
|
||||
"medium": 3,
|
||||
"low": 2,
|
||||
"files_analyzed": 5
|
||||
},
|
||||
"findings": [
|
||||
{
|
||||
"id": "dsc-bug-001-a1b2c3d4",
|
||||
"title": "Missing null check in user validation",
|
||||
"perspective": "bug",
|
||||
"priority": "high",
|
||||
"category": "null-check",
|
||||
"description": "User object is accessed without null check after database query, which may fail if user doesn't exist",
|
||||
"file": "src/auth/validator.ts",
|
||||
"line": 45,
|
||||
"snippet": "const user = await db.findUser(id);\nreturn user.email; // user may be null",
|
||||
"suggested_issue": {
|
||||
"title": "Add null check in user validation",
|
||||
"type": "bug",
|
||||
"priority": 2,
|
||||
"tags": ["bug", "auth"]
|
||||
},
|
||||
"external_reference": null,
|
||||
"confidence": 0.85,
|
||||
"impact": "Runtime error when user not found",
|
||||
"recommendation": "Add null check: if (!user) throw new NotFoundError('User not found');"
|
||||
}
|
||||
],
|
||||
"cross_references": []
|
||||
}
|
||||
]
|
||||
}
|
||||
125
.ccw/workflows/cli-templates/schemas/discovery-state-schema.json
Normal file
125
.ccw/workflows/cli-templates/schemas/discovery-state-schema.json
Normal file
@@ -0,0 +1,125 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "discovery-state-schema",
|
||||
"title": "Discovery State Schema (Merged)",
|
||||
"description": "Unified schema for issue discovery session (state + progress merged)",
|
||||
"type": "object",
|
||||
"required": ["discovery_id", "target_pattern", "phase", "created_at"],
|
||||
"properties": {
|
||||
"discovery_id": {
|
||||
"type": "string",
|
||||
"description": "Unique discovery session ID",
|
||||
"pattern": "^DSC-\\d{8}-\\d{6}$",
|
||||
"examples": ["DSC-20250128-143022"]
|
||||
},
|
||||
"target_pattern": {
|
||||
"type": "string",
|
||||
"description": "File/directory pattern being analyzed",
|
||||
"examples": ["src/auth/**", "codex-lens/**/*.py"]
|
||||
},
|
||||
"phase": {
|
||||
"type": "string",
|
||||
"enum": ["initialization", "parallel", "aggregation", "complete"],
|
||||
"description": "Current execution phase"
|
||||
},
|
||||
"created_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"updated_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"target": {
|
||||
"type": "object",
|
||||
"description": "Target module information",
|
||||
"properties": {
|
||||
"files_count": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"source": { "type": "integer" },
|
||||
"tests": { "type": "integer" },
|
||||
"total": { "type": "integer" }
|
||||
}
|
||||
},
|
||||
"project": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"version": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"perspectives": {
|
||||
"type": "array",
|
||||
"description": "Perspective analysis status (merged from progress)",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["name", "status"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"enum": ["bug", "ux", "test", "quality", "security", "performance", "maintainability", "best-practices"]
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["pending", "in_progress", "completed", "failed"]
|
||||
},
|
||||
"findings": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"external_research": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"enabled": { "type": "boolean", "default": false },
|
||||
"completed": { "type": "boolean", "default": false }
|
||||
}
|
||||
},
|
||||
"results": {
|
||||
"type": "object",
|
||||
"description": "Aggregated results (final phase)",
|
||||
"properties": {
|
||||
"total_findings": { "type": "integer", "minimum": 0 },
|
||||
"issues_generated": { "type": "integer", "minimum": 0 },
|
||||
"priority_distribution": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"critical": { "type": "integer" },
|
||||
"high": { "type": "integer" },
|
||||
"medium": { "type": "integer" },
|
||||
"low": { "type": "integer" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"examples": [
|
||||
{
|
||||
"discovery_id": "DSC-20251228-182237",
|
||||
"target_pattern": "codex-lens/**/*.py",
|
||||
"phase": "complete",
|
||||
"created_at": "2025-12-28T18:22:37+08:00",
|
||||
"updated_at": "2025-12-28T18:35:00+08:00",
|
||||
"target": {
|
||||
"files_count": { "source": 48, "tests": 44, "total": 93 },
|
||||
"project": { "name": "codex-lens", "version": "0.1.0" }
|
||||
},
|
||||
"perspectives": [
|
||||
{ "name": "bug", "status": "completed", "findings": 15 },
|
||||
{ "name": "test", "status": "completed", "findings": 11 },
|
||||
{ "name": "quality", "status": "completed", "findings": 12 }
|
||||
],
|
||||
"external_research": { "enabled": false, "completed": false },
|
||||
"results": {
|
||||
"total_findings": 37,
|
||||
"issues_generated": 15,
|
||||
"priority_distribution": { "critical": 4, "high": 13, "medium": 16, "low": 6 }
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
124
.ccw/workflows/cli-templates/schemas/explore-json-schema.json
Normal file
124
.ccw/workflows/cli-templates/schemas/explore-json-schema.json
Normal file
@@ -0,0 +1,124 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Exploration Context Schema",
|
||||
"description": "Code exploration results from cli-explore-agent for task context gathering",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"project_structure",
|
||||
"relevant_files",
|
||||
"patterns",
|
||||
"dependencies",
|
||||
"integration_points",
|
||||
"constraints",
|
||||
"clarification_needs",
|
||||
"_metadata"
|
||||
],
|
||||
"properties": {
|
||||
"project_structure": {
|
||||
"type": "string",
|
||||
"description": "Overall architecture description: module organization, layer structure, component relationships"
|
||||
},
|
||||
"relevant_files": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"oneOf": [
|
||||
{"type": "string"},
|
||||
{
|
||||
"type": "object",
|
||||
"required": ["path", "relevance"],
|
||||
"properties": {
|
||||
"path": {"type": "string", "description": "File path relative to project root"},
|
||||
"relevance": {"type": "number", "minimum": 0, "maximum": 1, "description": "Relevance score 0.0-1.0 (0.7+ high, 0.5-0.7 medium, <0.5 low)"},
|
||||
"rationale": {"type": "string", "description": "Brief explanation of why this file is relevant from this exploration angle"}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"description": "File paths to be modified or referenced for the task. Prefer object format with relevance scores for synthesis prioritization."
|
||||
},
|
||||
"patterns": {
|
||||
"type": "string",
|
||||
"description": "Existing code patterns, conventions, and styles found in the codebase"
|
||||
},
|
||||
"dependencies": {
|
||||
"type": "string",
|
||||
"description": "External and internal module dependencies relevant to the task"
|
||||
},
|
||||
"integration_points": {
|
||||
"type": "string",
|
||||
"description": "Where this task connects with existing code: APIs, hooks, events, shared state"
|
||||
},
|
||||
"constraints": {
|
||||
"type": "string",
|
||||
"description": "Technical constraints and limitations affecting implementation"
|
||||
},
|
||||
"clarification_needs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["question", "context", "options"],
|
||||
"properties": {
|
||||
"question": {
|
||||
"type": "string",
|
||||
"description": "The clarification question to ask user"
|
||||
},
|
||||
"context": {
|
||||
"type": "string",
|
||||
"description": "Background context explaining why this clarification is needed"
|
||||
},
|
||||
"options": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Available options for user to choose from (2-4 options)"
|
||||
},
|
||||
"recommended": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"description": "Zero-based index of recommended option in the options array. Based on codebase patterns and best practices analysis."
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Ambiguities requiring user input before planning"
|
||||
},
|
||||
"_metadata": {
|
||||
"type": "object",
|
||||
"required": ["timestamp", "task_description", "source"],
|
||||
"properties": {
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of exploration"
|
||||
},
|
||||
"task_description": {
|
||||
"type": "string",
|
||||
"description": "Original task description that triggered exploration"
|
||||
},
|
||||
"source": {
|
||||
"type": "string",
|
||||
"const": "cli-explore-agent",
|
||||
"description": "Agent that performed exploration"
|
||||
},
|
||||
"exploration_angle": {
|
||||
"type": "string",
|
||||
"description": "Agent-chosen exploration angle (e.g., 'architecture', 'security', 'dataflow')"
|
||||
},
|
||||
"exploration_index": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 4,
|
||||
"description": "Exploration index (1-4) in parallel exploration set"
|
||||
},
|
||||
"total_explorations": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 4,
|
||||
"description": "Total number of parallel explorations"
|
||||
},
|
||||
"duration_seconds": {
|
||||
"type": "integer",
|
||||
"description": "Exploration duration in seconds"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
298
.ccw/workflows/cli-templates/schemas/fix-plan-json-schema.json
Normal file
298
.ccw/workflows/cli-templates/schemas/fix-plan-json-schema.json
Normal file
@@ -0,0 +1,298 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Fix Plan Schema",
|
||||
"description": "Bug fix plan from cli-lite-planning-agent or direct planning",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"summary",
|
||||
"root_cause",
|
||||
"strategy",
|
||||
"tasks",
|
||||
"estimated_time",
|
||||
"recommended_execution",
|
||||
"severity",
|
||||
"risk_level",
|
||||
"_metadata"
|
||||
],
|
||||
"properties": {
|
||||
"summary": {
|
||||
"type": "string",
|
||||
"description": "2-3 sentence overview of the fix plan"
|
||||
},
|
||||
"root_cause": {
|
||||
"type": "string",
|
||||
"description": "Consolidated root cause statement from all diagnoses"
|
||||
},
|
||||
"strategy": {
|
||||
"type": "string",
|
||||
"enum": ["immediate_patch", "comprehensive_fix", "refactor"],
|
||||
"description": "Fix strategy: immediate_patch (minimal change), comprehensive_fix (proper solution), refactor (structural improvement)"
|
||||
},
|
||||
"tasks": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"maxItems": 5,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["id", "title", "scope", "action", "description", "implementation", "verification"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^FIX[0-9]+$",
|
||||
"description": "Task identifier (FIX1, FIX2, FIX3...)"
|
||||
},
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Task title (action verb + target, e.g., 'Fix token validation edge case')"
|
||||
},
|
||||
"scope": {
|
||||
"type": "string",
|
||||
"description": "Task scope: module path (src/auth/), feature name, or single file. Prefer module level."
|
||||
},
|
||||
"file": {
|
||||
"type": "string",
|
||||
"description": "Primary file (deprecated, use scope + modification_points instead)"
|
||||
},
|
||||
"action": {
|
||||
"type": "string",
|
||||
"enum": ["Fix", "Update", "Refactor", "Add", "Delete", "Configure"],
|
||||
"description": "Primary action type"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "What to fix (1-2 sentences)"
|
||||
},
|
||||
"modification_points": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["file", "target", "change"],
|
||||
"properties": {
|
||||
"file": {
|
||||
"type": "string",
|
||||
"description": "File path within scope"
|
||||
},
|
||||
"target": {
|
||||
"type": "string",
|
||||
"description": "Function/class/line range (e.g., 'validateToken:45-60')"
|
||||
},
|
||||
"change": {
|
||||
"type": "string",
|
||||
"description": "Brief description of change"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "All modification points for this fix task. Group related changes into one task."
|
||||
},
|
||||
"implementation": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"minItems": 2,
|
||||
"maxItems": 5,
|
||||
"description": "Step-by-step fix implementation guide"
|
||||
},
|
||||
"verification": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"minItems": 1,
|
||||
"maxItems": 3,
|
||||
"description": "Verification/test criteria to confirm fix works"
|
||||
},
|
||||
"reference": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"pattern": {
|
||||
"type": "string",
|
||||
"description": "Pattern name to follow"
|
||||
},
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Reference file paths to study"
|
||||
},
|
||||
"examples": {
|
||||
"type": "string",
|
||||
"description": "Specific guidance or example references"
|
||||
}
|
||||
},
|
||||
"description": "Reference materials for fix implementation (optional)"
|
||||
},
|
||||
"depends_on": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"pattern": "^FIX[0-9]+$"
|
||||
},
|
||||
"description": "Task IDs this task depends on (e.g., ['FIX1'])"
|
||||
},
|
||||
"risk": {
|
||||
"type": "string",
|
||||
"enum": ["low", "medium", "high"],
|
||||
"description": "Risk level of this specific fix task"
|
||||
},
|
||||
"cli_execution_id": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-zA-Z0-9_-]+$",
|
||||
"description": "Fixed CLI execution ID for this fix task (e.g., 'session-FIX1', 'bugfix-001-diagnosis')"
|
||||
},
|
||||
"cli_execution": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"strategy": {
|
||||
"type": "string",
|
||||
"enum": ["new", "resume", "fork", "merge_fork"],
|
||||
"description": "CLI execution strategy: new (no deps), resume (1 dep, continue), fork (1 dep, branch), merge_fork (N deps, combine)"
|
||||
},
|
||||
"resume_from": {
|
||||
"type": "string",
|
||||
"description": "Parent task's cli_execution_id (for resume/fork strategies)"
|
||||
},
|
||||
"merge_from": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Multiple parents' cli_execution_ids (for merge_fork strategy)"
|
||||
}
|
||||
},
|
||||
"description": "CLI execution strategy based on task dependencies"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Structured fix task breakdown (1-5 tasks)"
|
||||
},
|
||||
"flow_control": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"execution_order": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"phase": {
|
||||
"type": "string",
|
||||
"description": "Phase name (e.g., 'parallel-1', 'sequential-1')"
|
||||
},
|
||||
"tasks": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Task IDs in this phase"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["parallel", "sequential"],
|
||||
"description": "Execution type"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Ordered execution phases"
|
||||
},
|
||||
"exit_conditions": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"success": {
|
||||
"type": "string",
|
||||
"description": "Condition for successful fix completion"
|
||||
},
|
||||
"failure": {
|
||||
"type": "string",
|
||||
"description": "Condition that indicates fix failure"
|
||||
}
|
||||
},
|
||||
"description": "Conditions for fix workflow termination"
|
||||
}
|
||||
},
|
||||
"description": "Execution flow control (optional, auto-inferred from depends_on if not provided)"
|
||||
},
|
||||
"focus_paths": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Key file paths affected by this fix (aggregated from tasks)"
|
||||
},
|
||||
"test_strategy": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"scope": {
|
||||
"type": "string",
|
||||
"enum": ["unit", "integration", "e2e", "smoke", "full"],
|
||||
"description": "Test scope to run after fix"
|
||||
},
|
||||
"specific_tests": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Specific test files or patterns to run"
|
||||
},
|
||||
"manual_verification": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Manual verification steps if automated tests not available"
|
||||
}
|
||||
},
|
||||
"description": "Testing strategy for fix verification"
|
||||
},
|
||||
"rollback_plan": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"strategy": {
|
||||
"type": "string",
|
||||
"enum": ["git_revert", "feature_flag", "manual"],
|
||||
"description": "Rollback strategy if fix fails"
|
||||
},
|
||||
"steps": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Rollback steps"
|
||||
}
|
||||
},
|
||||
"description": "Rollback plan if fix causes issues (optional, recommended for high severity)"
|
||||
},
|
||||
"estimated_time": {
|
||||
"type": "string",
|
||||
"description": "Total estimated fix time (e.g., '30 minutes', '2 hours')"
|
||||
},
|
||||
"recommended_execution": {
|
||||
"type": "string",
|
||||
"enum": ["Agent", "Codex"],
|
||||
"description": "Recommended execution method based on complexity"
|
||||
},
|
||||
"severity": {
|
||||
"type": "string",
|
||||
"enum": ["Low", "Medium", "High", "Critical"],
|
||||
"description": "Bug severity level"
|
||||
},
|
||||
"risk_level": {
|
||||
"type": "string",
|
||||
"enum": ["low", "medium", "high"],
|
||||
"description": "Risk level of implementing the fix"
|
||||
},
|
||||
"_metadata": {
|
||||
"type": "object",
|
||||
"required": ["timestamp", "source"],
|
||||
"properties": {
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of planning"
|
||||
},
|
||||
"source": {
|
||||
"type": "string",
|
||||
"enum": ["cli-lite-planning-agent", "direct-planning"],
|
||||
"description": "Planning source"
|
||||
},
|
||||
"planning_mode": {
|
||||
"type": "string",
|
||||
"enum": ["direct", "agent-based"],
|
||||
"description": "Planning execution mode"
|
||||
},
|
||||
"diagnosis_angles": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Diagnosis angles used for context"
|
||||
},
|
||||
"duration_seconds": {
|
||||
"type": "integer",
|
||||
"description": "Planning duration in seconds"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
170
.ccw/workflows/cli-templates/schemas/issues-jsonl-schema.json
Normal file
170
.ccw/workflows/cli-templates/schemas/issues-jsonl-schema.json
Normal file
@@ -0,0 +1,170 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Issues JSONL Schema",
|
||||
"description": "Schema for each line in issues.jsonl (flat storage)",
|
||||
"type": "object",
|
||||
"required": ["id", "title", "status", "created_at"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Issue ID (GH-123, ISS-xxx, DSC-001)"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["registered", "planning", "planned", "queued", "executing", "completed", "failed", "paused"],
|
||||
"default": "registered"
|
||||
},
|
||||
"priority": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 5,
|
||||
"default": 3,
|
||||
"description": "1=critical, 2=high, 3=medium, 4=low, 5=trivial"
|
||||
},
|
||||
"context": {
|
||||
"type": "string",
|
||||
"description": "Issue context/description (markdown)"
|
||||
},
|
||||
"source": {
|
||||
"type": "string",
|
||||
"enum": ["github", "text", "discovery"],
|
||||
"description": "Source of the issue"
|
||||
},
|
||||
"source_url": {
|
||||
"type": "string",
|
||||
"description": "Original source URL (for GitHub issues)"
|
||||
},
|
||||
"tags": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Issue tags"
|
||||
},
|
||||
"extended_context": {
|
||||
"type": "object",
|
||||
"description": "Minimal extended context for planning hints",
|
||||
"properties": {
|
||||
"location": {
|
||||
"type": "string",
|
||||
"description": "file:line format (e.g., 'src/auth.ts:42')"
|
||||
},
|
||||
"suggested_fix": {
|
||||
"type": "string",
|
||||
"description": "Suggested remediation"
|
||||
},
|
||||
"notes": {
|
||||
"type": "string",
|
||||
"description": "Additional notes (user clarifications or discovery hints)"
|
||||
}
|
||||
}
|
||||
},
|
||||
"affected_components": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Files/modules affected"
|
||||
},
|
||||
"feedback": {
|
||||
"type": "array",
|
||||
"description": "Execution feedback history (failures, clarifications, rejections) for planning phase reference",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["type", "stage", "content", "created_at"],
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["failure", "clarification", "rejection"],
|
||||
"description": "Type of feedback"
|
||||
},
|
||||
"stage": {
|
||||
"type": "string",
|
||||
"enum": ["new", "plan", "execute"],
|
||||
"description": "Which stage the feedback occurred (new=creation, plan=planning, execute=execution)"
|
||||
},
|
||||
"content": {
|
||||
"type": "string",
|
||||
"description": "JSON string for failures (with solution_id, task_id, error_type, message, stack_trace) or plain text for clarifications/rejections"
|
||||
},
|
||||
"created_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "Timestamp when feedback was created"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"lifecycle_requirements": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"test_strategy": {
|
||||
"type": "string",
|
||||
"enum": ["unit", "integration", "e2e", "manual", "auto"]
|
||||
},
|
||||
"regression_scope": {
|
||||
"type": "string",
|
||||
"enum": ["affected", "related", "full"]
|
||||
},
|
||||
"acceptance_type": {
|
||||
"type": "string",
|
||||
"enum": ["automated", "manual", "both"]
|
||||
},
|
||||
"commit_strategy": {
|
||||
"type": "string",
|
||||
"enum": ["per-task", "squash", "atomic"]
|
||||
}
|
||||
}
|
||||
},
|
||||
"bound_solution_id": {
|
||||
"type": "string",
|
||||
"description": "ID of the bound solution (null if none bound)"
|
||||
},
|
||||
"solution_count": {
|
||||
"type": "integer",
|
||||
"default": 0,
|
||||
"description": "Number of candidate solutions"
|
||||
},
|
||||
"created_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"updated_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"planned_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"completed_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
}
|
||||
},
|
||||
"examples": [
|
||||
{
|
||||
"id": "DSC-001",
|
||||
"title": "Fix: SQLite connection pool memory leak",
|
||||
"status": "registered",
|
||||
"priority": 1,
|
||||
"context": "Connection pool cleanup only happens when MAX_POOL_SIZE is reached...",
|
||||
"source": "discovery",
|
||||
"tags": ["bug", "resource-leak", "critical"],
|
||||
"extended_context": {
|
||||
"location": "storage/sqlite_store.py:59",
|
||||
"suggested_fix": "Implement periodic cleanup or weak references",
|
||||
"notes": null
|
||||
},
|
||||
"affected_components": ["storage/sqlite_store.py"],
|
||||
"lifecycle_requirements": {
|
||||
"test_strategy": "unit",
|
||||
"regression_scope": "affected",
|
||||
"acceptance_type": "automated",
|
||||
"commit_strategy": "per-task"
|
||||
},
|
||||
"bound_solution_id": null,
|
||||
"solution_count": 0,
|
||||
"created_at": "2025-12-28T18:22:37Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,421 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Multi-CLI Discussion Artifact Schema",
|
||||
"description": "Visualization-friendly output for multi-CLI collaborative discussion agent",
|
||||
"type": "object",
|
||||
"required": ["metadata", "discussionTopic", "relatedFiles", "planning", "decision", "decisionRecords"],
|
||||
"properties": {
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"required": ["artifactId", "roundId", "timestamp", "contributingAgents"],
|
||||
"properties": {
|
||||
"artifactId": {
|
||||
"type": "string",
|
||||
"description": "Unique ID for this artifact (e.g., 'MCP-auth-refactor-2026-01-13-round-1')"
|
||||
},
|
||||
"roundId": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"description": "Discussion round number"
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp"
|
||||
},
|
||||
"contributingAgents": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/AgentIdentifier"
|
||||
},
|
||||
"description": "Agents that contributed to this artifact"
|
||||
},
|
||||
"durationSeconds": {
|
||||
"type": "integer",
|
||||
"description": "Total duration in seconds"
|
||||
},
|
||||
"exportFormats": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"enum": ["markdown", "html"]
|
||||
},
|
||||
"description": "Supported export formats"
|
||||
}
|
||||
}
|
||||
},
|
||||
"discussionTopic": {
|
||||
"type": "object",
|
||||
"required": ["title", "description", "status"],
|
||||
"properties": {
|
||||
"title": {
|
||||
"$ref": "#/definitions/I18nLabel"
|
||||
},
|
||||
"description": {
|
||||
"$ref": "#/definitions/I18nLabel"
|
||||
},
|
||||
"scope": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"included": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/I18nLabel" },
|
||||
"description": "What's in scope"
|
||||
},
|
||||
"excluded": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/I18nLabel" },
|
||||
"description": "What's explicitly out of scope"
|
||||
}
|
||||
}
|
||||
},
|
||||
"keyQuestions": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/I18nLabel" },
|
||||
"description": "Questions being explored"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["exploring", "analyzing", "debating", "decided", "blocked"],
|
||||
"description": "Discussion status"
|
||||
},
|
||||
"tags": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Tags for filtering (e.g., ['auth', 'security', 'api'])"
|
||||
}
|
||||
}
|
||||
},
|
||||
"relatedFiles": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"fileTree": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/FileNode" },
|
||||
"description": "File tree structure"
|
||||
},
|
||||
"dependencyGraph": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/DependencyEdge" },
|
||||
"description": "Dependency relationships"
|
||||
},
|
||||
"impactSummary": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/FileImpact" },
|
||||
"description": "File impact summary"
|
||||
}
|
||||
}
|
||||
},
|
||||
"planning": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"functional": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/Requirement" },
|
||||
"description": "Functional requirements"
|
||||
},
|
||||
"nonFunctional": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/Requirement" },
|
||||
"description": "Non-functional requirements"
|
||||
},
|
||||
"acceptanceCriteria": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/AcceptanceCriterion" },
|
||||
"description": "Acceptance criteria"
|
||||
}
|
||||
}
|
||||
},
|
||||
"decision": {
|
||||
"type": "object",
|
||||
"required": ["status", "confidenceScore"],
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["pending", "decided", "conflict"],
|
||||
"description": "Decision status"
|
||||
},
|
||||
"summary": {
|
||||
"$ref": "#/definitions/I18nLabel"
|
||||
},
|
||||
"selectedSolution": {
|
||||
"$ref": "#/definitions/Solution"
|
||||
},
|
||||
"rejectedAlternatives": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/RejectedSolution" }
|
||||
},
|
||||
"confidenceScore": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"description": "Confidence score (0.0 to 1.0)"
|
||||
}
|
||||
}
|
||||
},
|
||||
"decisionRecords": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"timeline": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/DecisionEvent" },
|
||||
"description": "Timeline of decision events"
|
||||
}
|
||||
}
|
||||
},
|
||||
"_internal": {
|
||||
"type": "object",
|
||||
"description": "Internal analysis data (for debugging)",
|
||||
"properties": {
|
||||
"cli_analyses": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/CLIAnalysis" }
|
||||
},
|
||||
"cross_verification": {
|
||||
"$ref": "#/definitions/CrossVerification"
|
||||
},
|
||||
"convergence": {
|
||||
"$ref": "#/definitions/ConvergenceMetrics"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"I18nLabel": {
|
||||
"type": "object",
|
||||
"required": ["en", "zh"],
|
||||
"properties": {
|
||||
"en": { "type": "string" },
|
||||
"zh": { "type": "string" }
|
||||
},
|
||||
"description": "Multi-language label for UI display"
|
||||
},
|
||||
"AgentIdentifier": {
|
||||
"type": "object",
|
||||
"required": ["name", "id"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"enum": ["Gemini", "Codex", "Qwen", "Human", "System"]
|
||||
},
|
||||
"id": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"FileNode": {
|
||||
"type": "object",
|
||||
"required": ["path", "type"],
|
||||
"properties": {
|
||||
"path": { "type": "string" },
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["file", "directory"]
|
||||
},
|
||||
"modificationStatus": {
|
||||
"type": "string",
|
||||
"enum": ["added", "modified", "deleted", "unchanged"]
|
||||
},
|
||||
"impactScore": {
|
||||
"type": "string",
|
||||
"enum": ["critical", "high", "medium", "low"]
|
||||
},
|
||||
"children": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/FileNode" }
|
||||
},
|
||||
"codeSnippet": { "$ref": "#/definitions/CodeSnippet" }
|
||||
}
|
||||
},
|
||||
"DependencyEdge": {
|
||||
"type": "object",
|
||||
"required": ["source", "target", "relationship"],
|
||||
"properties": {
|
||||
"source": { "type": "string" },
|
||||
"target": { "type": "string" },
|
||||
"relationship": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"FileImpact": {
|
||||
"type": "object",
|
||||
"required": ["filePath", "score", "reasoning"],
|
||||
"properties": {
|
||||
"filePath": { "type": "string" },
|
||||
"line": { "type": "integer" },
|
||||
"score": {
|
||||
"type": "string",
|
||||
"enum": ["critical", "high", "medium", "low"]
|
||||
},
|
||||
"reasoning": { "$ref": "#/definitions/I18nLabel" }
|
||||
}
|
||||
},
|
||||
"CodeSnippet": {
|
||||
"type": "object",
|
||||
"required": ["startLine", "endLine", "code"],
|
||||
"properties": {
|
||||
"startLine": { "type": "integer" },
|
||||
"endLine": { "type": "integer" },
|
||||
"code": { "type": "string" },
|
||||
"language": { "type": "string" },
|
||||
"comment": { "$ref": "#/definitions/I18nLabel" }
|
||||
}
|
||||
},
|
||||
"Requirement": {
|
||||
"type": "object",
|
||||
"required": ["id", "description", "priority"],
|
||||
"properties": {
|
||||
"id": { "type": "string" },
|
||||
"description": { "$ref": "#/definitions/I18nLabel" },
|
||||
"priority": {
|
||||
"type": "string",
|
||||
"enum": ["critical", "high", "medium", "low"]
|
||||
},
|
||||
"source": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"AcceptanceCriterion": {
|
||||
"type": "object",
|
||||
"required": ["id", "description", "isMet"],
|
||||
"properties": {
|
||||
"id": { "type": "string" },
|
||||
"description": { "$ref": "#/definitions/I18nLabel" },
|
||||
"isMet": { "type": "boolean" }
|
||||
}
|
||||
},
|
||||
"Solution": {
|
||||
"type": "object",
|
||||
"required": ["id", "title", "description"],
|
||||
"properties": {
|
||||
"id": { "type": "string" },
|
||||
"title": { "$ref": "#/definitions/I18nLabel" },
|
||||
"description": { "$ref": "#/definitions/I18nLabel" },
|
||||
"pros": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/I18nLabel" }
|
||||
},
|
||||
"cons": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/I18nLabel" }
|
||||
},
|
||||
"estimatedEffort": { "$ref": "#/definitions/I18nLabel" },
|
||||
"risk": {
|
||||
"type": "string",
|
||||
"enum": ["critical", "high", "medium", "low"]
|
||||
},
|
||||
"affectedFiles": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/FileImpact" }
|
||||
},
|
||||
"sourceCLIs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"RejectedSolution": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/definitions/Solution" },
|
||||
{
|
||||
"type": "object",
|
||||
"required": ["rejectionReason"],
|
||||
"properties": {
|
||||
"rejectionReason": { "$ref": "#/definitions/I18nLabel" }
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"DecisionEvent": {
|
||||
"type": "object",
|
||||
"required": ["eventId", "timestamp", "type", "contributor", "summary"],
|
||||
"properties": {
|
||||
"eventId": { "type": "string" },
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["proposal", "argument", "agreement", "disagreement", "decision", "reversal"]
|
||||
},
|
||||
"contributor": { "$ref": "#/definitions/AgentIdentifier" },
|
||||
"summary": { "$ref": "#/definitions/I18nLabel" },
|
||||
"evidence": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/Evidence" }
|
||||
},
|
||||
"reversibility": {
|
||||
"type": "string",
|
||||
"enum": ["easily_reversible", "requires_refactoring", "irreversible"]
|
||||
}
|
||||
}
|
||||
},
|
||||
"Evidence": {
|
||||
"type": "object",
|
||||
"required": ["type", "content", "description"],
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["link", "code_snippet", "log_output", "benchmark", "reference"]
|
||||
},
|
||||
"content": {},
|
||||
"description": { "$ref": "#/definitions/I18nLabel" }
|
||||
}
|
||||
},
|
||||
"CLIAnalysis": {
|
||||
"type": "object",
|
||||
"required": ["tool", "perspective", "feasibility_score"],
|
||||
"properties": {
|
||||
"tool": {
|
||||
"type": "string",
|
||||
"enum": ["gemini", "codex", "qwen"]
|
||||
},
|
||||
"perspective": { "type": "string" },
|
||||
"feasibility_score": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1
|
||||
},
|
||||
"findings": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"implementation_approaches": { "type": "array" },
|
||||
"technical_concerns": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"code_locations": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/FileImpact" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"CrossVerification": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"agreements": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"disagreements": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"resolution": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"ConvergenceMetrics": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"score": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1
|
||||
},
|
||||
"new_insights": { "type": "boolean" },
|
||||
"recommendation": {
|
||||
"type": "string",
|
||||
"enum": ["continue", "converged", "user_input_needed"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
444
.ccw/workflows/cli-templates/schemas/plan-json-schema.json
Normal file
444
.ccw/workflows/cli-templates/schemas/plan-json-schema.json
Normal file
@@ -0,0 +1,444 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Plan Object Schema",
|
||||
"description": "Implementation plan from cli-lite-planning-agent or direct planning",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"summary",
|
||||
"approach",
|
||||
"tasks",
|
||||
"estimated_time",
|
||||
"recommended_execution",
|
||||
"complexity",
|
||||
"_metadata"
|
||||
],
|
||||
"properties": {
|
||||
"summary": {
|
||||
"type": "string",
|
||||
"description": "2-3 sentence overview of the implementation plan"
|
||||
},
|
||||
"approach": {
|
||||
"type": "string",
|
||||
"description": "High-level implementation strategy and methodology"
|
||||
},
|
||||
"tasks": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"maxItems": 10,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["id", "title", "scope", "action", "description", "implementation", "acceptance"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^T[0-9]+$",
|
||||
"description": "Task identifier (T1, T2, T3...)"
|
||||
},
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Task title (action verb + target module/feature)"
|
||||
},
|
||||
"scope": {
|
||||
"type": "string",
|
||||
"description": "Task scope: module path (src/auth/), feature name, or single file. Prefer module/feature level over single file."
|
||||
},
|
||||
"file": {
|
||||
"type": "string",
|
||||
"description": "Primary file (deprecated, use scope + modification_points instead)"
|
||||
},
|
||||
"action": {
|
||||
"type": "string",
|
||||
"enum": ["Create", "Update", "Implement", "Refactor", "Add", "Delete", "Configure", "Test", "Fix"],
|
||||
"description": "Primary action type"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "What to implement (1-2 sentences)"
|
||||
},
|
||||
"modification_points": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["file", "target", "change"],
|
||||
"properties": {
|
||||
"file": {
|
||||
"type": "string",
|
||||
"description": "File path within scope"
|
||||
},
|
||||
"target": {
|
||||
"type": "string",
|
||||
"description": "Function/class/line range (e.g., 'validateToken:45-60')"
|
||||
},
|
||||
"change": {
|
||||
"type": "string",
|
||||
"description": "Brief description of change"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "All modification points for this task. Group related changes (same feature/module) into one task with multiple modification_points."
|
||||
},
|
||||
"implementation": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"minItems": 2,
|
||||
"maxItems": 7,
|
||||
"description": "Step-by-step implementation guide"
|
||||
},
|
||||
"reference": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"pattern": {
|
||||
"type": "string",
|
||||
"description": "Pattern name to follow"
|
||||
},
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Reference file paths to study"
|
||||
},
|
||||
"examples": {
|
||||
"type": "string",
|
||||
"description": "Specific guidance or example references"
|
||||
}
|
||||
},
|
||||
"description": "Reference materials for implementation (optional)"
|
||||
},
|
||||
"acceptance": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"minItems": 1,
|
||||
"maxItems": 4,
|
||||
"description": "Verification criteria (quantified, testable)"
|
||||
},
|
||||
"depends_on": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"pattern": "^T[0-9]+$"
|
||||
},
|
||||
"description": "Task IDs this task depends on (e.g., ['T1', 'T2'])"
|
||||
},
|
||||
"cli_execution_id": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-zA-Z0-9_-]+$",
|
||||
"description": "Fixed CLI execution ID for this task (e.g., 'session-T1', 'IMPL-001-analysis')"
|
||||
},
|
||||
"cli_execution": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"strategy": {
|
||||
"type": "string",
|
||||
"enum": ["new", "resume", "fork", "merge_fork"],
|
||||
"description": "CLI execution strategy: new (no deps), resume (1 dep, continue), fork (1 dep, branch), merge_fork (N deps, combine)"
|
||||
},
|
||||
"resume_from": {
|
||||
"type": "string",
|
||||
"description": "Parent task's cli_execution_id (for resume/fork strategies)"
|
||||
},
|
||||
"merge_from": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Multiple parents' cli_execution_ids (for merge_fork strategy)"
|
||||
}
|
||||
},
|
||||
"description": "CLI execution strategy based on task dependencies"
|
||||
},
|
||||
"rationale": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"chosen_approach": {
|
||||
"type": "string",
|
||||
"description": "The selected implementation approach and why it was chosen"
|
||||
},
|
||||
"alternatives_considered": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Alternative approaches that were considered but not chosen"
|
||||
},
|
||||
"decision_factors": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Key factors that influenced the decision (performance, maintainability, cost, etc.)"
|
||||
},
|
||||
"tradeoffs": {
|
||||
"type": "string",
|
||||
"description": "Known tradeoffs of the chosen approach"
|
||||
}
|
||||
},
|
||||
"description": "Design rationale explaining WHY this approach was chosen (required for Medium/High complexity)"
|
||||
},
|
||||
"verification": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"unit_tests": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "List of unit test names/descriptions to create"
|
||||
},
|
||||
"integration_tests": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "List of integration test names/descriptions to create"
|
||||
},
|
||||
"manual_checks": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Manual verification steps with specific actions"
|
||||
},
|
||||
"success_metrics": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Quantified metrics for success (e.g., 'Response time <200ms', 'Coverage >80%')"
|
||||
}
|
||||
},
|
||||
"description": "Detailed verification steps beyond acceptance criteria (required for Medium/High complexity)"
|
||||
},
|
||||
"risks": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["description", "probability", "impact", "mitigation"],
|
||||
"properties": {
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "Description of the risk"
|
||||
},
|
||||
"probability": {
|
||||
"type": "string",
|
||||
"enum": ["Low", "Medium", "High"],
|
||||
"description": "Likelihood of the risk occurring"
|
||||
},
|
||||
"impact": {
|
||||
"type": "string",
|
||||
"enum": ["Low", "Medium", "High"],
|
||||
"description": "Impact severity if the risk occurs"
|
||||
},
|
||||
"mitigation": {
|
||||
"type": "string",
|
||||
"description": "Strategy to mitigate or prevent the risk"
|
||||
},
|
||||
"fallback": {
|
||||
"type": "string",
|
||||
"description": "Alternative approach if mitigation fails"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Risk assessment and mitigation strategies (required for High complexity)"
|
||||
},
|
||||
"code_skeleton": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"interfaces": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"definition": {"type": "string"},
|
||||
"purpose": {"type": "string"}
|
||||
}
|
||||
},
|
||||
"description": "Key interface/type definitions"
|
||||
},
|
||||
"key_functions": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"signature": {"type": "string"},
|
||||
"purpose": {"type": "string"},
|
||||
"returns": {"type": "string"}
|
||||
}
|
||||
},
|
||||
"description": "Critical function signatures"
|
||||
},
|
||||
"classes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"purpose": {"type": "string"},
|
||||
"methods": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Key class structures"
|
||||
}
|
||||
},
|
||||
"description": "Code skeleton with interface/function signatures (required for High complexity)"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Structured task breakdown (1-10 tasks)"
|
||||
},
|
||||
"data_flow": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"diagram": {
|
||||
"type": "string",
|
||||
"description": "ASCII/text representation of data flow (e.g., 'A → B → C')"
|
||||
},
|
||||
"stages": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["stage", "input", "output", "component"],
|
||||
"properties": {
|
||||
"stage": {
|
||||
"type": "string",
|
||||
"description": "Stage name (e.g., 'Extraction', 'Processing', 'Storage')"
|
||||
},
|
||||
"input": {
|
||||
"type": "string",
|
||||
"description": "Input data format/type"
|
||||
},
|
||||
"output": {
|
||||
"type": "string",
|
||||
"description": "Output data format/type"
|
||||
},
|
||||
"component": {
|
||||
"type": "string",
|
||||
"description": "Component/module handling this stage"
|
||||
},
|
||||
"transformations": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Data transformations applied in this stage"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Detailed data flow stages"
|
||||
},
|
||||
"dependencies": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "External dependencies or data sources"
|
||||
}
|
||||
},
|
||||
"description": "Global data flow design showing how data moves through the system (required for High complexity)"
|
||||
},
|
||||
"design_decisions": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["decision", "rationale"],
|
||||
"properties": {
|
||||
"decision": {
|
||||
"type": "string",
|
||||
"description": "The design decision made"
|
||||
},
|
||||
"rationale": {
|
||||
"type": "string",
|
||||
"description": "Why this decision was made"
|
||||
},
|
||||
"tradeoff": {
|
||||
"type": "string",
|
||||
"description": "What was traded off for this decision"
|
||||
},
|
||||
"alternatives": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Alternatives that were considered"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Global design decisions that affect the entire plan"
|
||||
},
|
||||
"flow_control": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"execution_order": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"phase": {
|
||||
"type": "string",
|
||||
"description": "Phase name (e.g., 'parallel-1', 'sequential-1')"
|
||||
},
|
||||
"tasks": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Task IDs in this phase"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["parallel", "sequential"],
|
||||
"description": "Execution type"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Ordered execution phases"
|
||||
},
|
||||
"exit_conditions": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"success": {
|
||||
"type": "string",
|
||||
"description": "Condition for successful completion"
|
||||
},
|
||||
"failure": {
|
||||
"type": "string",
|
||||
"description": "Condition that indicates failure"
|
||||
}
|
||||
},
|
||||
"description": "Conditions for workflow termination"
|
||||
}
|
||||
},
|
||||
"description": "Execution flow control (optional, auto-inferred from depends_on if not provided)"
|
||||
},
|
||||
"focus_paths": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Key file paths affected by this plan (aggregated from tasks)"
|
||||
},
|
||||
"estimated_time": {
|
||||
"type": "string",
|
||||
"description": "Total estimated implementation time (e.g., '30 minutes', '2 hours')"
|
||||
},
|
||||
"recommended_execution": {
|
||||
"type": "string",
|
||||
"enum": ["Agent", "Codex"],
|
||||
"description": "Recommended execution method based on complexity"
|
||||
},
|
||||
"complexity": {
|
||||
"type": "string",
|
||||
"enum": ["Low", "Medium", "High"],
|
||||
"description": "Task complexity level"
|
||||
},
|
||||
"_metadata": {
|
||||
"type": "object",
|
||||
"required": ["timestamp", "source"],
|
||||
"properties": {
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of planning"
|
||||
},
|
||||
"source": {
|
||||
"type": "string",
|
||||
"enum": ["cli-lite-planning-agent", "direct-planning"],
|
||||
"description": "Planning source"
|
||||
},
|
||||
"planning_mode": {
|
||||
"type": "string",
|
||||
"enum": ["direct", "agent-based"],
|
||||
"description": "Planning execution mode"
|
||||
},
|
||||
"exploration_angles": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Exploration angles used for context"
|
||||
},
|
||||
"duration_seconds": {
|
||||
"type": "integer",
|
||||
"description": "Planning duration in seconds"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Plan Verification Agent Schema",
|
||||
"description": "Defines dimensions, severity rules, and CLI templates for plan verification agent",
|
||||
|
||||
"dimensions": {
|
||||
"A": { "name": "User Intent Alignment", "tier": 1, "severity": "CRITICAL",
|
||||
"checks": ["Goal Alignment", "Scope Drift", "Success Criteria Match", "Intent Conflicts"] },
|
||||
"B": { "name": "Requirements Coverage", "tier": 1, "severity": "CRITICAL",
|
||||
"checks": ["Orphaned Requirements", "Unmapped Tasks", "NFR Coverage Gaps"] },
|
||||
"C": { "name": "Consistency Validation", "tier": 1, "severity": "CRITICAL",
|
||||
"checks": ["Requirement Conflicts", "Architecture Drift", "Terminology Drift", "Data Model Inconsistency"] },
|
||||
"D": { "name": "Dependency Integrity", "tier": 2, "severity": "HIGH",
|
||||
"checks": ["Circular Dependencies", "Missing Dependencies", "Broken Dependencies", "Logical Ordering"] },
|
||||
"E": { "name": "Synthesis Alignment", "tier": 2, "severity": "HIGH",
|
||||
"checks": ["Priority Conflicts", "Success Criteria Mismatch", "Risk Mitigation Gaps"] },
|
||||
"F": { "name": "Task Specification Quality", "tier": 3, "severity": "MEDIUM",
|
||||
"checks": ["Ambiguous Focus Paths", "Underspecified Acceptance", "Missing Artifacts", "Weak Flow Control"] },
|
||||
"G": { "name": "Duplication Detection", "tier": 4, "severity": "LOW",
|
||||
"checks": ["Overlapping Task Scope", "Redundant Coverage"] },
|
||||
"H": { "name": "Feasibility Assessment", "tier": 4, "severity": "LOW",
|
||||
"checks": ["Complexity Misalignment", "Resource Conflicts", "Skill Gap Risks"] },
|
||||
"I": { "name": "Constraints Compliance", "tier": 1, "severity": "CRITICAL",
|
||||
"checks": ["Consolidated Constraints Violation", "Phase Constraint Ignored", "User Constraint Override"] },
|
||||
"J": { "name": "N+1 Context Validation", "tier": 2, "severity": "HIGH",
|
||||
"checks": ["Deferred Item Included", "Decision Contradiction", "Revisit Flag Ignored"] }
|
||||
},
|
||||
|
||||
"tiers": {
|
||||
"1": { "dimensions": ["A", "B", "C", "I"], "priority": "CRITICAL", "limit": null, "rule": "analysis-review-architecture" },
|
||||
"2": { "dimensions": ["D", "E", "J"], "priority": "HIGH", "limit": 15, "rule": "analysis-diagnose-bug-root-cause" },
|
||||
"3": { "dimensions": ["F"], "priority": "MEDIUM", "limit": 20, "rule": "analysis-analyze-code-patterns" },
|
||||
"4": { "dimensions": ["G", "H"], "priority": "LOW", "limit": 15, "rule": "analysis-analyze-code-patterns" }
|
||||
},
|
||||
|
||||
"severity_rules": {
|
||||
"CRITICAL": ["User intent violation", "Synthesis authority violation", "Zero coverage", "Circular/broken deps", "Constraint violation"],
|
||||
"HIGH": ["NFR gaps", "Priority conflicts", "Missing risk mitigation", "Deferred item included", "Decision contradiction"],
|
||||
"MEDIUM": ["Terminology drift", "Missing refs", "Weak flow control"],
|
||||
"LOW": ["Style improvements", "Minor redundancy"]
|
||||
},
|
||||
|
||||
"quality_gate": {
|
||||
"BLOCK_EXECUTION": { "condition": "critical > 0", "emoji": "🛑" },
|
||||
"PROCEED_WITH_FIXES": { "condition": "critical == 0 && high > 0", "emoji": "⚠️" },
|
||||
"PROCEED_WITH_CAUTION": { "condition": "critical == 0 && high == 0 && medium > 0", "emoji": "✅" },
|
||||
"PROCEED": { "condition": "only low or none", "emoji": "✅" }
|
||||
},
|
||||
|
||||
"token_budget": { "total_findings": 50, "early_exit": "CRITICAL > 0 in Tier 1 → skip Tier 3-4" }
|
||||
}
|
||||
@@ -0,0 +1,141 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Project Guidelines Schema",
|
||||
"description": "Schema for project-guidelines.json - user-maintained rules and constraints",
|
||||
"type": "object",
|
||||
"required": ["conventions", "constraints", "_metadata"],
|
||||
"properties": {
|
||||
"conventions": {
|
||||
"type": "object",
|
||||
"description": "Coding conventions and standards",
|
||||
"required": ["coding_style", "naming_patterns", "file_structure", "documentation"],
|
||||
"properties": {
|
||||
"coding_style": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Coding style rules (e.g., 'Use strict TypeScript mode', 'Prefer const over let')"
|
||||
},
|
||||
"naming_patterns": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Naming conventions (e.g., 'Use camelCase for variables', 'Use PascalCase for components')"
|
||||
},
|
||||
"file_structure": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "File organization rules (e.g., 'One component per file', 'Tests alongside source files')"
|
||||
},
|
||||
"documentation": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Documentation requirements (e.g., 'JSDoc for public APIs', 'README for each module')"
|
||||
}
|
||||
}
|
||||
},
|
||||
"constraints": {
|
||||
"type": "object",
|
||||
"description": "Technical constraints and boundaries",
|
||||
"required": ["architecture", "tech_stack", "performance", "security"],
|
||||
"properties": {
|
||||
"architecture": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Architecture constraints (e.g., 'No circular dependencies', 'Services must be stateless')"
|
||||
},
|
||||
"tech_stack": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Technology constraints (e.g., 'No new dependencies without review', 'Use native fetch over axios')"
|
||||
},
|
||||
"performance": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Performance requirements (e.g., 'API response < 200ms', 'Bundle size < 500KB')"
|
||||
},
|
||||
"security": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Security requirements (e.g., 'Sanitize all user input', 'No secrets in code')"
|
||||
}
|
||||
}
|
||||
},
|
||||
"quality_rules": {
|
||||
"type": "array",
|
||||
"description": "Enforceable quality rules",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["rule", "scope"],
|
||||
"properties": {
|
||||
"rule": {
|
||||
"type": "string",
|
||||
"description": "The quality rule statement"
|
||||
},
|
||||
"scope": {
|
||||
"type": "string",
|
||||
"description": "Where the rule applies (e.g., 'all', 'src/**', 'tests/**')"
|
||||
},
|
||||
"enforced_by": {
|
||||
"type": "string",
|
||||
"description": "How the rule is enforced (e.g., 'eslint', 'pre-commit', 'code-review')"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"learnings": {
|
||||
"type": "array",
|
||||
"description": "Project learnings captured from workflow sessions",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["date", "insight"],
|
||||
"properties": {
|
||||
"date": {
|
||||
"type": "string",
|
||||
"format": "date",
|
||||
"description": "Date the learning was captured (YYYY-MM-DD)"
|
||||
},
|
||||
"session_id": {
|
||||
"type": "string",
|
||||
"description": "WFS session ID where the learning originated"
|
||||
},
|
||||
"insight": {
|
||||
"type": "string",
|
||||
"description": "The learning or insight captured"
|
||||
},
|
||||
"context": {
|
||||
"type": "string",
|
||||
"description": "Additional context about when/why this learning applies"
|
||||
},
|
||||
"category": {
|
||||
"type": "string",
|
||||
"enum": ["architecture", "performance", "security", "testing", "workflow", "other"],
|
||||
"description": "Category of the learning"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"_metadata": {
|
||||
"type": "object",
|
||||
"required": ["created_at", "version"],
|
||||
"properties": {
|
||||
"created_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of creation"
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"description": "Schema version (e.g., '1.0.0')"
|
||||
},
|
||||
"last_updated": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of last update"
|
||||
},
|
||||
"updated_by": {
|
||||
"type": "string",
|
||||
"description": "Who/what last updated the file (e.g., 'user', 'workflow:session:solidify')"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
221
.ccw/workflows/cli-templates/schemas/project-tech-schema.json
Normal file
221
.ccw/workflows/cli-templates/schemas/project-tech-schema.json
Normal file
@@ -0,0 +1,221 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Project Tech Schema",
|
||||
"description": "Schema for project-tech.json - auto-generated technical analysis (stack, architecture, components)",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"project_name",
|
||||
"initialized_at",
|
||||
"overview",
|
||||
"features",
|
||||
"statistics",
|
||||
"_metadata"
|
||||
],
|
||||
"properties": {
|
||||
"project_name": {
|
||||
"type": "string",
|
||||
"description": "Project name extracted from git repo or directory"
|
||||
},
|
||||
"initialized_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of initialization"
|
||||
},
|
||||
"overview": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"description",
|
||||
"technology_stack",
|
||||
"architecture",
|
||||
"key_components"
|
||||
],
|
||||
"properties": {
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "Brief project description (e.g., 'TypeScript web application with React frontend')"
|
||||
},
|
||||
"technology_stack": {
|
||||
"type": "object",
|
||||
"required": ["languages", "frameworks", "build_tools", "test_frameworks"],
|
||||
"properties": {
|
||||
"languages": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["name", "file_count", "primary"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Language name (e.g., TypeScript, Python)"
|
||||
},
|
||||
"file_count": {
|
||||
"type": "integer",
|
||||
"description": "Number of source files in this language"
|
||||
},
|
||||
"primary": {
|
||||
"type": "boolean",
|
||||
"description": "True if this is the primary language"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"frameworks": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Detected frameworks (React, Express, Django, etc.)"
|
||||
},
|
||||
"build_tools": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Build tools and package managers (npm, cargo, maven, etc.)"
|
||||
},
|
||||
"test_frameworks": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Testing frameworks (jest, pytest, go test, etc.)"
|
||||
}
|
||||
}
|
||||
},
|
||||
"architecture": {
|
||||
"type": "object",
|
||||
"required": ["style", "layers", "patterns"],
|
||||
"properties": {
|
||||
"style": {
|
||||
"type": "string",
|
||||
"description": "Architecture style (MVC, microservices, layered, etc.)"
|
||||
},
|
||||
"layers": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Architectural layers (presentation, business-logic, data-access)"
|
||||
},
|
||||
"patterns": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Design patterns (Repository, Factory, Singleton, etc.)"
|
||||
}
|
||||
}
|
||||
},
|
||||
"key_components": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["name", "path", "description", "importance"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Component name"
|
||||
},
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Relative path to component directory"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "Brief description of component functionality"
|
||||
},
|
||||
"importance": {
|
||||
"type": "string",
|
||||
"enum": ["high", "medium", "low"],
|
||||
"description": "Component importance level"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "5-10 core modules/components"
|
||||
}
|
||||
}
|
||||
},
|
||||
"features": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["session_id", "title", "completed_at", "tags"],
|
||||
"properties": {
|
||||
"session_id": {
|
||||
"type": "string",
|
||||
"description": "WFS session identifier"
|
||||
},
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Feature title/description"
|
||||
},
|
||||
"completed_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of completion"
|
||||
},
|
||||
"tags": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Feature tags for categorization"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Completed workflow features (populated by /workflow:session:complete)"
|
||||
},
|
||||
"development_index": {
|
||||
"type": "object",
|
||||
"description": "Categorized development history (lite-plan/lite-execute)",
|
||||
"properties": {
|
||||
"feature": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } },
|
||||
"enhancement": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } },
|
||||
"bugfix": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } },
|
||||
"refactor": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } },
|
||||
"docs": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } }
|
||||
}
|
||||
},
|
||||
"statistics": {
|
||||
"type": "object",
|
||||
"required": ["total_features", "total_sessions", "last_updated"],
|
||||
"properties": {
|
||||
"total_features": {
|
||||
"type": "integer",
|
||||
"description": "Count of completed features"
|
||||
},
|
||||
"total_sessions": {
|
||||
"type": "integer",
|
||||
"description": "Count of workflow sessions"
|
||||
},
|
||||
"last_updated": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of last update"
|
||||
}
|
||||
}
|
||||
},
|
||||
"_metadata": {
|
||||
"type": "object",
|
||||
"required": ["initialized_by", "analysis_timestamp", "analysis_mode"],
|
||||
"properties": {
|
||||
"initialized_by": {
|
||||
"type": "string",
|
||||
"description": "Agent or tool that performed initialization"
|
||||
},
|
||||
"analysis_timestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of analysis"
|
||||
},
|
||||
"analysis_mode": {
|
||||
"type": "string",
|
||||
"enum": ["deep-scan", "quick-scan", "bash-fallback"],
|
||||
"description": "Analysis mode used"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"devIndexEntry": {
|
||||
"type": "object",
|
||||
"required": ["title", "sub_feature", "date", "description", "status"],
|
||||
"properties": {
|
||||
"title": { "type": "string", "maxLength": 60 },
|
||||
"sub_feature": { "type": "string", "description": "Module/component area" },
|
||||
"date": { "type": "string", "format": "date" },
|
||||
"description": { "type": "string", "maxLength": 100 },
|
||||
"status": { "type": "string", "enum": ["completed", "partial"] },
|
||||
"session_id": { "type": "string", "description": "lite-plan session ID" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
248
.ccw/workflows/cli-templates/schemas/queue-schema.json
Normal file
248
.ccw/workflows/cli-templates/schemas/queue-schema.json
Normal file
@@ -0,0 +1,248 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Issue Execution Queue Schema",
|
||||
"description": "Execution queue supporting both task-level (T-N) and solution-level (S-N) granularity",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^QUE-[0-9]{8}-[0-9]{6}$",
|
||||
"description": "Queue ID in format QUE-YYYYMMDD-HHMMSS"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["active", "paused", "completed", "archived"],
|
||||
"default": "active"
|
||||
},
|
||||
"issue_ids": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Issues included in this queue"
|
||||
},
|
||||
"solutions": {
|
||||
"type": "array",
|
||||
"description": "Solution-level queue items (preferred for new queues)",
|
||||
"items": {
|
||||
"$ref": "#/definitions/solutionItem"
|
||||
}
|
||||
},
|
||||
"tasks": {
|
||||
"type": "array",
|
||||
"description": "Task-level queue items (legacy format)",
|
||||
"items": {
|
||||
"$ref": "#/definitions/taskItem"
|
||||
}
|
||||
},
|
||||
"conflicts": {
|
||||
"type": "array",
|
||||
"description": "Detected conflicts between items",
|
||||
"items": {
|
||||
"$ref": "#/definitions/conflict"
|
||||
}
|
||||
},
|
||||
"execution_groups": {
|
||||
"type": "array",
|
||||
"description": "Parallel/Sequential execution groups",
|
||||
"items": {
|
||||
"$ref": "#/definitions/executionGroup"
|
||||
}
|
||||
},
|
||||
"_metadata": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"version": { "type": "string", "default": "2.0" },
|
||||
"queue_type": {
|
||||
"type": "string",
|
||||
"enum": ["solution", "task"],
|
||||
"description": "Queue granularity level"
|
||||
},
|
||||
"total_solutions": { "type": "integer" },
|
||||
"total_tasks": { "type": "integer" },
|
||||
"pending_count": { "type": "integer" },
|
||||
"ready_count": { "type": "integer" },
|
||||
"executing_count": { "type": "integer" },
|
||||
"completed_count": { "type": "integer" },
|
||||
"failed_count": { "type": "integer" },
|
||||
"last_queue_formation": { "type": "string", "format": "date-time" },
|
||||
"last_updated": { "type": "string", "format": "date-time" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"solutionItem": {
|
||||
"type": "object",
|
||||
"required": ["item_id", "issue_id", "solution_id", "status", "task_count", "files_touched"],
|
||||
"properties": {
|
||||
"item_id": {
|
||||
"type": "string",
|
||||
"pattern": "^S-[0-9]+$",
|
||||
"description": "Solution-level queue item ID (S-1, S-2, ...)"
|
||||
},
|
||||
"issue_id": {
|
||||
"type": "string",
|
||||
"description": "Source issue ID"
|
||||
},
|
||||
"solution_id": {
|
||||
"type": "string",
|
||||
"description": "Bound solution ID"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["pending", "ready", "executing", "completed", "failed", "blocked"],
|
||||
"default": "pending"
|
||||
},
|
||||
"task_count": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"description": "Number of tasks in this solution"
|
||||
},
|
||||
"files_touched": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "All files modified by this solution"
|
||||
},
|
||||
"execution_order": {
|
||||
"type": "integer",
|
||||
"description": "Order in execution sequence"
|
||||
},
|
||||
"execution_group": {
|
||||
"type": "string",
|
||||
"description": "Parallel (P*) or Sequential (S*) group ID"
|
||||
},
|
||||
"depends_on": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Solution IDs this item depends on"
|
||||
},
|
||||
"semantic_priority": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"description": "Semantic importance score (0.0-1.0)"
|
||||
},
|
||||
"queued_at": { "type": "string", "format": "date-time" },
|
||||
"started_at": { "type": "string", "format": "date-time" },
|
||||
"completed_at": { "type": "string", "format": "date-time" },
|
||||
"result": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"summary": { "type": "string" },
|
||||
"files_modified": { "type": "array", "items": { "type": "string" } },
|
||||
"tasks_completed": { "type": "integer" },
|
||||
"commit_hashes": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
},
|
||||
"failure_reason": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"taskItem": {
|
||||
"type": "object",
|
||||
"required": ["item_id", "issue_id", "solution_id", "task_id", "status"],
|
||||
"properties": {
|
||||
"item_id": {
|
||||
"type": "string",
|
||||
"pattern": "^T-[0-9]+$",
|
||||
"description": "Task-level queue item ID (T-1, T-2, ...)"
|
||||
},
|
||||
"issue_id": { "type": "string" },
|
||||
"solution_id": { "type": "string" },
|
||||
"task_id": { "type": "string" },
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["pending", "ready", "executing", "completed", "failed", "blocked"],
|
||||
"default": "pending"
|
||||
},
|
||||
"execution_order": { "type": "integer" },
|
||||
"execution_group": { "type": "string" },
|
||||
"depends_on": { "type": "array", "items": { "type": "string" } },
|
||||
"semantic_priority": { "type": "number", "minimum": 0, "maximum": 1 },
|
||||
"queued_at": { "type": "string", "format": "date-time" },
|
||||
"started_at": { "type": "string", "format": "date-time" },
|
||||
"completed_at": { "type": "string", "format": "date-time" },
|
||||
"result": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"files_modified": { "type": "array", "items": { "type": "string" } },
|
||||
"files_created": { "type": "array", "items": { "type": "string" } },
|
||||
"summary": { "type": "string" },
|
||||
"commit_hash": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"failure_reason": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"conflict": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["file_conflict", "dependency_conflict", "resource_conflict"]
|
||||
},
|
||||
"file": {
|
||||
"type": "string",
|
||||
"description": "Conflicting file path"
|
||||
},
|
||||
"solutions": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Solution IDs involved (for solution-level queues)"
|
||||
},
|
||||
"tasks": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Task IDs involved (for task-level queues)"
|
||||
},
|
||||
"resolution": {
|
||||
"type": "string",
|
||||
"enum": ["sequential", "merge", "manual"]
|
||||
},
|
||||
"resolution_order": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Execution order to resolve conflict"
|
||||
},
|
||||
"rationale": {
|
||||
"type": "string",
|
||||
"description": "Explanation of resolution decision"
|
||||
},
|
||||
"resolved": {
|
||||
"type": "boolean",
|
||||
"default": false
|
||||
}
|
||||
}
|
||||
},
|
||||
"executionGroup": {
|
||||
"type": "object",
|
||||
"required": ["id", "type"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^[PS][0-9]+$",
|
||||
"description": "Group ID (P1, P2 for parallel, S1, S2 for sequential)"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["parallel", "sequential"]
|
||||
},
|
||||
"solutions": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Solution IDs in this group"
|
||||
},
|
||||
"tasks": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Task IDs in this group (legacy)"
|
||||
},
|
||||
"solution_count": {
|
||||
"type": "integer",
|
||||
"description": "Number of solutions in group"
|
||||
},
|
||||
"task_count": {
|
||||
"type": "integer",
|
||||
"description": "Number of tasks in group (legacy)"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
94
.ccw/workflows/cli-templates/schemas/registry-schema.json
Normal file
94
.ccw/workflows/cli-templates/schemas/registry-schema.json
Normal file
@@ -0,0 +1,94 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Issue Registry Schema",
|
||||
"description": "Global registry of all issues and their solutions",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"issues": {
|
||||
"type": "array",
|
||||
"description": "List of registered issues",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["id", "title", "status", "created_at"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Issue ID (e.g., GH-123, TEXT-xxx)"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["registered", "planning", "planned", "queued", "executing", "completed", "failed", "paused"],
|
||||
"default": "registered"
|
||||
},
|
||||
"priority": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 5,
|
||||
"default": 3
|
||||
},
|
||||
"solution_count": {
|
||||
"type": "integer",
|
||||
"default": 0,
|
||||
"description": "Number of candidate solutions"
|
||||
},
|
||||
"bound_solution_id": {
|
||||
"type": "string",
|
||||
"description": "ID of the bound solution (null if none bound)"
|
||||
},
|
||||
"source": {
|
||||
"type": "string",
|
||||
"enum": ["github", "text", "file"],
|
||||
"description": "Source of the issue"
|
||||
},
|
||||
"source_url": {
|
||||
"type": "string",
|
||||
"description": "Original source URL (for GitHub issues)"
|
||||
},
|
||||
"created_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"updated_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"planned_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"queued_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"completed_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"_metadata": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"version": { "type": "string", "default": "1.0" },
|
||||
"total_issues": { "type": "integer" },
|
||||
"by_status": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"registered": { "type": "integer" },
|
||||
"planning": { "type": "integer" },
|
||||
"planned": { "type": "integer" },
|
||||
"queued": { "type": "integer" },
|
||||
"executing": { "type": "integer" },
|
||||
"completed": { "type": "integer" },
|
||||
"failed": { "type": "integer" }
|
||||
}
|
||||
},
|
||||
"last_updated": { "type": "string", "format": "date-time" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,82 @@
|
||||
[
|
||||
{
|
||||
"finding_id": "sec-001-a1b2c3d4",
|
||||
"original_dimension": "security",
|
||||
"iteration": 1,
|
||||
"analysis_timestamp": "2025-01-25T14:40:15Z",
|
||||
"cli_tool_used": "gemini",
|
||||
"root_cause": {
|
||||
"summary": "Legacy code from v1 migration, pre-ORM implementation",
|
||||
"details": "Query builder was ported from old codebase without security review. Team unaware of injection risks in string concatenation pattern. Code review at migration time focused on functionality, not security.",
|
||||
"affected_scope": "All query-builder.ts methods using string template literals (15 methods total)",
|
||||
"similar_patterns": [
|
||||
"src/database/user-queries.ts:buildEmailQuery",
|
||||
"src/database/order-queries.ts:buildOrderSearch"
|
||||
]
|
||||
},
|
||||
"remediation_plan": {
|
||||
"approach": "Migrate to ORM prepared statements with input validation layer",
|
||||
"priority": "P0 - Critical (security vulnerability)",
|
||||
"estimated_effort": "4 hours development + 2 hours testing",
|
||||
"risk_level": "low",
|
||||
"steps": [
|
||||
{
|
||||
"step": 1,
|
||||
"action": "Replace direct string concatenation with ORM query builder",
|
||||
"files": ["src/database/query-builder.ts:buildUserQuery:140-150"],
|
||||
"commands": [
|
||||
"Replace: const query = `SELECT * FROM users WHERE id = ${userId}`;",
|
||||
"With: return db('users').where('id', userId).first();"
|
||||
],
|
||||
"rationale": "ORM automatically parameterizes queries, eliminating injection risk",
|
||||
"validation": "Run: npm test -- src/database/query-builder.test.ts"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"action": "Add input validation layer before ORM",
|
||||
"files": ["src/database/validators.ts:validateUserId:NEW"],
|
||||
"commands": [
|
||||
"Create validator: export function validateUserId(id: unknown): number { ... }",
|
||||
"Add schema: z.number().positive().int()"
|
||||
],
|
||||
"rationale": "Defense in depth - validate types and ranges before database layer",
|
||||
"validation": "Run: npm test -- src/database/validators.test.ts"
|
||||
},
|
||||
{
|
||||
"step": 3,
|
||||
"action": "Apply pattern to all 15 similar methods",
|
||||
"files": ["src/database/query-builder.ts:ALL_METHODS"],
|
||||
"commands": ["Bulk replace string templates with ORM syntax"],
|
||||
"rationale": "Prevent similar vulnerabilities in other query methods",
|
||||
"validation": "Run: npm test -- src/database/"
|
||||
}
|
||||
],
|
||||
"rollback_strategy": "Git commit before each step, revert if tests fail. Staged rollout: dev → staging → production with monitoring."
|
||||
},
|
||||
"impact_assessment": {
|
||||
"files_affected": [
|
||||
"src/database/query-builder.ts (modify)",
|
||||
"src/database/validators.ts (new)",
|
||||
"src/database/user-queries.ts (modify)",
|
||||
"src/database/order-queries.ts (modify)"
|
||||
],
|
||||
"tests_required": [
|
||||
"src/database/query-builder.test.ts (update existing)",
|
||||
"src/database/validators.test.ts (new)",
|
||||
"integration/security/sql-injection.test.ts (new)"
|
||||
],
|
||||
"breaking_changes": false,
|
||||
"dependencies_updated": ["knex@2.5.1 (ORM library)"],
|
||||
"deployment_notes": "No downtime required. Database migrations not needed."
|
||||
},
|
||||
"reassessed_severity": "high",
|
||||
"severity_change_reason": "Found existing WAF rules partially mitigate risk in production. Input validation at API gateway layer provides additional defense. Downgrade from critical to high, but still requires immediate fix.",
|
||||
"confidence_score": 0.95,
|
||||
"references": [
|
||||
"Project ORM migration guide: docs/architecture/orm-guide.md",
|
||||
"Knex.js parameterization: https://knexjs.org/guide/query-builder.html#where",
|
||||
"Similar incident: TICKET-1234 (previous SQL injection fix)"
|
||||
],
|
||||
"status": "remediation_plan_ready"
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,51 @@
|
||||
[
|
||||
{
|
||||
"dimension": "security",
|
||||
"review_id": "review-20250125-143022",
|
||||
"analysis_timestamp": "2025-01-25T14:30:22Z",
|
||||
"cli_tool_used": "gemini",
|
||||
"model": "gemini-2.5-pro",
|
||||
"analysis_duration_ms": 2145000,
|
||||
"summary": {
|
||||
"total_findings": 15,
|
||||
"critical": 2,
|
||||
"high": 4,
|
||||
"medium": 6,
|
||||
"low": 3,
|
||||
"files_analyzed": 47,
|
||||
"lines_reviewed": 8932
|
||||
},
|
||||
"findings": [
|
||||
{
|
||||
"id": "sec-001-a1b2c3d4",
|
||||
"title": "SQL Injection vulnerability in user query",
|
||||
"severity": "critical",
|
||||
"category": "injection",
|
||||
"description": "Direct string concatenation in SQL query allows injection attacks. User input is not sanitized before query execution.",
|
||||
"file": "src/database/query-builder.ts",
|
||||
"line": 145,
|
||||
"snippet": "const query = `SELECT * FROM users WHERE id = ${userId}`;",
|
||||
"recommendation": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [userId])",
|
||||
"references": [
|
||||
"OWASP Top 10 - A03:2021 Injection",
|
||||
"https://owasp.org/www-community/attacks/SQL_Injection"
|
||||
],
|
||||
"impact": "Potential data breach, unauthorized access to user records, data manipulation",
|
||||
"metadata": {
|
||||
"cwe_id": "CWE-89",
|
||||
"owasp_category": "A03:2021-Injection"
|
||||
},
|
||||
"iteration": 0,
|
||||
"status": "pending_remediation",
|
||||
"cross_references": []
|
||||
}
|
||||
],
|
||||
"cross_references": [
|
||||
{
|
||||
"finding_id": "sec-001-a1b2c3d4",
|
||||
"related_dimensions": ["quality", "architecture"],
|
||||
"reason": "Same file flagged in multiple dimensions"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
166
.ccw/workflows/cli-templates/schemas/solution-schema.json
Normal file
166
.ccw/workflows/cli-templates/schemas/solution-schema.json
Normal file
@@ -0,0 +1,166 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Issue Solution Schema",
|
||||
"description": "Schema for solution registered to an issue",
|
||||
"type": "object",
|
||||
"required": ["id", "tasks", "is_bound", "created_at"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Unique solution identifier: SOL-{issue-id}-{4-char-uid} where uid is 4 alphanumeric chars",
|
||||
"pattern": "^SOL-.+-[a-z0-9]{4}$",
|
||||
"examples": ["SOL-GH-123-a7x9", "SOL-ISS-20251229-001-b2k4"]
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "High-level summary of the solution"
|
||||
},
|
||||
"approach": {
|
||||
"type": "string",
|
||||
"description": "Technical approach or strategy"
|
||||
},
|
||||
"tasks": {
|
||||
"type": "array",
|
||||
"description": "Task breakdown for this solution",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["id", "title", "scope", "action", "implementation", "acceptance"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^T[0-9]+$"
|
||||
},
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Action verb + target"
|
||||
},
|
||||
"scope": {
|
||||
"type": "string",
|
||||
"description": "Module path or feature area"
|
||||
},
|
||||
"action": {
|
||||
"type": "string",
|
||||
"enum": ["Create", "Update", "Implement", "Refactor", "Add", "Delete", "Configure", "Test", "Fix"]
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "1-2 sentences describing what to implement"
|
||||
},
|
||||
"modification_points": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"file": { "type": "string" },
|
||||
"target": { "type": "string" },
|
||||
"change": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"implementation": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Step-by-step implementation guide"
|
||||
},
|
||||
"test": {
|
||||
"type": "object",
|
||||
"description": "Test requirements",
|
||||
"properties": {
|
||||
"unit": { "type": "array", "items": { "type": "string" } },
|
||||
"integration": { "type": "array", "items": { "type": "string" } },
|
||||
"commands": { "type": "array", "items": { "type": "string" } },
|
||||
"coverage_target": { "type": "number" }
|
||||
}
|
||||
},
|
||||
"regression": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Regression check points"
|
||||
},
|
||||
"acceptance": {
|
||||
"type": "object",
|
||||
"description": "Acceptance criteria & verification",
|
||||
"required": ["criteria", "verification"],
|
||||
"properties": {
|
||||
"criteria": { "type": "array", "items": { "type": "string" } },
|
||||
"verification": { "type": "array", "items": { "type": "string" } },
|
||||
"manual_checks": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
},
|
||||
"commit": {
|
||||
"type": "object",
|
||||
"description": "Commit specification",
|
||||
"properties": {
|
||||
"type": { "type": "string", "enum": ["feat", "fix", "refactor", "test", "docs", "chore"] },
|
||||
"scope": { "type": "string" },
|
||||
"message_template": { "type": "string" },
|
||||
"breaking": { "type": "boolean" }
|
||||
}
|
||||
},
|
||||
"depends_on": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"default": [],
|
||||
"description": "Task IDs this task depends on"
|
||||
},
|
||||
"estimated_minutes": {
|
||||
"type": "integer",
|
||||
"description": "Estimated time to complete"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"description": "Task status (optional, for tracking)"
|
||||
},
|
||||
"priority": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 5,
|
||||
"default": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"exploration_context": {
|
||||
"type": "object",
|
||||
"description": "ACE exploration results",
|
||||
"properties": {
|
||||
"project_structure": { "type": "string" },
|
||||
"relevant_files": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"patterns": { "type": "string" },
|
||||
"integration_points": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"analysis": {
|
||||
"type": "object",
|
||||
"description": "Solution risk assessment",
|
||||
"properties": {
|
||||
"risk": { "type": "string", "enum": ["low", "medium", "high"] },
|
||||
"impact": { "type": "string", "enum": ["low", "medium", "high"] },
|
||||
"complexity": { "type": "string", "enum": ["low", "medium", "high"] }
|
||||
}
|
||||
},
|
||||
"score": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"description": "Solution quality score (0.0-1.0)"
|
||||
},
|
||||
"is_bound": {
|
||||
"type": "boolean",
|
||||
"default": false,
|
||||
"description": "Whether this solution is bound to the issue"
|
||||
},
|
||||
"created_at": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"bound_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "When this solution was bound to the issue"
|
||||
}
|
||||
}
|
||||
}
|
||||
158
.ccw/workflows/cli-templates/schemas/verify-json-schema.json
Normal file
158
.ccw/workflows/cli-templates/schemas/verify-json-schema.json
Normal file
@@ -0,0 +1,158 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Plan Verification Findings Schema",
|
||||
"description": "Schema for plan verification findings output from cli-explore-agent",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"session_id",
|
||||
"timestamp",
|
||||
"verification_tiers_completed",
|
||||
"findings",
|
||||
"summary"
|
||||
],
|
||||
"properties": {
|
||||
"session_id": {
|
||||
"type": "string",
|
||||
"description": "Workflow session ID (e.g., WFS-20250127-143000)",
|
||||
"pattern": "^WFS-[0-9]{8}-[0-9]{6}$"
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"description": "ISO 8601 timestamp when verification was completed",
|
||||
"format": "date-time"
|
||||
},
|
||||
"verification_tiers_completed": {
|
||||
"type": "array",
|
||||
"description": "List of verification tiers completed (e.g., ['Tier 1', 'Tier 2'])",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"enum": ["Tier 1", "Tier 2", "Tier 3", "Tier 4"]
|
||||
},
|
||||
"minItems": 1,
|
||||
"maxItems": 4
|
||||
},
|
||||
"findings": {
|
||||
"type": "array",
|
||||
"description": "Array of all findings across all dimensions",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"dimension",
|
||||
"dimension_name",
|
||||
"severity",
|
||||
"location",
|
||||
"summary",
|
||||
"recommendation"
|
||||
],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Unique finding ID prefixed by severity (C1, H1, M1, L1)",
|
||||
"pattern": "^[CHML][0-9]+$"
|
||||
},
|
||||
"dimension": {
|
||||
"type": "string",
|
||||
"description": "Verification dimension identifier",
|
||||
"enum": ["A", "B", "C", "D", "E", "F", "G", "H"]
|
||||
},
|
||||
"dimension_name": {
|
||||
"type": "string",
|
||||
"description": "Human-readable dimension name",
|
||||
"enum": [
|
||||
"User Intent Alignment",
|
||||
"Requirements Coverage Analysis",
|
||||
"Consistency Validation",
|
||||
"Dependency Integrity",
|
||||
"Synthesis Alignment",
|
||||
"Task Specification Quality",
|
||||
"Duplication Detection",
|
||||
"Feasibility Assessment"
|
||||
]
|
||||
},
|
||||
"severity": {
|
||||
"type": "string",
|
||||
"description": "Severity level of the finding",
|
||||
"enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"]
|
||||
},
|
||||
"location": {
|
||||
"type": "array",
|
||||
"description": "Array of locations where issue was found (e.g., 'IMPL_PLAN.md:L45', 'task:IMPL-1.2', 'synthesis:FR-03')",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"minItems": 1
|
||||
},
|
||||
"summary": {
|
||||
"type": "string",
|
||||
"description": "Concise summary of the issue (1-2 sentences)",
|
||||
"minLength": 10,
|
||||
"maxLength": 500
|
||||
},
|
||||
"recommendation": {
|
||||
"type": "string",
|
||||
"description": "Actionable recommendation to resolve the issue",
|
||||
"minLength": 10,
|
||||
"maxLength": 500
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"summary": {
|
||||
"type": "object",
|
||||
"description": "Aggregate summary of verification results",
|
||||
"required": [
|
||||
"critical_count",
|
||||
"high_count",
|
||||
"medium_count",
|
||||
"low_count",
|
||||
"total_findings",
|
||||
"coverage_percentage",
|
||||
"recommendation"
|
||||
],
|
||||
"properties": {
|
||||
"critical_count": {
|
||||
"type": "integer",
|
||||
"description": "Number of critical severity findings",
|
||||
"minimum": 0
|
||||
},
|
||||
"high_count": {
|
||||
"type": "integer",
|
||||
"description": "Number of high severity findings",
|
||||
"minimum": 0
|
||||
},
|
||||
"medium_count": {
|
||||
"type": "integer",
|
||||
"description": "Number of medium severity findings",
|
||||
"minimum": 0
|
||||
},
|
||||
"low_count": {
|
||||
"type": "integer",
|
||||
"description": "Number of low severity findings",
|
||||
"minimum": 0
|
||||
},
|
||||
"total_findings": {
|
||||
"type": "integer",
|
||||
"description": "Total number of findings",
|
||||
"minimum": 0
|
||||
},
|
||||
"coverage_percentage": {
|
||||
"type": "number",
|
||||
"description": "Percentage of synthesis requirements covered by tasks (0-100)",
|
||||
"minimum": 0,
|
||||
"maximum": 100
|
||||
},
|
||||
"recommendation": {
|
||||
"type": "string",
|
||||
"description": "Quality gate recommendation",
|
||||
"enum": [
|
||||
"BLOCK_EXECUTION",
|
||||
"PROCEED_WITH_FIXES",
|
||||
"PROCEED_WITH_CAUTION",
|
||||
"PROCEED"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
91
.ccw/workflows/cli-templates/tech-stacks/go-dev.md
Normal file
91
.ccw/workflows/cli-templates/tech-stacks/go-dev.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
name: go-dev
|
||||
description: Go core development principles for clean, efficient, and idiomatic code
|
||||
---
|
||||
|
||||
# Go Development Guidelines
|
||||
|
||||
You are now operating under Go core development principles. Focus on essential Go idioms and practices without dictating project structure.
|
||||
|
||||
## Core Go Principles
|
||||
|
||||
### Essential Language Guidelines
|
||||
- **Simplicity**: Write simple, readable code over clever solutions
|
||||
- **Naming**: Use clear, descriptive names following Go conventions
|
||||
- **Error Handling**: Handle errors explicitly, don't ignore them
|
||||
- **Interfaces**: Keep interfaces small and focused
|
||||
|
||||
```go
|
||||
// Core principle: Clear error handling
|
||||
func GetUser(id string) (*User, error) {
|
||||
if id == "" {
|
||||
return nil, errors.New("user ID cannot be empty")
|
||||
}
|
||||
|
||||
user, err := database.FindUser(id)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to get user %s: %w", id, err)
|
||||
}
|
||||
|
||||
return user, nil
|
||||
}
|
||||
|
||||
// Core principle: Small, focused interfaces
|
||||
type UserReader interface {
|
||||
GetUser(id string) (*User, error)
|
||||
}
|
||||
```
|
||||
|
||||
## Idiomatic Go Patterns
|
||||
- **Zero Values**: Design types to be useful in their zero state
|
||||
- **Receiver Types**: Use pointer receivers for methods that modify the receiver
|
||||
- **Package Names**: Use short, clear package names without underscores
|
||||
- **Goroutines**: Use goroutines and channels for concurrent operations
|
||||
|
||||
## Essential Error Handling
|
||||
- **Explicit Errors**: Always handle errors explicitly
|
||||
- **Error Wrapping**: Use `fmt.Errorf` with `%w` verb to wrap errors
|
||||
- **Custom Errors**: Create specific error types when appropriate
|
||||
- **Early Returns**: Use early returns to avoid deep nesting
|
||||
|
||||
```go
|
||||
// Core principle: Error wrapping and context
|
||||
func ProcessUserData(userID string) error {
|
||||
user, err := GetUser(userID)
|
||||
if err != nil {
|
||||
return fmt.Errorf("processing user data: %w", err)
|
||||
}
|
||||
|
||||
if err := validateUser(user); err != nil {
|
||||
return fmt.Errorf("user validation failed: %w", err)
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
## Concurrency Guidelines
|
||||
- **Channel Communication**: Use channels to communicate between goroutines
|
||||
- **Context**: Use context.Context for cancellation and timeouts
|
||||
- **Worker Pools**: Implement worker pools for bounded concurrency
|
||||
- **Race Detection**: Run tests with `-race` flag regularly
|
||||
|
||||
## Testing Essentials
|
||||
- **Table-Driven Tests**: Use table-driven tests for multiple test cases
|
||||
- **Test Names**: Use descriptive test function names
|
||||
- **Mocking**: Use interfaces for dependency injection and mocking
|
||||
- **Benchmarks**: Write benchmarks for performance-critical code
|
||||
|
||||
## Performance Guidelines
|
||||
- **Profiling**: Use Go's built-in profiling tools
|
||||
- **Memory Management**: Understand Go's garbage collector behavior
|
||||
- **Slice/Map Operations**: Be aware of capacity vs length for slices
|
||||
- **String Operations**: Use strings.Builder for efficient string concatenation
|
||||
|
||||
## Code Quality Essentials
|
||||
- **Go fmt**: Always format code with `gofmt` or `goimports`
|
||||
- **Go vet**: Run `go vet` to catch common mistakes
|
||||
- **Linting**: Use golangci-lint for comprehensive code analysis
|
||||
- **Documentation**: Write clear package and function documentation
|
||||
|
||||
Apply these core Go principles to write clean, efficient, and maintainable Go code following language idioms and best practices.
|
||||
107
.ccw/workflows/cli-templates/tech-stacks/java-dev.md
Normal file
107
.ccw/workflows/cli-templates/tech-stacks/java-dev.md
Normal file
@@ -0,0 +1,107 @@
|
||||
---
|
||||
name: java-dev
|
||||
description: Java core development principles for robust, maintainable enterprise applications
|
||||
---
|
||||
|
||||
# Java Development Guidelines
|
||||
|
||||
You are now operating under Java core development principles. Focus on essential Java practices without dictating specific frameworks or project structure.
|
||||
|
||||
## Core Java Principles
|
||||
|
||||
### Essential Language Guidelines
|
||||
- **Object-Oriented Design**: Use proper encapsulation, inheritance, and polymorphism
|
||||
- **Naming Conventions**: Follow Java naming standards (camelCase, PascalCase)
|
||||
- **Immutability**: Favor immutable objects when possible
|
||||
- **Exception Handling**: Use specific exceptions and proper exception handling
|
||||
|
||||
```java
|
||||
// Core principle: Proper exception handling and immutability
|
||||
public final class User {
|
||||
private final String id;
|
||||
private final String name;
|
||||
private final String email;
|
||||
|
||||
public User(String id, String name, String email) {
|
||||
this.id = Objects.requireNonNull(id, "User ID cannot be null");
|
||||
this.name = Objects.requireNonNull(name, "Name cannot be null");
|
||||
this.email = Objects.requireNonNull(email, "Email cannot be null");
|
||||
}
|
||||
|
||||
public String getId() { return id; }
|
||||
public String getName() { return name; }
|
||||
public String getEmail() { return email; }
|
||||
}
|
||||
|
||||
// Core principle: Specific exceptions
|
||||
public class UserNotFoundException extends Exception {
|
||||
public UserNotFoundException(String message) {
|
||||
super(message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Essential Object-Oriented Patterns
|
||||
- **Single Responsibility**: Each class should have one reason to change
|
||||
- **Dependency Injection**: Use constructor injection for required dependencies
|
||||
- **Interface Segregation**: Keep interfaces focused and minimal
|
||||
- **Composition over Inheritance**: Favor composition for flexibility
|
||||
|
||||
## Error Handling Essentials
|
||||
- **Checked vs Unchecked**: Use checked exceptions for recoverable conditions
|
||||
- **Exception Hierarchy**: Create meaningful exception hierarchies
|
||||
- **Resource Management**: Use try-with-resources for automatic resource cleanup
|
||||
- **Logging**: Log exceptions appropriately with context
|
||||
|
||||
```java
|
||||
// Core principle: Resource management and exception handling
|
||||
public class UserService {
|
||||
private final UserRepository userRepository;
|
||||
|
||||
public UserService(UserRepository userRepository) {
|
||||
this.userRepository = Objects.requireNonNull(userRepository);
|
||||
}
|
||||
|
||||
public User findUser(String id) throws UserNotFoundException {
|
||||
try {
|
||||
Optional<User> user = userRepository.findById(id);
|
||||
return user.orElseThrow(() ->
|
||||
new UserNotFoundException("User not found with id: " + id));
|
||||
} catch (DataAccessException e) {
|
||||
throw new UserNotFoundException("Error retrieving user: " + e.getMessage(), e);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Modern Java Features
|
||||
- **Optional**: Use Optional to handle null values safely
|
||||
- **Streams**: Use streams for data processing and filtering
|
||||
- **Lambda Expressions**: Use lambdas for functional programming patterns
|
||||
- **Records**: Use records for simple data carriers (Java 14+)
|
||||
|
||||
## Testing Essentials
|
||||
- **Unit Tests**: Use JUnit 5 for unit testing
|
||||
- **Test Organization**: Follow Given-When-Then or Arrange-Act-Assert patterns
|
||||
- **Mocking**: Use Mockito for mocking dependencies
|
||||
- **Integration Tests**: Test component interactions properly
|
||||
|
||||
## Performance Guidelines
|
||||
- **String Handling**: Use StringBuilder for string concatenation in loops
|
||||
- **Collection Choice**: Choose appropriate collection types for use cases
|
||||
- **Memory Management**: Understand garbage collection behavior
|
||||
- **Profiling**: Use profiling tools to identify performance bottlenecks
|
||||
|
||||
## Concurrency Guidelines
|
||||
- **Thread Safety**: Design for thread safety when needed
|
||||
- **Concurrent Collections**: Use concurrent collections appropriately
|
||||
- **ExecutorService**: Use thread pools instead of creating threads manually
|
||||
- **Synchronization**: Use proper synchronization mechanisms
|
||||
|
||||
## Code Quality Essentials
|
||||
- **Code Formatting**: Use consistent code formatting and style
|
||||
- **Static Analysis**: Use tools like SpotBugs, PMD, and Checkstyle
|
||||
- **Documentation**: Write clear Javadoc for public APIs
|
||||
- **Clean Code**: Follow clean code principles and naming conventions
|
||||
|
||||
Apply these core Java principles to write robust, maintainable, and efficient Java applications following language best practices and modern Java idioms.
|
||||
58
.ccw/workflows/cli-templates/tech-stacks/javascript-dev.md
Normal file
58
.ccw/workflows/cli-templates/tech-stacks/javascript-dev.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: javascript-dev
|
||||
description: JavaScript and Node.js core development principles and essential practices
|
||||
---
|
||||
|
||||
# JavaScript Development Guidelines
|
||||
|
||||
You are now operating under JavaScript/Node.js core development principles. Focus on essential practices without dictating project structure.
|
||||
|
||||
## Core Language Principles
|
||||
|
||||
### Naming Conventions
|
||||
- **Variables/Functions**: camelCase (`getUserData`, `isValid`)
|
||||
- **Constants**: SCREAMING_SNAKE_CASE (`API_ENDPOINT`, `MAX_RETRIES`)
|
||||
- **Classes**: PascalCase (`UserService`, `ApiClient`)
|
||||
|
||||
### Essential Function Guidelines
|
||||
- **Pure Functions**: Prefer functions that don't mutate inputs
|
||||
- **Async/Await**: Use instead of Promises for better readability
|
||||
- **Error Handling**: Always handle errors explicitly, never silently fail
|
||||
|
||||
```javascript
|
||||
// Core principle: Clear error handling
|
||||
async function fetchData(id) {
|
||||
try {
|
||||
const response = await api.get(`/data/${id}`);
|
||||
return response.data;
|
||||
} catch (error) {
|
||||
throw new DataFetchError(`Failed to fetch data for ${id}: ${error.message}`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Essential Testing Practices
|
||||
- **Test Names**: Describe behavior clearly (`should return user when ID exists`)
|
||||
- **Arrange-Act-Assert**: Structure tests consistently
|
||||
- **Mock External Dependencies**: Isolate units under test
|
||||
- **Test Edge Cases**: Include error conditions and boundary values
|
||||
|
||||
## Code Quality Essentials
|
||||
- **Consistent Formatting**: Use automated formatting (Prettier)
|
||||
- **Linting**: Catch common errors early (ESLint)
|
||||
- **Type Safety**: Consider TypeScript for larger projects
|
||||
- **Input Validation**: Validate all external inputs
|
||||
|
||||
## Security Core Principles
|
||||
- **Input Sanitization**: Never trust user input
|
||||
- **Environment Variables**: Keep secrets out of code
|
||||
- **Dependency Management**: Regularly audit and update packages
|
||||
- **Error Messages**: Don't expose internal details to users
|
||||
|
||||
## Performance Guidelines
|
||||
- **Avoid Premature Optimization**: Write clear code first
|
||||
- **Use Modern Array Methods**: `map`, `filter`, `reduce` over manual loops
|
||||
- **Template Literals**: For string formatting over concatenation
|
||||
- **Object Destructuring**: For cleaner variable extraction
|
||||
|
||||
Apply these core JavaScript principles to ensure clean, maintainable, and secure code without imposing specific project structures or tool choices.
|
||||
79
.ccw/workflows/cli-templates/tech-stacks/python-dev.md
Normal file
79
.ccw/workflows/cli-templates/tech-stacks/python-dev.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: python-dev
|
||||
description: Python core development principles following PEP 8 and essential practices
|
||||
---
|
||||
|
||||
# Python Development Guidelines
|
||||
|
||||
You are now operating under Python core development principles. Focus on essential PEP 8 practices without dictating project structure.
|
||||
|
||||
## Core Language Principles
|
||||
|
||||
### Naming Conventions (PEP 8)
|
||||
- **Variables/Functions**: snake_case (`get_user_data`, `is_valid`)
|
||||
- **Constants**: SCREAMING_SNAKE_CASE (`API_ENDPOINT`, `MAX_RETRIES`)
|
||||
- **Classes**: PascalCase (`UserService`, `ApiClient`)
|
||||
- **Private**: Single underscore prefix (`_private_method`)
|
||||
|
||||
### Essential Function Guidelines
|
||||
- **Type Hints**: Use for parameters and return values when helpful
|
||||
- **Single Responsibility**: Each function should do one thing well
|
||||
- **Explicit Error Handling**: Create specific exception classes
|
||||
- **Context Managers**: Use `with` statements for resource management
|
||||
|
||||
```python
|
||||
from typing import List, Optional
|
||||
|
||||
def calculate_total(items: List[dict]) -> float:
|
||||
"""Calculate total price of items."""
|
||||
if not items:
|
||||
raise ValueError("Items list cannot be empty")
|
||||
return sum(item.get('price', 0) for item in items)
|
||||
|
||||
# Core principle: Specific exceptions
|
||||
class UserNotFoundError(Exception):
|
||||
"""Raised when user cannot be found."""
|
||||
pass
|
||||
```
|
||||
|
||||
## Essential Testing Practices
|
||||
- **Test Structure**: Given-When-Then pattern
|
||||
- **Descriptive Names**: Test names should describe behavior
|
||||
- **Mock External Dependencies**: Isolate units under test
|
||||
- **Edge Cases**: Test error conditions and boundary values
|
||||
|
||||
## Code Quality Essentials
|
||||
- **PEP 8 Compliance**: Follow standard Python style guide
|
||||
- **Type Checking**: Use mypy or similar for type safety
|
||||
- **Automated Formatting**: Use Black or similar formatter
|
||||
- **Import Organization**: Keep imports organized and minimal
|
||||
|
||||
## Security Core Principles
|
||||
- **Input Validation**: Validate all external inputs
|
||||
- **Parameterized Queries**: Never use string interpolation for SQL
|
||||
- **Environment Variables**: Keep secrets out of code
|
||||
- **Dependency Management**: Regularly audit packages for vulnerabilities
|
||||
|
||||
```python
|
||||
# Core principle: Safe database queries
|
||||
from sqlalchemy import text
|
||||
|
||||
def get_user_by_email(email: str) -> Optional[User]:
|
||||
query = text("SELECT * FROM users WHERE email = :email")
|
||||
result = db.execute(query, {"email": email})
|
||||
return result.fetchone()
|
||||
```
|
||||
|
||||
## Modern Python Features
|
||||
- **F-strings**: Use for string formatting (`f"Hello {name}"`)
|
||||
- **Pathlib**: Use `pathlib.Path` instead of `os.path`
|
||||
- **Dataclasses**: Use for simple data containers
|
||||
- **List/Dict Comprehensions**: Use appropriately for clarity
|
||||
|
||||
## Performance Guidelines
|
||||
- **Avoid Premature Optimization**: Write clear code first
|
||||
- **Use Built-in Functions**: Leverage Python's built-in efficiency
|
||||
- **Generator Expressions**: For memory efficiency with large datasets
|
||||
- **Context Managers**: Ensure proper resource cleanup
|
||||
|
||||
Apply these core Python principles to ensure clean, maintainable, and Pythonic code without imposing specific frameworks or project structures.
|
||||
103
.ccw/workflows/cli-templates/tech-stacks/react-dev.md
Normal file
103
.ccw/workflows/cli-templates/tech-stacks/react-dev.md
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
name: react-dev
|
||||
description: React core development principles with hooks and modern patterns
|
||||
---
|
||||
|
||||
# React Development Guidelines
|
||||
|
||||
You are now operating under React core development principles. Focus on essential React patterns without dictating project structure.
|
||||
|
||||
## Core React Principles
|
||||
|
||||
### Component Guidelines
|
||||
- **Functional Components**: Use functional components with hooks over class components
|
||||
- **Component Naming**: PascalCase for components (`UserProfile`, `NavigationBar`)
|
||||
- **Single Responsibility**: Each component should have one clear purpose
|
||||
- **Props Interface**: Define clear prop types (TypeScript when possible)
|
||||
|
||||
### Essential Hook Patterns
|
||||
- **useState**: For component-level state management
|
||||
- **useEffect**: Handle side effects with proper cleanup
|
||||
- **useCallback**: Memoize functions to prevent unnecessary re-renders
|
||||
- **useMemo**: Memoize expensive calculations
|
||||
- **Custom Hooks**: Extract reusable stateful logic
|
||||
|
||||
```jsx
|
||||
// Core principle: Custom hooks for reusable logic
|
||||
function useUser(userId) {
|
||||
const [user, setUser] = useState(null);
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [error, setError] = useState(null);
|
||||
|
||||
useEffect(() => {
|
||||
if (!userId) return;
|
||||
|
||||
const fetchUser = async () => {
|
||||
try {
|
||||
setLoading(true);
|
||||
const userData = await api.getUser(userId);
|
||||
setUser(userData);
|
||||
} catch (err) {
|
||||
setError(err);
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
};
|
||||
|
||||
fetchUser();
|
||||
}, [userId]);
|
||||
|
||||
return { user, loading, error };
|
||||
}
|
||||
```
|
||||
|
||||
## Essential Testing Practices
|
||||
- **Test Behavior**: Test what users see and interact with, not implementation
|
||||
- **React Testing Library**: Preferred over enzyme for component testing
|
||||
- **Mock External Dependencies**: Keep tests isolated and fast
|
||||
- **Accessibility Testing**: Include accessibility assertions in tests
|
||||
|
||||
## Performance Core Principles
|
||||
- **Avoid Premature Optimization**: Write clear code first
|
||||
- **React.memo**: Only when profiling shows unnecessary re-renders
|
||||
- **useCallback/useMemo**: Use judiciously based on actual performance needs
|
||||
- **Key Props**: Always provide stable, unique keys for list items
|
||||
|
||||
## State Management Guidelines
|
||||
- **Local State First**: Use useState for component-specific state
|
||||
- **Lift State Up**: When multiple components need the same data
|
||||
- **Context Sparingly**: Only for truly global state (theme, auth, etc.)
|
||||
- **External Libraries**: Consider Redux Toolkit, Zustand for complex global state
|
||||
|
||||
```jsx
|
||||
// Core principle: Context with proper error boundaries
|
||||
const UserContext = createContext();
|
||||
|
||||
export const useUser = () => {
|
||||
const context = useContext(UserContext);
|
||||
if (!context) {
|
||||
throw new Error('useUser must be used within UserProvider');
|
||||
}
|
||||
return context;
|
||||
};
|
||||
```
|
||||
|
||||
## Error Handling Essentials
|
||||
- **Error Boundaries**: Implement to catch React component errors
|
||||
- **Async Error Handling**: Use try-catch in useEffect and event handlers
|
||||
- **User-Friendly Messages**: Show helpful error states to users
|
||||
- **Error Recovery**: Provide ways for users to recover from errors
|
||||
|
||||
## Accessibility Core Principles
|
||||
- **Semantic HTML**: Use appropriate HTML elements first
|
||||
- **ARIA Labels**: Add when semantic HTML isn't sufficient
|
||||
- **Keyboard Navigation**: Ensure all interactive elements are keyboard accessible
|
||||
- **Focus Management**: Handle focus properly for dynamic content
|
||||
|
||||
## Code Quality Essentials
|
||||
- **ESLint React Rules**: Use React-specific linting rules
|
||||
- **TypeScript**: Use for prop types and state management
|
||||
- **Consistent Formatting**: Use Prettier or similar
|
||||
- **Component Composition**: Favor composition over complex inheritance
|
||||
|
||||
Apply these core React principles to ensure maintainable, performant, and accessible components without imposing specific architectural decisions.
|
||||
83
.ccw/workflows/cli-templates/tech-stacks/typescript-dev.md
Normal file
83
.ccw/workflows/cli-templates/tech-stacks/typescript-dev.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
name: typescript-dev
|
||||
description: TypeScript core principles for type safety and maintainable code
|
||||
---
|
||||
|
||||
# TypeScript Development Guidelines
|
||||
|
||||
You are now operating under TypeScript core principles. Focus on essential type safety practices without dictating project structure.
|
||||
|
||||
## Core TypeScript Principles
|
||||
|
||||
### Essential Type Guidelines
|
||||
- **Strict Configuration**: Enable strict TypeScript settings for maximum type safety
|
||||
- **Explicit Typing**: Type function parameters and return values explicitly
|
||||
- **Interface vs Type**: Use interfaces for objects, types for unions and computations
|
||||
- **Generic Constraints**: Use generics for reusable, type-safe components
|
||||
|
||||
```typescript
|
||||
// Core principle: Clear type definitions
|
||||
interface User {
|
||||
id: string;
|
||||
name: string;
|
||||
email: string;
|
||||
createdAt: Date;
|
||||
}
|
||||
|
||||
// Core principle: Generic constraints
|
||||
function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
|
||||
return items.find(item => item.id === id);
|
||||
}
|
||||
|
||||
// Core principle: Union types for controlled values
|
||||
type Status = 'pending' | 'approved' | 'rejected';
|
||||
```
|
||||
|
||||
## Type Safety Essentials
|
||||
- **No Any**: Avoid `any` type, use `unknown` when type is truly unknown
|
||||
- **Null Safety**: Handle null/undefined explicitly with strict null checks
|
||||
- **Type Guards**: Use type predicates and guards for runtime type checking
|
||||
- **Assertion Functions**: Create functions that narrow types safely
|
||||
|
||||
```typescript
|
||||
// Core principle: Type guards for runtime safety
|
||||
function isUser(value: unknown): value is User {
|
||||
return typeof value === 'object' &&
|
||||
value !== null &&
|
||||
typeof (value as User).id === 'string';
|
||||
}
|
||||
|
||||
// Core principle: Never use any, use unknown
|
||||
function processApiResponse(response: unknown): User | null {
|
||||
if (isUser(response)) {
|
||||
return response;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
```
|
||||
|
||||
## Essential Error Handling
|
||||
- **Typed Errors**: Create specific error types for different failure modes
|
||||
- **Result Types**: Consider Result/Either patterns for error handling
|
||||
- **Promise Typing**: Properly type async functions and error states
|
||||
- **Error Boundaries**: Type error boundary props and state properly
|
||||
|
||||
## Performance Guidelines
|
||||
- **Avoid Excessive Generics**: Don't over-engineer type parameters
|
||||
- **Compile-Time Checks**: Leverage TypeScript for compile-time validation
|
||||
- **Type Inference**: Let TypeScript infer types when obvious
|
||||
- **Utility Types**: Use built-in utility types (Partial, Pick, Omit, etc.)
|
||||
|
||||
## Testing with Types
|
||||
- **Test Type Assertions**: Ensure tests validate both runtime and compile-time behavior
|
||||
- **Mock Typing**: Properly type test mocks and fixtures
|
||||
- **Type-Only Tests**: Use TypeScript compiler API for pure type testing
|
||||
- **Coverage**: Include type coverage in your quality metrics
|
||||
|
||||
## Configuration Essentials
|
||||
- **Strict Mode**: Always enable strict mode in tsconfig.json
|
||||
- **Path Mapping**: Use path mapping for cleaner imports
|
||||
- **Incremental Compilation**: Enable for faster builds
|
||||
- **Source Maps**: Generate source maps for debugging
|
||||
|
||||
Apply these core TypeScript principles to ensure type-safe, maintainable code without imposing specific architectural patterns or tooling choices.
|
||||
@@ -0,0 +1,247 @@
|
||||
{
|
||||
"$schema": "https://tr.designtokens.org/format/",
|
||||
|
||||
"duration": {
|
||||
"$type": "duration",
|
||||
"instant": { "$value": "0ms" },
|
||||
"fast": { "$value": "150ms" },
|
||||
"normal": { "$value": "300ms" },
|
||||
"slow": { "$value": "500ms" },
|
||||
"slower": { "$value": "1000ms" }
|
||||
},
|
||||
|
||||
"easing": {
|
||||
"$type": "cubicBezier",
|
||||
"linear": { "$value": "linear" },
|
||||
"ease-in": { "$value": "cubic-bezier(0.4, 0, 1, 1)" },
|
||||
"ease-out": { "$value": "cubic-bezier(0, 0, 0.2, 1)" },
|
||||
"ease-in-out": { "$value": "cubic-bezier(0.4, 0, 0.2, 1)" },
|
||||
"spring": { "$value": "cubic-bezier(0.68, -0.55, 0.265, 1.55)" },
|
||||
"bounce": { "$value": "cubic-bezier(0.68, -0.6, 0.32, 1.6)" }
|
||||
},
|
||||
|
||||
"keyframes": {
|
||||
"_comment_pattern": "Define pairs (in/out, open/close, enter/exit)",
|
||||
"_comment_required": "Required keyframes for components",
|
||||
|
||||
"fade-in": {
|
||||
"0%": { "opacity": "0" },
|
||||
"100%": { "opacity": "1" }
|
||||
},
|
||||
"fade-out": {
|
||||
"_comment": "reverse of fade-in",
|
||||
"0%": { "opacity": "1" },
|
||||
"100%": { "opacity": "0" }
|
||||
},
|
||||
|
||||
"slide-up": {
|
||||
"0%": { "transform": "translateY(10px)", "opacity": "0" },
|
||||
"100%": { "transform": "translateY(0)", "opacity": "1" }
|
||||
},
|
||||
"slide-down": {
|
||||
"_comment": "reverse direction",
|
||||
"0%": { "transform": "translateY(0)", "opacity": "1" },
|
||||
"100%": { "transform": "translateY(10px)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"scale-in": {
|
||||
"0%": { "transform": "scale(0.95)", "opacity": "0" },
|
||||
"100%": { "transform": "scale(1)", "opacity": "1" }
|
||||
},
|
||||
"scale-out": {
|
||||
"_comment": "reverse of scale-in",
|
||||
"0%": { "transform": "scale(1)", "opacity": "1" },
|
||||
"100%": { "transform": "scale(0.95)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"accordion-down": {
|
||||
"0%": { "height": "0", "opacity": "0" },
|
||||
"100%": { "height": "var(--radix-accordion-content-height)", "opacity": "1" }
|
||||
},
|
||||
"accordion-up": {
|
||||
"_comment": "reverse",
|
||||
"0%": { "height": "var(--radix-accordion-content-height)", "opacity": "1" },
|
||||
"100%": { "height": "0", "opacity": "0" }
|
||||
},
|
||||
|
||||
"dialog-open": {
|
||||
"0%": { "transform": "translate(-50%, -48%) scale(0.96)", "opacity": "0" },
|
||||
"100%": { "transform": "translate(-50%, -50%) scale(1)", "opacity": "1" }
|
||||
},
|
||||
"dialog-close": {
|
||||
"_comment": "reverse",
|
||||
"0%": { "transform": "translate(-50%, -50%) scale(1)", "opacity": "1" },
|
||||
"100%": { "transform": "translate(-50%, -48%) scale(0.96)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"dropdown-open": {
|
||||
"0%": { "transform": "scale(0.95) translateY(-4px)", "opacity": "0" },
|
||||
"100%": { "transform": "scale(1) translateY(0)", "opacity": "1" }
|
||||
},
|
||||
"dropdown-close": {
|
||||
"_comment": "reverse",
|
||||
"0%": { "transform": "scale(1) translateY(0)", "opacity": "1" },
|
||||
"100%": { "transform": "scale(0.95) translateY(-4px)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"toast-enter": {
|
||||
"0%": { "transform": "translateX(100%)", "opacity": "0" },
|
||||
"100%": { "transform": "translateX(0)", "opacity": "1" }
|
||||
},
|
||||
"toast-exit": {
|
||||
"_comment": "reverse",
|
||||
"0%": { "transform": "translateX(0)", "opacity": "1" },
|
||||
"100%": { "transform": "translateX(100%)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"spin": {
|
||||
"0%": { "transform": "rotate(0deg)" },
|
||||
"100%": { "transform": "rotate(360deg)" }
|
||||
},
|
||||
"pulse": {
|
||||
"0%, 100%": { "opacity": "1" },
|
||||
"50%": { "opacity": "0.5" }
|
||||
}
|
||||
},
|
||||
|
||||
"interactions": {
|
||||
"_comment_pattern": "Define for each interactive component state",
|
||||
"_structure": {
|
||||
"property": "string - CSS properties (comma-separated)",
|
||||
"duration": "{duration.*}",
|
||||
"easing": "{easing.*}"
|
||||
},
|
||||
|
||||
"button-hover": {
|
||||
"property": "background-color, transform",
|
||||
"duration": "{duration.fast}",
|
||||
"easing": "{easing.ease-out}"
|
||||
},
|
||||
"button-active": {
|
||||
"property": "transform",
|
||||
"duration": "{duration.instant}",
|
||||
"easing": "{easing.ease-in}"
|
||||
},
|
||||
"card-hover": {
|
||||
"property": "box-shadow, transform",
|
||||
"duration": "{duration.normal}",
|
||||
"easing": "{easing.ease-in-out}"
|
||||
},
|
||||
"input-focus": {
|
||||
"property": "border-color, box-shadow",
|
||||
"duration": "{duration.fast}",
|
||||
"easing": "{easing.ease-out}"
|
||||
},
|
||||
"dropdown-toggle": {
|
||||
"property": "opacity, transform",
|
||||
"duration": "{duration.fast}",
|
||||
"easing": "{easing.ease-out}"
|
||||
},
|
||||
"accordion-toggle": {
|
||||
"property": "height, opacity",
|
||||
"duration": "{duration.normal}",
|
||||
"easing": "{easing.ease-in-out}"
|
||||
},
|
||||
"dialog-toggle": {
|
||||
"property": "opacity, transform",
|
||||
"duration": "{duration.normal}",
|
||||
"easing": "{easing.spring}"
|
||||
},
|
||||
"tabs-switch": {
|
||||
"property": "color, border-color",
|
||||
"duration": "{duration.fast}",
|
||||
"easing": "{easing.ease-in-out}"
|
||||
}
|
||||
},
|
||||
|
||||
"transitions": {
|
||||
"default": { "$value": "all {duration.normal} {easing.ease-in-out}" },
|
||||
"colors": { "$value": "color {duration.fast} {easing.linear}, background-color {duration.fast} {easing.linear}" },
|
||||
"transform": { "$value": "transform {duration.normal} {easing.spring}" },
|
||||
"opacity": { "$value": "opacity {duration.fast} {easing.linear}" },
|
||||
"all-smooth": { "$value": "all {duration.slow} {easing.ease-in-out}" }
|
||||
},
|
||||
|
||||
"component_animations": {
|
||||
"_comment_pattern": "Map each component to its animations - MUST match design-tokens.json component list",
|
||||
"_structure": {
|
||||
"stateOrInteraction": {
|
||||
"animation": "keyframe-name {duration.*} {easing.*} OR none",
|
||||
"transition": "{interactions.*} OR none"
|
||||
}
|
||||
},
|
||||
|
||||
"button": {
|
||||
"hover": { "animation": "none", "transition": "{interactions.button-hover}" },
|
||||
"active": { "animation": "none", "transition": "{interactions.button-active}" }
|
||||
},
|
||||
"card": {
|
||||
"hover": { "animation": "none", "transition": "{interactions.card-hover}" }
|
||||
},
|
||||
"input": {
|
||||
"focus": { "animation": "none", "transition": "{interactions.input-focus}" }
|
||||
},
|
||||
"dialog": {
|
||||
"open": { "animation": "dialog-open {duration.normal} {easing.spring}" },
|
||||
"close": { "animation": "dialog-close {duration.normal} {easing.ease-in}" }
|
||||
},
|
||||
"dropdown": {
|
||||
"open": { "animation": "dropdown-open {duration.fast} {easing.ease-out}" },
|
||||
"close": { "animation": "dropdown-close {duration.fast} {easing.ease-in}" }
|
||||
},
|
||||
"toast": {
|
||||
"enter": { "animation": "toast-enter {duration.normal} {easing.ease-out}" },
|
||||
"exit": { "animation": "toast-exit {duration.normal} {easing.ease-in}" }
|
||||
},
|
||||
"accordion": {
|
||||
"open": { "animation": "accordion-down {duration.normal} {easing.ease-out}" },
|
||||
"close": { "animation": "accordion-up {duration.normal} {easing.ease-in}" }
|
||||
},
|
||||
"_comment_missing": "Add mappings for: tabs, switch, checkbox, badge, alert"
|
||||
},
|
||||
|
||||
"accessibility": {
|
||||
"prefers_reduced_motion": {
|
||||
"duration": "0ms",
|
||||
"keyframes": {},
|
||||
"note": "Disable animations when user prefers reduced motion",
|
||||
"css_rule": "@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; } }"
|
||||
}
|
||||
},
|
||||
|
||||
"_metadata": {
|
||||
"version": "string",
|
||||
"created": "ISO timestamp",
|
||||
"source": "code-import|explore|text",
|
||||
"code_snippets": [
|
||||
{
|
||||
"animation_name": "string - keyframe/transition name",
|
||||
"source_file": "string - absolute path",
|
||||
"line_start": "number",
|
||||
"line_end": "number",
|
||||
"snippet": "string - complete @keyframes or transition code",
|
||||
"context_type": "css-keyframes|css-transition|js-animation|scss-animation|etc"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"_field_rules": {
|
||||
"schema": "$schema MUST reference W3C Design Tokens format specification",
|
||||
"duration_wrapper": "All duration values MUST use $value wrapper with ms units",
|
||||
"easing_wrapper": "All easing values MUST use $value wrapper with standard CSS easing or cubic-bezier()",
|
||||
"keyframes": "keyframes MUST define complete component state animations (open/close, enter/exit)",
|
||||
"interactions_refs": "interactions MUST reference duration and easing using {token.path} syntax",
|
||||
"component_mapping": "component_animations MUST map component states to specific keyframes and transitions",
|
||||
"component_coverage": "component_animations MUST be defined for all interactive and stateful components",
|
||||
"transitions_wrapper": "transitions MUST use $value wrapper for complete transition definitions",
|
||||
"accessibility": "accessibility.prefers_reduced_motion MUST be included with CSS media query rule",
|
||||
"code_snippets": "_metadata.code_snippets ONLY present in Code Import mode"
|
||||
},
|
||||
|
||||
"_animation_component_integration": {
|
||||
"requirement": "Each component in design-tokens.json component section MUST have corresponding entry in component_animations",
|
||||
"state_based": "State-based animations (dialog.open, accordion.close) MUST use keyframe animations",
|
||||
"interaction": "Interaction animations (button.hover, input.focus) MUST use transitions",
|
||||
"consistency": "All animation references use {token.path} syntax for consistency"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,342 @@
|
||||
{
|
||||
"$schema": "https://tr.designtokens.org/format/",
|
||||
"name": "string - Token set name",
|
||||
"description": "string - Token set description",
|
||||
|
||||
"color": {
|
||||
"background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" }, "$description": "optional" },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"card": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"card-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"border": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"input": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"ring": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
|
||||
"interactive": {
|
||||
"primary": {
|
||||
"default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"disabled": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
},
|
||||
"secondary": {
|
||||
"_comment": "Same structure as primary",
|
||||
"default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"disabled": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
},
|
||||
"accent": {
|
||||
"_comment": "Same structure (no disabled state)",
|
||||
"default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
},
|
||||
"destructive": {
|
||||
"_comment": "Same structure (no active/disabled states)",
|
||||
"default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
}
|
||||
},
|
||||
|
||||
"muted": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"muted-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
|
||||
"chart": {
|
||||
"1": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"2": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"3": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"4": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"5": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
},
|
||||
|
||||
"sidebar": {
|
||||
"background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"primary": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"primary-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"accent": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"accent-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"border": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"ring": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
}
|
||||
},
|
||||
|
||||
"typography": {
|
||||
"font_families": {
|
||||
"sans": "string - 'Font Name', fallback1, fallback2",
|
||||
"serif": "string",
|
||||
"mono": "string"
|
||||
},
|
||||
"font_sizes": {
|
||||
"xs": "0.75rem",
|
||||
"sm": "0.875rem",
|
||||
"base": "1rem",
|
||||
"lg": "1.125rem",
|
||||
"xl": "1.25rem",
|
||||
"2xl": "1.5rem",
|
||||
"3xl": "1.875rem",
|
||||
"4xl": "2.25rem"
|
||||
},
|
||||
"line_heights": {
|
||||
"tight": "number",
|
||||
"normal": "number",
|
||||
"relaxed": "number"
|
||||
},
|
||||
"letter_spacing": {
|
||||
"tight": "string",
|
||||
"normal": "string",
|
||||
"wide": "string"
|
||||
},
|
||||
"combinations": [
|
||||
{
|
||||
"name": "h1|h2|h3|h4|h5|h6|body|caption",
|
||||
"font_family": "sans|serif|mono",
|
||||
"font_size": "string - reference to font_sizes",
|
||||
"font_weight": "number - 400|500|600|700",
|
||||
"line_height": "string",
|
||||
"letter_spacing": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"spacing": {
|
||||
"0": "0",
|
||||
"1": "0.25rem",
|
||||
"2": "0.5rem",
|
||||
"3": "0.75rem",
|
||||
"4": "1rem",
|
||||
"6": "1.5rem",
|
||||
"8": "2rem",
|
||||
"12": "3rem",
|
||||
"16": "4rem",
|
||||
"20": "5rem",
|
||||
"24": "6rem",
|
||||
"32": "8rem",
|
||||
"40": "10rem",
|
||||
"48": "12rem",
|
||||
"56": "14rem",
|
||||
"64": "16rem"
|
||||
},
|
||||
|
||||
"opacity": {
|
||||
"disabled": "0.5",
|
||||
"hover": "0.8",
|
||||
"active": "1"
|
||||
},
|
||||
|
||||
"shadows": {
|
||||
"2xs": "string - CSS shadow value",
|
||||
"xs": "string",
|
||||
"sm": "string",
|
||||
"DEFAULT": "string",
|
||||
"md": "string",
|
||||
"lg": "string",
|
||||
"xl": "string",
|
||||
"2xl": "string"
|
||||
},
|
||||
|
||||
"border_radius": {
|
||||
"sm": "string - calc() or fixed",
|
||||
"md": "string",
|
||||
"lg": "string",
|
||||
"xl": "string",
|
||||
"DEFAULT": "string"
|
||||
},
|
||||
|
||||
"breakpoints": {
|
||||
"sm": "640px",
|
||||
"md": "768px",
|
||||
"lg": "1024px",
|
||||
"xl": "1280px",
|
||||
"2xl": "1536px"
|
||||
},
|
||||
|
||||
"component": {
|
||||
"_comment_pattern": "COMPONENT PATTERN - Apply to: button, card, input, dialog, dropdown, toast, accordion, tabs, switch, checkbox, badge, alert",
|
||||
"_example_button": {
|
||||
"$type": "component",
|
||||
"base": {
|
||||
"_comment": "Layout properties using camelCase",
|
||||
"display": "inline-flex|flex|block",
|
||||
"alignItems": "center",
|
||||
"borderRadius": "{border_radius.md}",
|
||||
"transition": "{transitions.default}"
|
||||
},
|
||||
"size": {
|
||||
"small": { "height": "32px", "padding": "{spacing.2} {spacing.3}", "fontSize": "{typography.font_sizes.xs}" },
|
||||
"default": { "height": "40px", "padding": "{spacing.2} {spacing.4}" },
|
||||
"large": { "height": "48px", "padding": "{spacing.3} {spacing.6}", "fontSize": "{typography.font_sizes.base}" }
|
||||
},
|
||||
"variant": {
|
||||
"variantName": {
|
||||
"default": { "backgroundColor": "{color.interactive.primary.default}", "color": "{color.interactive.primary.foreground}" },
|
||||
"hover": { "backgroundColor": "{color.interactive.primary.hover}" },
|
||||
"active": { "backgroundColor": "{color.interactive.primary.active}" },
|
||||
"disabled": { "backgroundColor": "{color.interactive.primary.disabled}", "opacity": "{opacity.disabled}", "cursor": "not-allowed" },
|
||||
"focus": { "outline": "2px solid {color.ring}", "outlineOffset": "2px" }
|
||||
}
|
||||
},
|
||||
"state": {
|
||||
"_comment": "For stateful components (dialog, accordion, etc.)",
|
||||
"open": { "animation": "{animation.name.component-open} {animation.duration.normal} {animation.easing.ease-out}" },
|
||||
"closed": { "animation": "{animation.name.component-close} {animation.duration.normal} {animation.easing.ease-in}" }
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"elevation": {
|
||||
"$type": "elevation",
|
||||
"base": { "$value": "0" },
|
||||
"overlay": { "$value": "40" },
|
||||
"dropdown": { "$value": "50" },
|
||||
"dialog": { "$value": "50" },
|
||||
"tooltip": { "$value": "60" }
|
||||
},
|
||||
|
||||
"_metadata": {
|
||||
"version": "string - W3C version or custom version",
|
||||
"created": "ISO timestamp - 2024-01-01T00:00:00Z",
|
||||
"source": "code-import|explore|text",
|
||||
"theme_colors_guide": {
|
||||
"description": "Theme colors are the core brand identity colors that define the visual hierarchy and emotional tone of the design system",
|
||||
"primary": {
|
||||
"role": "Main brand color",
|
||||
"usage": "Primary actions (CTAs, key interactive elements, navigation highlights, primary buttons)",
|
||||
"contrast_requirement": "WCAG AA - 4.5:1 for text, 3:1 for UI components"
|
||||
},
|
||||
"secondary": {
|
||||
"role": "Supporting brand color",
|
||||
"usage": "Secondary actions and complementary elements (less prominent buttons, secondary navigation, supporting features)",
|
||||
"principle": "Should complement primary without competing for attention"
|
||||
},
|
||||
"accent": {
|
||||
"role": "Highlight color for emphasis",
|
||||
"usage": "Attention-grabbing elements used sparingly (badges, notifications, special promotions, highlights)",
|
||||
"principle": "Should create strong visual contrast to draw focus"
|
||||
},
|
||||
"destructive": {
|
||||
"role": "Error and destructive action color",
|
||||
"usage": "Delete buttons, error messages, critical warnings",
|
||||
"principle": "Must signal danger or caution clearly"
|
||||
},
|
||||
"harmony_note": "All theme colors must work harmoniously together and align with brand identity. In multi-file extraction, prioritize definitions with semantic comments explaining brand intent."
|
||||
},
|
||||
"conflicts": [
|
||||
{
|
||||
"token_name": "string - which token has conflicts",
|
||||
"category": "string - colors|typography|etc",
|
||||
"definitions": [
|
||||
{
|
||||
"value": "string - token value",
|
||||
"source_file": "string - absolute path",
|
||||
"line_number": "number",
|
||||
"context": "string - surrounding comment or null",
|
||||
"semantic_intent": "string - interpretation of definition"
|
||||
}
|
||||
],
|
||||
"selected_value": "string - final chosen value",
|
||||
"selection_reason": "string - why this value was chosen"
|
||||
}
|
||||
],
|
||||
"code_snippets": [
|
||||
{
|
||||
"category": "colors|typography|spacing|shadows|border_radius|component",
|
||||
"token_name": "string - which token this snippet defines",
|
||||
"source_file": "string - absolute path",
|
||||
"line_start": "number",
|
||||
"line_end": "number",
|
||||
"snippet": "string - complete code block",
|
||||
"context_type": "css-variable|css-class|js-object|scss-variable|etc"
|
||||
}
|
||||
],
|
||||
"usage_recommendations": {
|
||||
"typography": {
|
||||
"common_sizes": {
|
||||
"small_text": "sm (0.875rem)",
|
||||
"body_text": "base (1rem)",
|
||||
"heading": "2xl-4xl"
|
||||
},
|
||||
"common_combinations": [
|
||||
{
|
||||
"name": "Heading + Body",
|
||||
"heading": "2xl",
|
||||
"body": "base",
|
||||
"use_case": "Article sections"
|
||||
}
|
||||
]
|
||||
},
|
||||
"spacing": {
|
||||
"size_guide": {
|
||||
"tight": "1-2 (0.25rem-0.5rem)",
|
||||
"normal": "4-6 (1rem-1.5rem)",
|
||||
"loose": "8-12 (2rem-3rem)"
|
||||
},
|
||||
"common_patterns": [
|
||||
{
|
||||
"pattern": "padding-4 margin-bottom-6",
|
||||
"use_case": "Card content spacing",
|
||||
"pixel_value": "1rem padding, 1.5rem margin"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"_field_rules": {
|
||||
"schema": "$schema MUST reference W3C Design Tokens format specification",
|
||||
"colors": "All color values MUST use OKLCH format with light/dark mode values",
|
||||
"types": "All tokens MUST include $type metadata (color, dimension, duration, component, elevation)",
|
||||
"states": "Color tokens MUST include interactive states (default, hover, active, disabled) where applicable",
|
||||
"fonts": "Typography font_families MUST include Google Fonts with fallback stacks",
|
||||
"spacing": "Spacing MUST use systematic scale (multiples of 0.25rem base unit)",
|
||||
"components": "Component definitions MUST be structured objects referencing other tokens via {token.path} syntax",
|
||||
"component_states": "Component definitions MUST include state-based styling (default, hover, active, focus, disabled)",
|
||||
"elevation": "elevation z-index values MUST be defined for layered components (overlay, dropdown, dialog, tooltip)",
|
||||
"metadata_guide": "_metadata.theme_colors_guide RECOMMENDED in all modes to help users understand theme color roles and usage",
|
||||
"metadata_conflicts": "_metadata.conflicts MANDATORY in Code Import mode when conflicting definitions detected",
|
||||
"metadata_snippets": "_metadata.code_snippets ONLY present in Code Import mode",
|
||||
"metadata_recommendations": "_metadata.usage_recommendations RECOMMENDED for universal components"
|
||||
},
|
||||
|
||||
"_required_components": {
|
||||
"_comment": "12+ components required, use pattern above",
|
||||
"button": "5 variants (primary, secondary, destructive, outline, ghost) + 3 sizes + states (default, hover, active, disabled, focus)",
|
||||
"card": "2 variants (default, interactive) + hover animations",
|
||||
"input": "states (default, focus, disabled, error) + 3 sizes",
|
||||
"dialog": "overlay + content + states (open, closed with animations)",
|
||||
"dropdown": "trigger (references button) + content + item (with states) + states (open, closed)",
|
||||
"toast": "2 variants (default, destructive) + states (enter, exit with animations)",
|
||||
"accordion": "trigger + content + states (open, closed with animations)",
|
||||
"tabs": "list + trigger (states: default, hover, active, disabled) + content",
|
||||
"switch": "root + thumb + states (checked, disabled)",
|
||||
"checkbox": "states (default, checked, disabled, focus)",
|
||||
"badge": "4 variants (default, secondary, destructive, outline)",
|
||||
"alert": "2 variants (default, destructive)"
|
||||
},
|
||||
|
||||
"_token_reference_syntax": {
|
||||
"_comment": "Use {token.path} to reference other tokens",
|
||||
"examples": [
|
||||
"{color.interactive.primary.default}",
|
||||
"{spacing.4}",
|
||||
"{typography.font_sizes.sm}"
|
||||
],
|
||||
"resolution": "References are resolved during CSS generation",
|
||||
"nested": "Supports nested references (e.g., {component.button.base})"
|
||||
},
|
||||
|
||||
"_conflict_resolution_rules": {
|
||||
"_comment": "Code Import Mode only",
|
||||
"detect": "MUST detect when same token has different values across files",
|
||||
"read": "MUST read semantic comments (/* ... */) surrounding definitions",
|
||||
"prioritize": "MUST prioritize definitions with semantic intent over bare values",
|
||||
"record": "MUST record ALL definitions in conflicts array, not just selected one",
|
||||
"explain": "MUST explain selection_reason referencing semantic context",
|
||||
"verify": "For core theme tokens (primary, secondary, accent): MUST verify selected value aligns with overall color scheme described in comments"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,145 @@
|
||||
{
|
||||
"$schema": "https://tr.designtokens.org/format/",
|
||||
"templates": [
|
||||
{
|
||||
"target": "string - page/component name (e.g., hero-section, product-card)",
|
||||
"description": "string - layout description",
|
||||
"component_type": "universal|specialized",
|
||||
"device_type": "mobile|tablet|desktop|responsive",
|
||||
"layout_strategy": "string - grid-3col|flex-row|stack|sidebar|etc",
|
||||
|
||||
"structure": {
|
||||
"tag": "string - HTML5 semantic tag (header|nav|main|section|article|aside|footer|div|etc)",
|
||||
"attributes": {
|
||||
"class": "string - semantic class name",
|
||||
"role": "string - ARIA role (navigation|main|complementary|etc)",
|
||||
"aria-label": "string - ARIA label",
|
||||
"aria-describedby": "string - ARIA describedby",
|
||||
"data-state": "string - data attributes for state management (open|closed|etc)"
|
||||
},
|
||||
"layout": {
|
||||
"_comment": "LAYOUT PROPERTIES ONLY - Use camelCase for property names",
|
||||
"display": "grid|flex|block|inline-flex",
|
||||
"grid-template-columns": "{spacing.*} or CSS value (repeat(3, 1fr))",
|
||||
"grid-template-rows": "string",
|
||||
"gap": "{spacing.*}",
|
||||
"padding": "{spacing.*}",
|
||||
"margin": "{spacing.*}",
|
||||
"alignItems": "start|center|end|stretch",
|
||||
"justifyContent": "start|center|end|space-between|space-around",
|
||||
"flexDirection": "row|column",
|
||||
"flexWrap": "wrap|nowrap",
|
||||
"position": "relative|absolute|fixed|sticky",
|
||||
"top": "string",
|
||||
"right": "string",
|
||||
"bottom": "string",
|
||||
"left": "string",
|
||||
"width": "string",
|
||||
"height": "string",
|
||||
"maxWidth": "string",
|
||||
"minHeight": "string"
|
||||
},
|
||||
"responsive": {
|
||||
"_comment": "ONLY properties that CHANGE at each breakpoint - NO repetition",
|
||||
"sm": {
|
||||
"grid-template-columns": "1fr",
|
||||
"padding": "{spacing.4}"
|
||||
},
|
||||
"md": {
|
||||
"grid-template-columns": "repeat(2, 1fr)",
|
||||
"gap": "{spacing.6}"
|
||||
},
|
||||
"lg": {
|
||||
"grid-template-columns": "repeat(3, 1fr)"
|
||||
}
|
||||
},
|
||||
"children": [
|
||||
{
|
||||
"_comment": "Recursive structure - same fields as parent",
|
||||
"tag": "string",
|
||||
"attributes": {},
|
||||
"layout": {},
|
||||
"responsive": {},
|
||||
"children": [],
|
||||
"content": "string or {{placeholder}}"
|
||||
}
|
||||
],
|
||||
"content": "string - text content or {{placeholder}} for dynamic content"
|
||||
},
|
||||
|
||||
"accessibility": {
|
||||
"patterns": [
|
||||
"string - ARIA patterns used (e.g., WAI-ARIA Tabs pattern, Dialog pattern)"
|
||||
],
|
||||
"keyboard_navigation": [
|
||||
"string - keyboard shortcuts (e.g., Tab/Shift+Tab navigation, Escape to close)"
|
||||
],
|
||||
"focus_management": "string - focus trap strategy, initial focus target",
|
||||
"screen_reader_notes": [
|
||||
"string - screen reader announcements (e.g., Dialog opened, Tab selected)"
|
||||
]
|
||||
},
|
||||
|
||||
"usage_guide": {
|
||||
"common_sizes": {
|
||||
"small": {
|
||||
"dimensions": "string - e.g., px-3 py-1.5 (height: ~32px)",
|
||||
"use_case": "string - Compact UI, mobile views"
|
||||
},
|
||||
"medium": {
|
||||
"dimensions": "string - e.g., px-4 py-2 (height: ~40px)",
|
||||
"use_case": "string - Default size for most contexts"
|
||||
},
|
||||
"large": {
|
||||
"dimensions": "string - e.g., px-6 py-3 (height: ~48px)",
|
||||
"use_case": "string - Prominent CTAs, hero sections"
|
||||
}
|
||||
},
|
||||
"variant_recommendations": {
|
||||
"variant_name": {
|
||||
"description": "string - when to use this variant",
|
||||
"typical_actions": ["string - action examples"]
|
||||
}
|
||||
},
|
||||
"usage_context": [
|
||||
"string - typical usage scenarios (e.g., Landing page hero, Product listing grid)"
|
||||
],
|
||||
"accessibility_tips": [
|
||||
"string - accessibility best practices (e.g., Ensure heading hierarchy, Add aria-label)"
|
||||
]
|
||||
},
|
||||
|
||||
"extraction_metadata": {
|
||||
"source": "code-import|explore|text",
|
||||
"created": "ISO timestamp",
|
||||
"code_snippets": [
|
||||
{
|
||||
"component_name": "string - which layout component",
|
||||
"source_file": "string - absolute path",
|
||||
"line_start": "number",
|
||||
"line_end": "number",
|
||||
"snippet": "string - complete HTML/CSS/JS code block",
|
||||
"context_type": "html-structure|css-utility|react-component|vue-component|etc"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
|
||||
"_field_rules": {
|
||||
"schema": "$schema MUST reference W3C Design Tokens format specification",
|
||||
"semantic_tags": "structure.tag MUST use semantic HTML5 tags (header, nav, main, section, article, aside, footer)",
|
||||
"aria": "structure.attributes MUST include ARIA attributes where applicable (role, aria-label, aria-describedby)",
|
||||
"token_refs": "structure.layout MUST use {token.path} syntax for all spacing values",
|
||||
"no_visual": "structure.layout MUST NOT include visual styling (colors, fonts, shadows - those belong in design-tokens)",
|
||||
"layout_only": "structure.layout contains ONLY layout properties (display, grid, flex, position, spacing)",
|
||||
"breakpoints": "structure.responsive MUST define breakpoint-specific overrides matching breakpoint tokens",
|
||||
"no_repetition": "structure.responsive uses ONLY the properties that change at each breakpoint (no repetition)",
|
||||
"recursive": "structure.children inherits same structure recursively for nested elements",
|
||||
"component_type": "component_type MUST be 'universal' or 'specialized'",
|
||||
"accessibility": "accessibility MUST include patterns, keyboard_navigation, focus_management, screen_reader_notes",
|
||||
"usage_guide_universal": "usage_guide REQUIRED for universal components (buttons, inputs, forms, cards, navigation, etc.)",
|
||||
"usage_guide_specialized": "usage_guide OPTIONAL for specialized components (can be simplified or omitted)",
|
||||
"code_snippets": "extraction_metadata.code_snippets ONLY present in Code Import mode"
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user