codex-workflows 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/ai-development-guide/SKILL.md +283 -0
- package/.agents/skills/ai-development-guide/agents/openai.yaml +7 -0
- package/.agents/skills/ai-development-guide/references/frontend.md +135 -0
- package/.agents/skills/coding-rules/SKILL.md +98 -0
- package/.agents/skills/coding-rules/agents/openai.yaml +7 -0
- package/.agents/skills/coding-rules/references/typescript.md +220 -0
- package/.agents/skills/documentation-criteria/SKILL.md +127 -0
- package/.agents/skills/documentation-criteria/agents/openai.yaml +7 -0
- package/.agents/skills/documentation-criteria/references/adr-template.md +64 -0
- package/.agents/skills/documentation-criteria/references/design-template.md +327 -0
- package/.agents/skills/documentation-criteria/references/plan-template.md +131 -0
- package/.agents/skills/documentation-criteria/references/prd-template.md +119 -0
- package/.agents/skills/documentation-criteria/references/task-template.md +38 -0
- package/.agents/skills/documentation-criteria/references/ui-spec-template.md +145 -0
- package/.agents/skills/implementation-approach/SKILL.md +145 -0
- package/.agents/skills/implementation-approach/agents/openai.yaml +7 -0
- package/.agents/skills/integration-e2e-testing/SKILL.md +125 -0
- package/.agents/skills/integration-e2e-testing/agents/openai.yaml +7 -0
- package/.agents/skills/integration-e2e-testing/references/e2e-design.md +86 -0
- package/.agents/skills/recipe-add-integration-tests/SKILL.md +128 -0
- package/.agents/skills/recipe-add-integration-tests/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-build/SKILL.md +119 -0
- package/.agents/skills/recipe-build/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-design/SKILL.md +90 -0
- package/.agents/skills/recipe-design/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-diagnose/SKILL.md +187 -0
- package/.agents/skills/recipe-diagnose/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-front-build/SKILL.md +127 -0
- package/.agents/skills/recipe-front-build/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-front-design/SKILL.md +90 -0
- package/.agents/skills/recipe-front-design/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-front-plan/SKILL.md +68 -0
- package/.agents/skills/recipe-front-plan/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-front-review/SKILL.md +101 -0
- package/.agents/skills/recipe-front-review/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-fullstack-build/SKILL.md +139 -0
- package/.agents/skills/recipe-fullstack-build/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-fullstack-implement/SKILL.md +151 -0
- package/.agents/skills/recipe-fullstack-implement/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-implement/SKILL.md +125 -0
- package/.agents/skills/recipe-implement/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-plan/SKILL.md +73 -0
- package/.agents/skills/recipe-plan/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-reverse-engineer/SKILL.md +212 -0
- package/.agents/skills/recipe-reverse-engineer/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-review/SKILL.md +115 -0
- package/.agents/skills/recipe-review/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-task/SKILL.md +74 -0
- package/.agents/skills/recipe-task/agents/openai.yaml +7 -0
- package/.agents/skills/recipe-update-doc/SKILL.md +156 -0
- package/.agents/skills/recipe-update-doc/agents/openai.yaml +7 -0
- package/.agents/skills/subagents-orchestration-guide/SKILL.md +354 -0
- package/.agents/skills/subagents-orchestration-guide/agents/openai.yaml +7 -0
- package/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md +124 -0
- package/.agents/skills/task-analyzer/SKILL.md +142 -0
- package/.agents/skills/task-analyzer/agents/openai.yaml +7 -0
- package/.agents/skills/task-analyzer/references/skills-index.yaml +162 -0
- package/.agents/skills/testing/SKILL.md +324 -0
- package/.agents/skills/testing/agents/openai.yaml +7 -0
- package/.agents/skills/testing/references/typescript.md +224 -0
- package/.codex/agents/acceptance-test-generator.toml +310 -0
- package/.codex/agents/code-reviewer.toml +228 -0
- package/.codex/agents/code-verifier.toml +231 -0
- package/.codex/agents/design-sync.toml +265 -0
- package/.codex/agents/document-reviewer.toml +367 -0
- package/.codex/agents/integration-test-reviewer.toml +178 -0
- package/.codex/agents/investigator.toml +197 -0
- package/.codex/agents/prd-creator.toml +250 -0
- package/.codex/agents/quality-fixer-frontend.toml +356 -0
- package/.codex/agents/quality-fixer.toml +249 -0
- package/.codex/agents/requirement-analyzer.toml +172 -0
- package/.codex/agents/rule-advisor.toml +186 -0
- package/.codex/agents/scope-discoverer.toml +248 -0
- package/.codex/agents/solver.toml +212 -0
- package/.codex/agents/task-decomposer.toml +262 -0
- package/.codex/agents/task-executor-frontend.toml +312 -0
- package/.codex/agents/task-executor.toml +314 -0
- package/.codex/agents/technical-designer-frontend.toml +492 -0
- package/.codex/agents/technical-designer.toml +474 -0
- package/.codex/agents/ui-spec-designer.toml +150 -0
- package/.codex/agents/verifier.toml +228 -0
- package/.codex/agents/work-planner.toml +251 -0
- package/README.md +365 -0
- package/bin/cli.js +249 -0
- package/package.json +35 -0
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# [Feature Name] UI Specification
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
[Purpose and scope of this UI Specification in 2-3 sentences]
|
|
6
|
+
|
|
7
|
+
### Target PRD
|
|
8
|
+
- PRD path: [docs/prd/xxx-prd.md | "N/A -- based on requirement-analyzer output"]
|
|
9
|
+
- Feature scope: [Which PRD requirements this UI Spec covers | Summary of analyzed requirements]
|
|
10
|
+
|
|
11
|
+
### Design Source
|
|
12
|
+
| Source | Path | Version |
|
|
13
|
+
|--------|------|---------|
|
|
14
|
+
| Prototype code | [docs/ui-spec/assets/xxx/] | [commit SHA / tag] |
|
|
15
|
+
|
|
16
|
+
## Prototype Management
|
|
17
|
+
|
|
18
|
+
Prototype code is an **attachment** to this UI Spec. The canonical specification is always this document + the Design Doc.
|
|
19
|
+
|
|
20
|
+
- **Attachment path**: [docs/ui-spec/assets/{feature-name}/]
|
|
21
|
+
- **Version identification**: [commit SHA / tag]
|
|
22
|
+
- **Compliance premise**: [e.g., design system compliance, component library usage]
|
|
23
|
+
- **Relationship to canonical spec**: Differences between prototype and this spec are resolved in favor of this document. Prototype serves as visual/behavioral reference only.
|
|
24
|
+
|
|
25
|
+
## AC Traceability (Prototype)
|
|
26
|
+
|
|
27
|
+
Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided.
|
|
28
|
+
|
|
29
|
+
| AC ID | AC Summary | Screen / State | Prototype Reference (element ID / path) | Adoption Decision |
|
|
30
|
+
|-------|-----------|----------------|----------------------------------------|-------------------|
|
|
31
|
+
| AC-01 | [EARS AC summary] | [Screen / state name] | [element or file reference] | Adopted / Not adopted / On hold |
|
|
32
|
+
|
|
33
|
+
## Screen List and Transitions
|
|
34
|
+
|
|
35
|
+
### Screen List
|
|
36
|
+
|
|
37
|
+
| Screen ID | Screen Name | Description | Entry Condition |
|
|
38
|
+
|-----------|------------|-------------|-----------------|
|
|
39
|
+
| S-01 | [Screen name] | [Purpose] | [How user reaches this screen] |
|
|
40
|
+
|
|
41
|
+
### Transition Conditions
|
|
42
|
+
|
|
43
|
+
| Source | Destination | Trigger | Guard Condition |
|
|
44
|
+
|--------|------------|---------|-----------------|
|
|
45
|
+
| S-01 | S-02 | [User action] | [Precondition if any] |
|
|
46
|
+
|
|
47
|
+
## Component Decomposition
|
|
48
|
+
|
|
49
|
+
### Component Tree
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
[Page/Screen]
|
|
53
|
+
+-- [Container Component]
|
|
54
|
+
| +-- [Presentational Component A]
|
|
55
|
+
| +-- [Presentational Component B]
|
|
56
|
+
+-- [Container Component]
|
|
57
|
+
+-- [Presentational Component C]
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Component: [ComponentName]
|
|
61
|
+
|
|
62
|
+
#### State x Display Matrix
|
|
63
|
+
|
|
64
|
+
| State | Default | Loading | Empty | Error | Partial |
|
|
65
|
+
|-------|---------|---------|-------|-------|---------|
|
|
66
|
+
| Display | [Normal display] | [Skeleton / spinner] | [Empty state + CTA] | [Error message + recovery action] | [Cached / partial display] |
|
|
67
|
+
|
|
68
|
+
#### Interaction Definition
|
|
69
|
+
|
|
70
|
+
| AC ID | EARS Condition | User Action | System Response | State Transition | Error Handling |
|
|
71
|
+
|-------|---------------|-------------|-----------------|-----------------|----------------|
|
|
72
|
+
| AC-01 | When [trigger] | [Click / input / etc.] | [Expected behavior] | [From state -> To state] | [Retry / Reset / Fallback] |
|
|
73
|
+
|
|
74
|
+
### Component: [ComponentName2]
|
|
75
|
+
|
|
76
|
+
[Repeat State x Display Matrix and Interaction Definition for each component]
|
|
77
|
+
|
|
78
|
+
## Design Tokens and Component Map
|
|
79
|
+
|
|
80
|
+
### Environment Constraints
|
|
81
|
+
- Target browsers: [e.g., Chrome 120+, Safari 17+]
|
|
82
|
+
- Responsive breakpoints: [e.g., 768px, 1024px, 1280px]
|
|
83
|
+
- Theme support: [e.g., light/dark, system preference]
|
|
84
|
+
|
|
85
|
+
### Existing Component Reuse Map
|
|
86
|
+
|
|
87
|
+
| UI Element | Decision | Existing Component | Notes |
|
|
88
|
+
|-----------|----------|-------------------|-------|
|
|
89
|
+
| [Button] | Reuse | [components/ui/Button] | [No modifications needed] |
|
|
90
|
+
| [DataTable] | Extend | [components/ui/Table] | [Add sorting support] |
|
|
91
|
+
| [FeatureCard] | New | - | [No similar component exists] |
|
|
92
|
+
|
|
93
|
+
### Design Tokens
|
|
94
|
+
|
|
95
|
+
| Token | Value | Usage |
|
|
96
|
+
|-------|-------|-------|
|
|
97
|
+
| [color-primary] | [value] | [Primary actions] |
|
|
98
|
+
| [spacing-md] | [value] | [Component spacing] |
|
|
99
|
+
|
|
100
|
+
## Visual Acceptance
|
|
101
|
+
|
|
102
|
+
### Golden States
|
|
103
|
+
Define the key visual states that serve as acceptance benchmarks:
|
|
104
|
+
|
|
105
|
+
1. **[State name]**: [Description of what should be visually confirmed]
|
|
106
|
+
2. **[State name]**: [Description]
|
|
107
|
+
|
|
108
|
+
### Layout Constraints
|
|
109
|
+
- [Min/max width, height constraints]
|
|
110
|
+
- [Spacing rules between components]
|
|
111
|
+
- [Overflow behavior]
|
|
112
|
+
|
|
113
|
+
## Accessibility Requirements
|
|
114
|
+
|
|
115
|
+
### Keyboard Navigation
|
|
116
|
+
|
|
117
|
+
| Component | Tab Order | Key Binding | Behavior |
|
|
118
|
+
|-----------|-----------|-------------|----------|
|
|
119
|
+
| [Component] | [Order number] | [Enter / Space / Arrow] | [Expected behavior] |
|
|
120
|
+
|
|
121
|
+
### Screen Reader
|
|
122
|
+
|
|
123
|
+
| Component | Role | Accessible Name | Live Region |
|
|
124
|
+
|-----------|------|-----------------|-------------|
|
|
125
|
+
| [Component] | [ARIA role] | [aria-label / aria-labelledby] | [polite / assertive / none] |
|
|
126
|
+
|
|
127
|
+
### Contrast Requirements
|
|
128
|
+
|
|
129
|
+
| Element | Foreground | Background | Ratio Target |
|
|
130
|
+
|---------|-----------|------------|-------------|
|
|
131
|
+
| [Text element] | [Color] | [Color] | [4.5:1 for normal text / 3:1 for large text] |
|
|
132
|
+
|
|
133
|
+
## Open Items
|
|
134
|
+
|
|
135
|
+
| ID | Description | Owner | Deadline |
|
|
136
|
+
|----|-------------|-------|----------|
|
|
137
|
+
| TBD-01 | [Unresolved question or decision] | [Who resolves] | [Target date] |
|
|
138
|
+
|
|
139
|
+
*All TBDs must have an owner and deadline. Resolve before Design Doc creation.*
|
|
140
|
+
|
|
141
|
+
## Update History
|
|
142
|
+
|
|
143
|
+
| Date | Version | Changes | Author |
|
|
144
|
+
|------|---------|---------|--------|
|
|
145
|
+
| YYYY-MM-DD | 1.0 | Initial version | [Name] |
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: implementation-approach
|
|
3
|
+
description: "Implementation strategy selection framework with meta-cognitive approach. Use when: planning implementation strategy, selecting between vertical/horizontal slicing, or defining verification criteria for tasks."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Implementation Strategy Selection Framework (Meta-cognitive Approach)
|
|
7
|
+
|
|
8
|
+
## Meta-cognitive Strategy Selection Process [MANDATORY]
|
|
9
|
+
|
|
10
|
+
### Phase 1: Comprehensive Current State Analysis
|
|
11
|
+
|
|
12
|
+
**Core Question**: "What does the existing implementation look like?"
|
|
13
|
+
|
|
14
|
+
#### Analysis Framework
|
|
15
|
+
```yaml
|
|
16
|
+
Architecture Analysis: Responsibility separation, data flow, dependencies, technical debt
|
|
17
|
+
Implementation Quality Assessment: Code quality, test coverage, performance, security
|
|
18
|
+
Historical Context Understanding: Current form rationale, past decision validity, constraint changes, requirement evolution
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
#### Meta-cognitive Question List [MANDATORY CHECKPOINTS]
|
|
22
|
+
- What is the true responsibility of this implementation?
|
|
23
|
+
- Which parts are business essence and which derive from technical constraints?
|
|
24
|
+
- What dependencies or implicit preconditions are unclear from the code?
|
|
25
|
+
- What benefits and constraints does the current design bring?
|
|
26
|
+
|
|
27
|
+
**ENFORCEMENT**: CANNOT proceed to Phase 2 without answering all questions
|
|
28
|
+
|
|
29
|
+
### Phase 2: Strategy Exploration and Creation
|
|
30
|
+
|
|
31
|
+
**Core Question**: "When determining before to after, what implementation patterns or strategies should be referenced?"
|
|
32
|
+
|
|
33
|
+
#### Strategy Discovery Process
|
|
34
|
+
```yaml
|
|
35
|
+
Research and Exploration: Tech stack examples, similar projects, OSS references, literature/blogs
|
|
36
|
+
Creative Thinking: Strategy combinations, constraint-based design, phase division, extension point design
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
#### Reference Strategy Patterns (Creative Combinations Encouraged)
|
|
40
|
+
|
|
41
|
+
**Legacy Handling Strategies**:
|
|
42
|
+
- Strangler Pattern: Gradual migration through phased replacement
|
|
43
|
+
- Facade Pattern: Complexity hiding through unified interface
|
|
44
|
+
- Adapter Pattern: Bridge with existing systems
|
|
45
|
+
|
|
46
|
+
**New Development Strategies**:
|
|
47
|
+
- Feature-driven Development: Vertical implementation prioritizing user value
|
|
48
|
+
- Foundation-driven Development: Foundation-first construction prioritizing stability
|
|
49
|
+
- Risk-driven Development: Prioritize addressing maximum risk elements
|
|
50
|
+
|
|
51
|
+
**Integration/Migration Strategies**:
|
|
52
|
+
- Proxy Pattern: Transparent feature extension
|
|
53
|
+
- Decorator Pattern: Phased enhancement of existing features
|
|
54
|
+
- Bridge Pattern: Flexibility through abstraction
|
|
55
|
+
|
|
56
|
+
**IMPORTANT**: The optimal solution is discovered through creative thinking according to each project's context. EVALUATE multiple strategy combinations before selecting.
|
|
57
|
+
|
|
58
|
+
### Phase 3: Risk Assessment and Control [MANDATORY]
|
|
59
|
+
|
|
60
|
+
**Core Question**: "What risks arise when applying this to existing implementation, and what's the best way to control them?"
|
|
61
|
+
|
|
62
|
+
#### Risk Analysis Matrix
|
|
63
|
+
```yaml
|
|
64
|
+
Technical Risks: System impact, data consistency, performance degradation, integration complexity
|
|
65
|
+
Operational Risks: Service availability, deployment downtime, process changes, rollback procedures
|
|
66
|
+
Project Risks: Schedule delays, learning costs, quality achievement, team coordination
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
#### Risk Control Strategies
|
|
70
|
+
```yaml
|
|
71
|
+
Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup
|
|
72
|
+
Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Phase 4: Constraint Compatibility Verification
|
|
76
|
+
|
|
77
|
+
**Core Question**: "What are this project's constraints?"
|
|
78
|
+
|
|
79
|
+
#### Constraint Checklist
|
|
80
|
+
```yaml
|
|
81
|
+
Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets
|
|
82
|
+
Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods
|
|
83
|
+
Resource Constraints: Team/skills, work hours/systems, budget, external contracts
|
|
84
|
+
Business Constraints: Market launch timing, customer impact, regulatory compliance
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Phase 5: Implementation Approach Decision
|
|
88
|
+
|
|
89
|
+
Select optimal solution from basic implementation approaches (creative combinations encouraged):
|
|
90
|
+
|
|
91
|
+
#### Vertical Slice (Feature-driven)
|
|
92
|
+
**Characteristics**: Vertical implementation across all layers by feature unit
|
|
93
|
+
**Application Conditions**: Low inter-feature dependencies, output in user-usable form, changes needed across all architecture layers
|
|
94
|
+
**Verification Method**: End-user value delivery at each feature completion
|
|
95
|
+
|
|
96
|
+
#### Horizontal Slice (Foundation-driven)
|
|
97
|
+
**Characteristics**: Phased construction by architecture layer
|
|
98
|
+
**Application Conditions**: Foundation system stability important, multiple features depend on common foundation, layer-by-layer verification effective
|
|
99
|
+
**Verification Method**: Integrated operation verification when all foundation layers complete
|
|
100
|
+
|
|
101
|
+
#### Hybrid (Creative Combination)
|
|
102
|
+
**Characteristics**: Flexible combination according to project characteristics
|
|
103
|
+
**Application Conditions**: Unclear requirements, need to change approach per phase, transition from prototyping to full implementation
|
|
104
|
+
**Verification Method**: Verify at appropriate L1/L2/L3 levels according to each phase's goals
|
|
105
|
+
|
|
106
|
+
### Phase 6: Decision Rationale Documentation
|
|
107
|
+
|
|
108
|
+
**Design Doc Documentation**: Clearly specify implementation strategy selection reasons and rationale.
|
|
109
|
+
|
|
110
|
+
## Verification Level Definitions
|
|
111
|
+
|
|
112
|
+
Priority for completion verification of each task:
|
|
113
|
+
|
|
114
|
+
- **L1: Functional Operation Verification** - Operates as end-user feature (e.g., search executable)
|
|
115
|
+
- **L2: Test Operation Verification** - New tests added and passing
|
|
116
|
+
- **L3: Build Success Verification** - Code builds/runs without errors
|
|
117
|
+
|
|
118
|
+
**Priority**: L1 > L2 > L3 in order of verifiability importance
|
|
119
|
+
|
|
120
|
+
## Integration Point Definitions
|
|
121
|
+
|
|
122
|
+
Define integration points according to selected strategy:
|
|
123
|
+
- **Strangler-based**: When switching between old and new systems for each feature
|
|
124
|
+
- **Feature-driven**: When users can actually use the feature
|
|
125
|
+
- **Foundation-driven**: When all architecture layers are ready and E2E tests pass
|
|
126
|
+
- **Hybrid**: When individual goals defined for each phase are achieved
|
|
127
|
+
|
|
128
|
+
## Anti-patterns [MANDATORY to detect]
|
|
129
|
+
|
|
130
|
+
- **Pattern Fixation**: EVALUATE unique combinations instead of selecting only listed strategies
|
|
131
|
+
- **Insufficient Analysis**: MUST complete Phase 1 analysis framework before strategy selection
|
|
132
|
+
- **Risk Neglect**: MUST complete Phase 3 risk analysis matrix before implementation
|
|
133
|
+
- **Constraint Ignorance**: MUST check Phase 4 constraint checklist before deciding strategy
|
|
134
|
+
- **Rationale Omission**: MUST use Phase 6 documentation template when selecting strategy
|
|
135
|
+
|
|
136
|
+
**ENFORCEMENT**: Detecting ANY anti-pattern requires IMMEDIATE correction before proceeding
|
|
137
|
+
|
|
138
|
+
## Guidelines for Meta-cognitive Execution
|
|
139
|
+
|
|
140
|
+
1. **Leverage Known Patterns**: Use as starting point, then EVALUATE creative combinations
|
|
141
|
+
2. **Active Research**: Research implementation examples from similar tech stacks
|
|
142
|
+
3. **Apply 5 Whys**: Pursue root causes to grasp essence
|
|
143
|
+
4. **Multi-perspective Evaluation**: EVALUATE comprehensively from each Phase 1-4 perspective
|
|
144
|
+
5. **Creative Thinking**: EVALUATE sequential application of multiple strategies and designs leveraging project-specific constraints
|
|
145
|
+
6. **Clarify Decision Rationale**: Strategy selection rationale MUST be explicit in design documents
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: integration-e2e-testing
|
|
3
|
+
description: "Integration and E2E test design principles, ROI calculation, test skeleton specification, and review criteria. Use when: designing integration tests, E2E tests, generating test skeletons, or reviewing test quality."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Integration and E2E Testing Principles
|
|
7
|
+
|
|
8
|
+
## References
|
|
9
|
+
|
|
10
|
+
**E2E test design with Playwright**: See [references/e2e-design.md](references/e2e-design.md) for UI Spec-driven E2E test candidate selection and Playwright test architecture.
|
|
11
|
+
|
|
12
|
+
## Test Type Definition and Limits [MANDATORY]
|
|
13
|
+
|
|
14
|
+
| Test Type | Purpose | Scope | Limit per Feature | Implementation Timing |
|
|
15
|
+
|-----------|---------|-------|-------------------|----------------------|
|
|
16
|
+
| Integration | Verify component interactions | Partial system integration | MAX 3 | Created alongside implementation |
|
|
17
|
+
| E2E | Verify critical user journeys | Full system | MAX 1-2 | Executed in final phase only |
|
|
18
|
+
|
|
19
|
+
**ENFORCEMENT**: Exceeding test limits requires explicit justification
|
|
20
|
+
|
|
21
|
+
## Behavior-First Principle [MANDATORY]
|
|
22
|
+
|
|
23
|
+
### MUST Include (High ROI)
|
|
24
|
+
- Business logic correctness (calculations, state transitions, data transformations)
|
|
25
|
+
- Data integrity and persistence behavior
|
|
26
|
+
- User-visible functionality completeness
|
|
27
|
+
- Error handling behavior (what user sees/experiences)
|
|
28
|
+
|
|
29
|
+
### MUST Exclude (Low ROI in CI/CD)
|
|
30
|
+
- External service real connections — use contract/interface verification instead
|
|
31
|
+
- Performance metrics — non-deterministic, defer to load testing
|
|
32
|
+
- Implementation details — test observable behavior only
|
|
33
|
+
- UI layout specifics — test information availability instead
|
|
34
|
+
|
|
35
|
+
**ENFORCEMENT**: Test = User-observable behavior verifiable in isolated CI environment
|
|
36
|
+
|
|
37
|
+
## ROI Calculation
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
ROI Score = (Business Value x User Frequency + Legal Requirement x 10 + Defect Detection)
|
|
41
|
+
/ (Creation Cost + Execution Cost + Maintenance Cost)
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Cost Table
|
|
45
|
+
|
|
46
|
+
| Test Type | Create | Execute | Maintain | Total |
|
|
47
|
+
|-----------|--------|---------|----------|-------|
|
|
48
|
+
| Unit | 1 | 1 | 1 | 3 |
|
|
49
|
+
| Integration | 3 | 5 | 3 | 11 |
|
|
50
|
+
| E2E | 10 | 20 | 8 | 38 |
|
|
51
|
+
|
|
52
|
+
## Test Skeleton Specification [MANDATORY]
|
|
53
|
+
|
|
54
|
+
### Required Comment Patterns
|
|
55
|
+
|
|
56
|
+
Each test MUST include the following annotations:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
// AC: [Original acceptance criteria text]
|
|
60
|
+
// Behavior: [Trigger] -> [Process] -> [Observable Result]
|
|
61
|
+
// @category: core-functionality | integration | edge-case | e2e
|
|
62
|
+
// @dependency: none | [component names] | full-system
|
|
63
|
+
// @complexity: low | medium | high
|
|
64
|
+
// ROI: [score]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Verification Items (Optional)
|
|
68
|
+
|
|
69
|
+
When verification points need explicit enumeration:
|
|
70
|
+
```
|
|
71
|
+
// Verification items:
|
|
72
|
+
// - [Item 1]
|
|
73
|
+
// - [Item 2]
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## EARS Format Mapping
|
|
77
|
+
|
|
78
|
+
| EARS Keyword | Test Type | Generation Approach |
|
|
79
|
+
|--------------|-----------|---------------------|
|
|
80
|
+
| **When** | Event-driven | Trigger event -> verify outcome |
|
|
81
|
+
| **While** | State condition | Setup state -> verify behavior |
|
|
82
|
+
| **If-then** | Branch coverage | Both condition paths verified |
|
|
83
|
+
| (none) | Basic functionality | Direct invocation -> verify result |
|
|
84
|
+
|
|
85
|
+
## Test File Naming Convention
|
|
86
|
+
|
|
87
|
+
- Integration tests: `*.int.test.*` or `*.integration.test.*`
|
|
88
|
+
- E2E tests: `*.e2e.test.*`
|
|
89
|
+
|
|
90
|
+
The test runner or framework in the project determines the appropriate file extension.
|
|
91
|
+
|
|
92
|
+
## Review Criteria
|
|
93
|
+
|
|
94
|
+
### Skeleton and Implementation Consistency
|
|
95
|
+
|
|
96
|
+
| Check | Failure Condition |
|
|
97
|
+
|-------|-------------------|
|
|
98
|
+
| Behavior Verification | No assertion for "observable result" in skeleton |
|
|
99
|
+
| Verification Item Coverage | Listed items not all covered by assertions |
|
|
100
|
+
| Mock Boundary | Internal components mocked in integration test |
|
|
101
|
+
|
|
102
|
+
### Implementation Quality
|
|
103
|
+
|
|
104
|
+
| Check | Failure Condition |
|
|
105
|
+
|-------|-------------------|
|
|
106
|
+
| AAA Structure | Arrange/Act/Assert separation unclear |
|
|
107
|
+
| Independence | State sharing between tests, order dependency |
|
|
108
|
+
| Reproducibility | Date/random dependency, varying results |
|
|
109
|
+
| Readability | Test name doesn't match verification content |
|
|
110
|
+
|
|
111
|
+
## Quality Standards [MANDATORY]
|
|
112
|
+
|
|
113
|
+
### REQUIRED
|
|
114
|
+
- Each test MUST verify one behavior
|
|
115
|
+
- Clear AAA (Arrange-Act-Assert) structure
|
|
116
|
+
- No test interdependencies
|
|
117
|
+
- Deterministic execution
|
|
118
|
+
|
|
119
|
+
### PROHIBITED
|
|
120
|
+
- Testing implementation details — test observable behavior only
|
|
121
|
+
- Multiple behaviors per test — split into separate tests
|
|
122
|
+
- Shared mutable state — each test creates its own state
|
|
123
|
+
- Time-dependent assertions without mocking — use deterministic time
|
|
124
|
+
|
|
125
|
+
**ENFORCEMENT**: Tests violating ANY standard MUST be rewritten before merge
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# E2E Test Design with Playwright
|
|
2
|
+
|
|
3
|
+
## When to Create E2E Tests
|
|
4
|
+
|
|
5
|
+
E2E tests target **critical user journeys** that span multiple pages or require real browser interaction. Apply the same ROI framework from the parent skill -- only create E2E tests when ROI > 50.
|
|
6
|
+
|
|
7
|
+
### Candidate Sources
|
|
8
|
+
|
|
9
|
+
| Source | What to Extract |
|
|
10
|
+
|--------|----------------|
|
|
11
|
+
| **Design Doc ACs** | User journeys with EARS "When" keyword spanning multiple screens |
|
|
12
|
+
| **UI Spec Screen Transitions** | Multi-step flows (e.g., form wizard, checkout) |
|
|
13
|
+
| **UI Spec State x Display Matrix** | Error/empty/loading states requiring browser-level verification |
|
|
14
|
+
| **UI Spec Interaction Definitions** | Complex interactions (drag-drop, keyboard navigation, responsive behavior) |
|
|
15
|
+
|
|
16
|
+
### Selection Criteria
|
|
17
|
+
|
|
18
|
+
**Include** (high E2E ROI):
|
|
19
|
+
- Multi-page user journeys (login -> dashboard -> action -> confirmation)
|
|
20
|
+
- Flows requiring real browser APIs (navigation, cookies, localStorage)
|
|
21
|
+
- Accessibility verification requiring actual DOM rendering
|
|
22
|
+
- Responsive behavior across viewports
|
|
23
|
+
|
|
24
|
+
**Exclude** (use integration tests instead):
|
|
25
|
+
- Single-component state changes (use RTL)
|
|
26
|
+
- API response handling (use MSW + RTL)
|
|
27
|
+
- Pure data transformations
|
|
28
|
+
|
|
29
|
+
## UI Spec to E2E Test Mapping
|
|
30
|
+
|
|
31
|
+
When a UI Spec exists, use it as the primary source for E2E test design:
|
|
32
|
+
|
|
33
|
+
1. **Extract screen transitions** -> Each multi-step transition = 1 E2E candidate
|
|
34
|
+
2. **Check state x display matrix** -> Error states requiring navigation = E2E candidate
|
|
35
|
+
3. **Review interaction definitions** -> Browser-dependent interactions = E2E candidate
|
|
36
|
+
4. **Cross-reference with Design Doc ACs** -> Ensure E2E candidates map to acceptance criteria
|
|
37
|
+
|
|
38
|
+
### Mapping Template
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
Screen Transition: [Screen A] -> [Screen B] -> [Screen C]
|
|
42
|
+
AC Reference: AC-{id}
|
|
43
|
+
User Journey: [Description of what the user accomplishes]
|
|
44
|
+
Preconditions: [Auth state, data state]
|
|
45
|
+
Verification Points:
|
|
46
|
+
- [What to assert at each step]
|
|
47
|
+
E2E ROI Score: [calculated score]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Playwright Test Architecture
|
|
51
|
+
|
|
52
|
+
### Page Object Pattern
|
|
53
|
+
|
|
54
|
+
Organize browser interactions through page objects for maintainability:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
tests/
|
|
58
|
+
├── e2e/
|
|
59
|
+
│ ├── pages/ # Page objects
|
|
60
|
+
│ ├── fixtures/ # Test fixtures and helpers
|
|
61
|
+
│ └── *.e2e.test.ts # Test files
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Test Isolation
|
|
65
|
+
|
|
66
|
+
- Each test starts from a clean browser context
|
|
67
|
+
- No shared state between tests
|
|
68
|
+
- Use `beforeEach` for common setup (auth, navigation)
|
|
69
|
+
- Prefer `page.goto()` over in-test navigation for setup
|
|
70
|
+
|
|
71
|
+
### Viewport Testing
|
|
72
|
+
|
|
73
|
+
When UI Spec defines responsive behavior, test critical breakpoints:
|
|
74
|
+
|
|
75
|
+
| Breakpoint | Width | When to Test |
|
|
76
|
+
|-----------|-------|-------------|
|
|
77
|
+
| Mobile | 375px | If UI Spec defines mobile-specific interactions |
|
|
78
|
+
| Tablet | 768px | If UI Spec defines tablet layout differences |
|
|
79
|
+
| Desktop | 1280px | Default -- always test |
|
|
80
|
+
|
|
81
|
+
## Budget Enforcement
|
|
82
|
+
|
|
83
|
+
Hard limits per feature (same as parent skill):
|
|
84
|
+
- **E2E Tests**: MAX 1-2 tests
|
|
85
|
+
- Only generate if ROI score > 50
|
|
86
|
+
- Prefer fewer, comprehensive journey tests over many granular tests
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: recipe-add-integration-tests
|
|
3
|
+
description: "Add integration/E2E tests to existing codebase using Design Doc acceptance criteria."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Required Skills [LOAD BEFORE EXECUTION]
|
|
7
|
+
|
|
8
|
+
1. [LOAD IF NOT ACTIVE] `testing` — test strategy and quality gates
|
|
9
|
+
2. [LOAD IF NOT ACTIVE] `integration-e2e-testing` — integration and E2E test patterns
|
|
10
|
+
3. [LOAD IF NOT ACTIVE] `documentation-criteria` — document creation rules and templates
|
|
11
|
+
|
|
12
|
+
**Context**: Test addition workflow for existing implementations
|
|
13
|
+
|
|
14
|
+
## Orchestrator Definition
|
|
15
|
+
|
|
16
|
+
**Core Identity**: "I am not a worker. I am an orchestrator."
|
|
17
|
+
|
|
18
|
+
**First Action**: Register Steps 0-8 before any execution.
|
|
19
|
+
|
|
20
|
+
**Why Spawn**: Orchestrator's context is shared across all steps. Direct implementation consumes context needed for review and quality check phases. Task files create context boundaries. Subagents work in isolated context.
|
|
21
|
+
|
|
22
|
+
**Execution Method**:
|
|
23
|
+
- Skeleton generation -> Spawn acceptance-test-generator agent
|
|
24
|
+
- Task file creation -> Orchestrator creates directly (minimal context usage)
|
|
25
|
+
- Test implementation -> Spawn task-executor agent
|
|
26
|
+
- Test review -> Spawn integration-test-reviewer agent
|
|
27
|
+
- Quality checks -> Spawn quality-fixer agent
|
|
28
|
+
|
|
29
|
+
Design Doc path: $ARGUMENTS
|
|
30
|
+
|
|
31
|
+
## Prerequisites
|
|
32
|
+
|
|
33
|
+
- Design Doc must exist (created manually or via reverse-engineer)
|
|
34
|
+
- Existing implementation to test
|
|
35
|
+
|
|
36
|
+
## Execution Flow
|
|
37
|
+
|
|
38
|
+
### Step 0: Prepare Context
|
|
39
|
+
|
|
40
|
+
Reference documentation-criteria skill for task file template in Step 3.
|
|
41
|
+
|
|
42
|
+
### Step 1: Validate Design Doc
|
|
43
|
+
|
|
44
|
+
Verify Design Doc exists at $ARGUMENTS or find the most recent in docs/design/.
|
|
45
|
+
|
|
46
|
+
### Step 2: Skeleton Generation
|
|
47
|
+
|
|
48
|
+
Spawn acceptance-test-generator agent: "Generate test skeletons from Design Doc at [path from Step 1]."
|
|
49
|
+
|
|
50
|
+
**Expected output**: `generatedFiles` containing integration and e2e paths
|
|
51
|
+
|
|
52
|
+
### Step 3: Create Task File [GATE]
|
|
53
|
+
|
|
54
|
+
**[STOP — BLOCKING]** Present task file content to user for confirmation before proceeding to implementation.
|
|
55
|
+
**CANNOT proceed until user explicitly confirms.**
|
|
56
|
+
|
|
57
|
+
Create task file at: `docs/plans/tasks/integration-tests-YYYYMMDD.md`
|
|
58
|
+
|
|
59
|
+
**Template**:
|
|
60
|
+
```markdown
|
|
61
|
+
---
|
|
62
|
+
name: Implement integration tests for [feature name]
|
|
63
|
+
type: test-implementation
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Objective
|
|
67
|
+
|
|
68
|
+
Implement test cases defined in skeleton files.
|
|
69
|
+
|
|
70
|
+
## Target Files
|
|
71
|
+
|
|
72
|
+
- Skeleton: [path from Step 2 generatedFiles]
|
|
73
|
+
- Design Doc: [path from Step 1]
|
|
74
|
+
|
|
75
|
+
## Tasks
|
|
76
|
+
|
|
77
|
+
- [ ] Implement each test case in skeleton
|
|
78
|
+
- [ ] Verify all tests pass
|
|
79
|
+
- [ ] Ensure coverage meets requirements
|
|
80
|
+
|
|
81
|
+
## Acceptance Criteria
|
|
82
|
+
|
|
83
|
+
- All skeleton test cases implemented
|
|
84
|
+
- All tests passing
|
|
85
|
+
- No quality issues
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**Output**: "Task file created at [path]. Ready for Step 4."
|
|
89
|
+
|
|
90
|
+
### Step 4: Test Implementation
|
|
91
|
+
|
|
92
|
+
Spawn task-executor agent: "Implement integration tests. Task file: docs/plans/tasks/integration-tests-YYYYMMDD.md. Implement tests following the task file."
|
|
93
|
+
|
|
94
|
+
**Expected output**: `status`, `testsAdded`
|
|
95
|
+
|
|
96
|
+
### Step 5: Test Review
|
|
97
|
+
|
|
98
|
+
Spawn integration-test-reviewer agent: "Review test quality. Test files: [paths from Step 4 testsAdded]. Skeleton files: [paths from Step 2 generatedFiles]."
|
|
99
|
+
|
|
100
|
+
**Expected output**: `status` (approved/needs_revision), `requiredFixes`
|
|
101
|
+
|
|
102
|
+
### Step 6: Apply Review Fixes
|
|
103
|
+
|
|
104
|
+
Check Step 5 result:
|
|
105
|
+
- `status: approved` -> Mark complete, proceed to Step 7
|
|
106
|
+
- `status: needs_revision` -> Spawn task-executor agent: "Fix the following issues in test files: [requiredFixes from Step 5]." Then return to Step 5.
|
|
107
|
+
|
|
108
|
+
### Step 7: Quality Check
|
|
109
|
+
|
|
110
|
+
Spawn quality-fixer agent: "Final quality assurance for test files added in this workflow. Run all tests and verify coverage."
|
|
111
|
+
|
|
112
|
+
**Expected output**: `approved` (true/false)
|
|
113
|
+
|
|
114
|
+
### Step 8: Commit
|
|
115
|
+
|
|
116
|
+
On `approved: true` from quality-fixer:
|
|
117
|
+
- MUST commit test files with appropriate message
|
|
118
|
+
ENFORCEMENT: Commits without quality-fixer approval are invalid.
|
|
119
|
+
|
|
120
|
+
## Completion Criteria
|
|
121
|
+
|
|
122
|
+
- [ ] Design Doc validated and located
|
|
123
|
+
- [ ] Skeleton generated via acceptance-test-generator
|
|
124
|
+
- [ ] Task file created and confirmed
|
|
125
|
+
- [ ] Tests implemented via task-executor
|
|
126
|
+
- [ ] Tests reviewed via integration-test-reviewer (approved or fixes applied)
|
|
127
|
+
- [ ] Quality check passed via quality-fixer
|
|
128
|
+
- [ ] Test files committed
|