feat: Add Role Analysis Reviewer Agent and validation template

- Introduced Role Analysis Reviewer Agent to validate role analysis outputs against templates and quality standards. - Created a detailed validation ruleset for the system-architect role, including mandatory and recommended sections. - Added JSON validation report structure for output. - Implemented execution command for validation process. test: Add UX tests for HookCard component - Created comprehensive tests for HookCard component, focusing on delete confirmation UX pattern. - Verified confirmation dialog appearance, deletion functionality, and button interactions. - Ensured proper handling of state updates and visual feedback for enabled/disabled status. test: Add UX tests for ThemeSelector component - Developed tests for ThemeSelector component, emphasizing delete confirmation UX pattern. - Validated confirmation dialog display, deletion actions, and toast notifications for undo functionality. - Ensured proper management of theme slots and state updates. feat: Implement useDebounce hook - Added useDebounce hook to delay expensive computations or API calls, enhancing performance. feat: Create System Architect Analysis Template - Developed a comprehensive template for system architect role analysis, covering required sections such as architecture overview, data model, state machine, error handling strategy, observability requirements, configuration model, and boundary scenarios. - Included examples and templates for each section to guide users in producing SPEC.md-level precision modeling.
2026-03-07 16:41:06 +08:00 · 2026-03-05 19:58:10 +08:00
parent bc7a556985
commit 3fd55ebd4b
55 changed files with 4262 additions and 1138 deletions
--- a/.claude/skills/brainstorm/README.md
+++ b/.claude/skills/brainstorm/README.md
@@ -0,0 +1,177 @@
+# Brainstorm Skill
+
+Unified brainstorming skill combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis into a single entry point with two operational modes.
+
+## Key Features
+
+- **Dual-Mode Operation**: Auto mode (full pipeline) and single role mode (individual analysis)
+- **Interactive Framework Generation**: Seven-phase workflow for guidance specification
+- **Parallel Role Analysis**: Concurrent execution of multiple role perspectives
+- **Cross-Role Synthesis**: Integration of insights into feature specifications
+- **SPEC.md Quality Standards**: Guidance specification includes Concepts & Terminology, Non-Goals, RFC 2119 constraints
+- **Template-Driven Role Analysis**: system-architect produces Data Model, State Machine, Error Handling, Observability, Configuration Model, Boundary Scenarios
+- **Automated Quality Gates**: Validation agents ensure outputs meet quality standards
+- **Session Continuity**: All phases share state via workflow-session.json
+- **Progressive Loading**: Phase documents loaded on-demand via Ref markers
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    /brainstorm                                │
+│         Unified Entry Point + Interactive Routing             │
+└───────────────────────┬─────────────────────────────────────┘
+                        │
+              ┌─────────┴─────────┐
+              ↓                   ↓
+    ┌─────────────────┐  ┌──────────────────┐
+    │   Auto Mode     │  │ Single Role Mode │
+    │  (自动模式)      │  │ (单角色分析模式)   │
+    └────────┬────────┘  └────────┬─────────┘
+             │                    │
+    ┌────────┼────────┐          │
+    ↓        ↓        ↓          ↓
+ Phase 2  Phase 3  Phase 4    Phase 3
+Artifacts  N×Role  Synthesis  1×Role
+ (7步)    Analysis  (8步)    Analysis
+           并行               (4步)
+```
+
+### Execution Flow
+
+**Auto Mode**:
+1. **Phase 1**: Mode detection and parameter parsing
+2. **Phase 1.5**: Terminology & Boundary Definition (extract terms, collect Non-Goals)
+3. **Phase 2**: Interactive Framework Generation (7 sub-phases)
+   - Context collection → Topic analysis → Role selection → Role questions → Conflict resolution → Final check → Generate specification
+   - **Phase 5**: Generate guidance-specification.md with Concepts & Terminology, Non-Goals, RFC 2119 constraints
+4. **Phase 3**: Parallel Role Analysis (N concurrent role analyses)
+   - Template-driven analysis with quality validation
+   - system-architect includes: Data Model, State Machine, Error Handling, Observability, Configuration Model, Boundary Scenarios
+5. **Phase 4**: Synthesis Integration (6 sub-phases)
+   - Discovery → File discovery → Cross-role analysis → User interaction → Spec generation → Finalization
+
+**Single Role Mode**:
+1. **Phase 1**: Mode detection and parameter parsing
+2. **Phase 3**: Single role analysis (4 sub-phases)
+   - Detection → Context → Agent → Validation
+
+## Usage
+
+### Auto Mode
+
+```bash
+# Full pipeline with default settings
+/brainstorm "Build real-time collaboration platform"
+
+# Auto-select mode with specific role count
+/brainstorm -y "GOAL: Build platform SCOPE: 100 users" --count 5
+
+# With style skill for UI designer
+/brainstorm "Design payment system" --style-skill material-design
+```
+
+### Single Role Mode
+
+```bash
+# Analyze with specific role
+/brainstorm system-architect --session WFS-xxx
+
+# With interactive questions
+/brainstorm ux-expert --include-questions
+
+# Update existing analysis
+/brainstorm ui-designer --session WFS-xxx --update --style-skill material-design
+
+# Skip questions (use defaults)
+/brainstorm product-manager --skip-questions
+```
+
+## Available Roles
+
+| Role ID | Title | Focus Area |
+|---------|-------|------------|
+| `data-architect` | 数据架构师 | Data models, storage strategies, data flow |
+| `product-manager` | 产品经理 | Product strategy, roadmap, prioritization |
+| `product-owner` | 产品负责人 | Backlog management, user stories, acceptance criteria |
+| `scrum-master` | 敏捷教练 | Process facilitation, impediment removal |
+| `subject-matter-expert` | 领域专家 | Domain knowledge, business rules, compliance |
+| `system-architect` | 系统架构师 | Technical architecture, scalability, integration |
+| `test-strategist` | 测试策略师 | Test strategy, quality assurance |
+| `ui-designer` | UI设计师 | Visual design, mockups, design systems |
+| `ux-expert` | UX专家 | User research, information architecture, journey |
+
+## Output Files
+
+```
+.workflow/active/WFS-{topic}/
+├── workflow-session.json              # Session metadata
+├── .process/
+│   └── context-package.json           # Phase 0 output
+└── .brainstorming/
+    ├── guidance-specification.md      # Framework with terminology, non-goals
+    ├── feature-index.json             # Feature index
+    ├── synthesis-changelog.md         # Synthesis decisions
+    ├── feature-specs/                 # Feature specifications
+    │   ├── F-001-{slug}.md
+    │   └── F-00N-{slug}.md
+    ├── specs/
+    │   └── terminology-template.json  # Terminology glossary schema
+    ├── templates/
+    │   └── role-templates/
+    │       └── system-architect-template.md  # System architect analysis template
+    ├── agents/
+    │   └── role-analysis-reviewer-agent.md   # Role analysis validation agent
+    ├── {role}/                        # Role analyses (immutable)
+    │   ├── {role}-context.md          # Q&A responses
+    │   ├── analysis.md                # Main document
+    │   ├── analysis-cross-cutting.md  # Cross-feature
+    │   └── analysis-F-{id}-{slug}.md  # Per-feature
+    └── synthesis-specification.md     # Integration
+```
+
+## Quality Standards
+
+### Guidance Specification
+- **Section 2**: Concepts & Terminology (5-10 core terms with definitions, aliases, categories)
+- **Section 3**: Non-Goals (Out of Scope) with rationale
+- **RFC 2119 Keywords**: All requirements use MUST, SHOULD, MAY
+
+### Role Analysis (system-architect)
+1. **Architecture Overview**: High-level system design
+2. **Data Model**: 3-5 core entities with precise field definitions
+3. **State Machine**: Lifecycle for 1-2 entities with complex workflows
+4. **Error Handling Strategy**: Global + per-component recovery
+5. **Observability Requirements**: Metrics, logs, health checks
+6. **Configuration Model**: All configurable parameters with validation
+7. **Boundary Scenarios**: Concurrency, rate limiting, shutdown, cleanup, scalability, DR
+
+### Quality Validation
+- Template compliance checking
+- RFC 2119 keyword usage verification
+- Diagram syntax validation
+- Section completeness scoring
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `--yes`, `-y` | Auto mode, skip all questions | - |
+| `--count N` | Number of roles to select | 3 |
+| `--session ID` | Use existing session | - |
+| `--update` | Update existing analysis | - |
+| `--include-questions` | Interactive context gathering | - |
+| `--skip-questions` | Use default answers | - |
+| `--style-skill PKG` | Style package for ui-designer | - |
+
+## Follow-up Commands
+
+After brainstorm completes:
+- `/workflow-plan --session {sessionId}` - Generate implementation plan
+- `/workflow:brainstorm:synthesis --session {sessionId}` - Run synthesis standalone
+
+## Related Documentation
+
+- **Template Source**: `~/.ccw/workflows/cli-templates/planning-roles/`
+- **Style SKILL Packages**: `.claude/skills/style-{package-name}/`
+- **Phase Documents**: `phases/01-mode-routing.md`, `phases/02-artifacts.md`, `phases/03-role-analysis.md`, `phases/04-synthesis.md`
--- a/.claude/skills/brainstorm/SKILL.md
+++ b/.claude/skills/brainstorm/SKILL.md
@@ -49,6 +49,9 @@ Single Role Mode:
 3. **Task Attachment/Collapse**: Sub-tasks attached during phase execution, collapsed after completion
 4. **Session Continuity**: All phases share session state via workflow-session.json
 5. **Auto-Continue Execution**: Phases chain automatically without user intervention between them
+6. **SPEC.md Quality Alignment**: Guidance specification and role analysis follow SPEC.md standards (Concepts & Terminology, Non-Goals, Data Model, State Machine, RFC 2119 constraints)
+7. **Template-Driven Analysis**: Role-specific templates (e.g., system-architect) ensure consistent, high-quality outputs
+8. **Quality Gates**: Automated validation of guidance specification and role analysis against quality standards

 ## Auto Mode

@@ -73,13 +76,19 @@ Parse arguments, detect mode from flags/parameters, or ask user via AskUserQuest

 ### Auto Mode Execution (execution_mode = "auto")

+**Phase 1.5: Terminology & Boundary Definition**
+   - Extract 5-10 core domain terms from user input and Phase 1 context
+   - Generate terminology table (term, definition, aliases, category)
+   - Collect Non-Goals via AskUserQuestion (明确排除的范围)
+   - Store to `session.terminology` and `session.non_goals`
+
 #### Phase 2: Interactive Framework Generation
   Ref: phases/02-artifacts.md

 Seven-phase interactive workflow: Context collection → Topic analysis → Role selection → Role questions → Conflict resolution → Final check → Generate specification.

 **Input**: topic description, --count N, --yes flag
-**Output**: guidance-specification.md, workflow-session.json (selected_roles[], session_id)
+**Output**: guidance-specification.md (with Concepts & Terminology, Non-Goals, RFC 2119 constraints), workflow-session.json (selected_roles[], session_id)

 **TodoWrite**: Attach 7 sub-tasks (Phase 0-5), execute sequentially, collapse on completion.

@@ -95,6 +104,16 @@ Execute role analysis for EACH selected role in parallel.

 For ui-designer: append `--style-skill {package}` if provided.

+**Template-Driven Analysis**:
+- Load role-specific template if exists (e.g., `templates/role-templates/system-architect-template.md`)
+- Inject template into agent prompt as required structure
+- For system-architect: MUST include Data Model, State Machine, Error Handling, Observability, Configuration Model, Boundary Scenarios
+
+**Quality Validation**:
+- After analysis generation, invoke `role-analysis-reviewer-agent` to validate against template
+- Check MUST have sections (blocking), SHOULD have sections (warning), quality checks (RFC keywords, valid diagrams)
+- Output validation report with score and recommendations
+
 **TodoWrite**: Attach N parallel sub-tasks, execute concurrently, collapse on completion.

 #### Phase 4: Synthesis Integration
@@ -327,6 +346,13 @@ Initial → Phase 1 Mode Routing (completed)
    ├── feature-specs/                 # Feature specs (Phase 4, auto mode, feature_mode)
    │   ├── F-001-{slug}.md
    │   └── F-00N-{slug}.md
+    ├── specs/
+    │   └── terminology-template.json  # Terminology schema
+    ├── templates/
+    │   └── role-templates/
+    │       └── system-architect-template.md  # System architect analysis template
+    ├── agents/
+    │   └── role-analysis-reviewer-agent.md   # Role analysis validation agent
    ├── {role}/                        # Role analyses (IMMUTABLE after Phase 3)
    │   ├── {role}-context.md          # Interactive Q&A responses
    │   ├── analysis.md                # Main/index document
--- a/.claude/skills/brainstorm/phases/02-artifacts.md
+++ b/.claude/skills/brainstorm/phases/02-artifacts.md
@@ -117,6 +117,73 @@ AskUserQuestion({

 **⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation.

+### Phase 1.5: Terminology & Boundary Definition
+
+**Goal**: Extract core terminology and define scope boundaries (Non-Goals)
+
+**Steps**:
+1. Analyze Phase 1 user responses and topic description
+2. Extract 5-10 core domain terms that will be used throughout the specification
+3. Generate terminology clarification questions if needed
+4. Define scope boundaries by identifying what is explicitly OUT of scope
+
+**Terminology Extraction**:
+```javascript
+// Based on Phase 1 context and user input
+const coreTerms = extractTerminology({
+  topic: session.topic,
+  userResponses: session.intent_context,
+  contextPackage: contextPackage // from Phase 0
+});
+
+// Generate terminology table
+const terminologyTable = coreTerms.map(term => ({
+  term: term.canonical,
+  definition: term.definition,
+  aliases: term.alternatives,
+  category: term.category // core|technical|business
+}));
+```
+
+**Non-Goals Definition**:
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "以下哪些是明确 NOT 包含在本次项目范围内的？（可多选）",
+    header: "范围边界 (Non-Goals)",
+    multiSelect: true,
+    options: [
+      { label: "移动端应用", description: "本次只做 Web 端，移动端后续考虑" },
+      { label: "多语言支持", description: "MVP 阶段只支持中文" },
+      { label: "第三方集成", description: "暂不集成外部系统" },
+      { label: "高级分析功能", description: "基础功能优先，分析功能 v2" },
+      { label: "其他（请在后续补充）", description: "用户自定义排除项" }
+    ]
+  }]
+});
+
+// If user selects "其他", follow up with:
+if (selectedNonGoals.includes("其他")) {
+  AskUserQuestion({
+    questions: [{
+      question: "请描述其他明确排除的功能或范围",
+      header: "补充 Non-Goals",
+      multiSelect: false,
+      freeText: true
+    }]
+  });
+}
+
+// Store to session
+session.terminology = terminologyTable;
+session.non_goals = selectedNonGoals.map(ng => ({
+  item: ng.label,
+  rationale: ng.description
+}));
+```
+
+**Output**: Updated `workflow-session.json` with `terminology` and `non_goals` fields
+
 ### Phase 2: Role Selection

 **Goal**: User selects roles from intelligent recommendations
@@ -303,11 +370,26 @@ After final clarification, extract implementable feature units from all Phase 1-
 ### Phase 5: Generate Specification

 **Steps**:
-1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` + `additional_decisions` + `feature_list`
+1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` + `additional_decisions` + `feature_list` + `terminology` + `non_goals`
 2. Transform Q&A to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements
-3. Generate `guidance-specification.md`
-4. Update `workflow-session.json` (metadata only)
-5. Validate: No interrogative sentences, all decisions traceable
+3. Apply RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT) to all behavioral requirements
+4. Generate `guidance-specification.md` with Concepts & Terminology and Non-Goals sections
+5. Update `workflow-session.json` (metadata only)
+6. Validate: No interrogative sentences, all decisions traceable, RFC keywords applied
+
+**RFC 2119 Compliance**:
+
+All behavioral requirements and constraints MUST be expressed using RFC 2119 keywords:
+- **MUST**: Absolute requirement, non-negotiable
+- **MUST NOT**: Absolute prohibition
+- **SHOULD**: Strong recommendation, may be ignored with valid reason
+- **SHOULD NOT**: Strong discouragement
+- **MAY**: Optional, implementer's choice
+
+Example transformations:
+- "用户需要登录" → "The system MUST authenticate users before granting access"
+- "建议使用缓存" → "The system SHOULD cache frequently accessed data"
+- "可以支持 OAuth" → "The system MAY support OAuth2 authentication"

 ## Question Guidelines

@@ -366,15 +448,43 @@ for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) {
 **CONFIRMED Objectives**: [from topic + Phase 1]
 **CONFIRMED Success Criteria**: [from Phase 1 answers]

-## 2-N. [Role] Decisions
+## 2. Concepts & Terminology
+
+**Core Terms**: The following terms are used consistently throughout this specification.
+
+| Term | Definition | Aliases | Category |
+|------|------------|---------|----------|
+${session.terminology.map(t => `| ${t.term} | ${t.definition} | ${t.aliases.join(', ')} | ${t.category} |`).join('\n')}
+
+**Usage Rules**:
+- All documents MUST use the canonical term
+- Aliases are for reference only
+- New terms introduced in role analysis MUST be added to this glossary
+
+## 3. Non-Goals (Out of Scope)
+
+The following are explicitly OUT of scope for this project:
+
+${session.non_goals.map(ng => `- **${ng.item}**: ${ng.rationale}`).join('\n')}
+
+**Rationale**: These exclusions help maintain focus on core objectives and prevent scope creep.
+
+## 4-N. [Role] Decisions
 ### SELECTED Choices
-**[Question topic]**: [User's answer]
+**[Question topic]**: [User's answer with RFC 2119 keywords]
 - **Rationale**: [From option description]
- **Impact**: [Implications]
+- **Impact**: [Implications with RFC keywords]
+- **Requirement Level**: [MUST/SHOULD/MAY based on criticality]
+
+**Example**:
+- The system MUST authenticate users within 200ms (P99)
+- The system SHOULD cache frequently accessed data
+- The system MAY support OAuth2 providers (Google, GitHub)

 ### Cross-Role Considerations
-**[Conflict resolved]**: [Resolution from Phase 4]
+**[Conflict resolved]**: [Resolution from Phase 4 with RFC keywords]
 - **Affected Roles**: [Roles involved]
+- **Decision**: [MUST/SHOULD/MAY statement]

 ## Cross-Role Integration
 **CONFIRMED Integration Points**: [API/Data/Auth from multiple roles]
--- a/.claude/skills/brainstorm/phases/03-role-analysis.md
+++ b/.claude/skills/brainstorm/phases/03-role-analysis.md
@@ -301,6 +301,14 @@ const agentContext = {
  original_topic: original_topic,
  session_id: session_id
 };
+
+// Load role-specific template if exists
+let roleTemplate = null;
+try {
+  roleTemplate = Read(`templates/role-templates/${role_name}-template.md`);
+} catch (e) {
+  // No template, use generic analysis
+}
 ```

 **Step 3.3.3: Execute Conceptual Planning Agent**
@@ -362,6 +370,13 @@ UPDATE_MODE: ${update_mode}
   - Command: Read(${brainstorm_dir}/${role_name}/${role_name}-context.md)
   - Output: user_context_answers

+${roleTemplate ? `
+5. **load_role_template**
+   - Action: Load role-specific analysis template
+   - Command: Read(templates/role-templates/${role_name}-template.md)
+   - Output: role_specific_template
+` : ''}
+
 5. **${update_mode ? 'load_existing_analysis' : 'skip'}**
   ${update_mode ? `
   - Action: Load existing analysis for incremental update
@@ -378,6 +393,21 @@ ${featureListBlock}
 **Role Focus**: ${roleConfig[role_name].focus_area}
 **Template Integration**: Apply role template guidelines within framework structure
 ${feature_mode ? `**Feature Organization**: Organize analysis by feature points - each feature gets its own sub-document. Cross-cutting concerns go into analysis-cross-cutting.md.` : ''}
+**RFC 2119 Compliance**: Use RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT) to define all behavioral constraints and recommendations. Every technical decision MUST be expressed with appropriate RFC keyword. Distinguish between absolute requirements (MUST) and recommendations (SHOULD).
+
+${roleTemplate ? `
+**ROLE-SPECIFIC TEMPLATE (MUST follow this structure)**:
+${roleTemplate}
+
+Your analysis MUST include all Required Sections from the template above.
+` : ''}
+
+**For system-architect role specifically**:
+- MUST define Data Model for 3-5 core entities with fields, types, constraints, relationships
+- MUST create State Machine for at least 1 entity with complex lifecycle (ASCII diagram + transition table)
+- MUST define Error Handling Strategy with error classification and recovery mechanisms
+- MUST specify Observability Requirements with metrics (at least 5), log events, and health checks
+- All constraints MUST use RFC 2119 keywords (MUST, SHOULD, MAY)

 ## Expected Deliverables
 ${feature_mode ? `
--- a/.claude/skills/brainstorm/phases/04-synthesis.md
+++ b/.claude/skills/brainstorm/phases/04-synthesis.md
@@ -531,22 +531,32 @@ ${feature_mode ? `
 **Status**: Draft (from synthesis)

 ## 1. Requirements Summary
-[Consolidated requirements from all role perspectives]
- Functional requirements (from product-manager, product-owner)
- User experience requirements (from ux-expert, ui-designer)
- Technical requirements (from system-architect, data-architect, api-designer)
- Domain requirements (from subject-matter-expert)
+[Consolidated requirements from all role perspectives using RFC 2119 keywords]
+- Functional requirements (from product-manager, product-owner) - use MUST/SHOULD/MAY
+- User experience requirements (from ux-expert, ui-designer) - use MUST/SHOULD/MAY
+- Technical requirements (from system-architect, data-architect, api-designer) - use MUST/SHOULD/MAY
+- Domain requirements (from subject-matter-expert) - use MUST/SHOULD/MAY
+
+**Example**:
+- The feature MUST support user authentication via email/password
+- The UI SHOULD provide real-time feedback within 100ms
+- The system MAY cache user preferences for offline access

 ## 2. Design Decisions [CORE SECTION]
 [Key architectural and design decisions with rationale - 40%+ of word count]
 For each decision:
- **Decision**: [What was decided]
+- **Decision**: [What was decided - MUST use RFC 2119 keywords]
 - **Context**: [Why this decision was needed]
 - **Options Considered**: [Alternatives from different roles]
- **Chosen Approach**: [Selected option with rationale]
+- **Chosen Approach**: [Selected option with rationale using MUST/SHOULD/MAY]
 - **Trade-offs**: [What we gain vs. what we sacrifice]
 - **Source**: [Which role(s) drove this decision]

+**RFC 2119 Examples**:
+- "The system MUST authenticate users before granting access"
+- "The feature SHOULD cache frequently accessed data for performance"
+- "The component MAY support OAuth2 authentication as an optional enhancement"
+
 ## 3. Interface Contract
 [API endpoints, data models, component interfaces]
 - External interfaces (API contracts from api-designer)
--- a/.claude/skills/brainstorm/specs/terminology-template.json
+++ b/.claude/skills/brainstorm/specs/terminology-template.json
@@ -0,0 +1,22 @@
+{
+  "version": "1.0",
+  "description": "Terminology glossary schema for brainstorm guidance-specification",
+  "schema": {
+    "terminology": {
+      "type": "array",
+      "items": {
+        "term": "string (required) - canonical term",
+        "definition": "string (required) - concise definition",
+        "aliases": "array of strings - alternative names",
+        "category": "enum: core|technical|business (required)",
+        "first_used_in": "string - source document"
+      }
+    }
+  },
+  "validation_rules": {
+    "min_terms": 5,
+    "max_terms": 20,
+    "term_format": "lowercase, alphanumeric + hyphens",
+    "definition_max_length": 200
+  }
+}