codex-workflows 0.1.0

package/.agents/skills/documentation-criteria/references/design-template.md

@@ -0,0 +1,327 @@
+# [Feature Name] Design Document
+
+## Overview
+
+[Explain the purpose and overview of this feature in 2-3 sentences]
+
+### Referenced UI Spec (when feature includes frontend)
+- UI Spec path: [docs/ui-spec/xxx-ui-spec.md]
+- Component structure and state design are inherited from UI Spec
+
+## Design Summary (Meta)
+
+```yaml
+design_type: "new_feature|extension|refactoring"
+risk_level: "low|medium|high"
+complexity_level: "low|medium|high"
+complexity_rationale: "[Required if medium/high: (1) which requirements/ACs necessitate this complexity, (2) which constraints/risks it addresses]"
+main_constraints:
+  - "[constraint 1]"
+  - "[constraint 2]"
+biggest_risks:
+  - "[risk 1]"
+  - "[risk 2]"
+unknowns:
+  - "[uncertainty 1]"
+  - "[uncertainty 2]"
+```
+
+## Background and Context
+
+### Prerequisite ADRs
+
+- [ADR File Name]: [Related decision items]
+- Reference common technical ADRs when applicable
+
+### Agreement Checklist
+
+#### Scope
+- [ ] [Features/components to change]
+- [ ] [Features to add]
+
+#### Non-Scope (Explicitly not changing)
+- [ ] [Features/components not to change]
+- [ ] [Existing logic to preserve]
+
+#### Constraints
+- [ ] Parallel operation: [Yes/No]
+- [ ] Backward compatibility: [Required/Not required]
+- [ ] Performance measurement: [Required/Not required]
+
+#### Applicable Standards
+- [ ] [Standard/convention] `[explicit]` - Source: [config / rule file / documentation path]
+- [ ] [Observed pattern] `[implicit]` - Evidence: [file paths] - Confirmed: [Yes/No]
+
+### Problem to Solve
+
+[Specific problems or challenges this feature aims to address]
+
+### Current Challenges
+
+[Current system issues or limitations]
+
+### Requirements
+
+#### Functional Requirements
+
+- [List mandatory functional requirements]
+
+#### Non-Functional Requirements
+
+- **Performance**: [Response time, throughput requirements]
+- **Scalability**: [Requirements for handling increased load]
+- **Reliability**: [Error rate, availability requirements]
+- **Maintainability**: [Code readability and changeability]
+
+## Acceptance Criteria (AC) - EARS Format
+
+Each AC is written in EARS (Easy Approach to Requirements Syntax) format.
+
+**EARS Keywords**:
+| Keyword | Usage | Test Type |
+|---------|-------|-----------|
+| **When** | Event-triggered behavior | Event-driven test |
+| **While** | State-dependent behavior | State condition test |
+| **If-then** | Conditional behavior | Branch coverage test |
+| (none) | Ubiquitous behavior | Basic functionality test |
+
+**Format**: `[Keyword] <trigger/condition>, the system shall <expected behavior>`
+
+### [Functional Requirement 1]
+
+- [ ] **When** user clicks login button with valid credentials, the system shall authenticate and redirect to dashboard
+- [ ] **If** credentials are invalid, **then** the system shall display error message "Invalid credentials"
+- [ ] **While** user is logged in, the system shall maintain the session for configured timeout period
+
+### [Functional Requirement 2]
+
+- [ ] The system shall display data list with pagination of 10 items per page
+- [ ] **When** input is entered in search field, the system shall apply real-time filtering
+
+## Existing Codebase Analysis
+
+### Implementation Path Mapping
+| Type | Path | Description |
+|------|------|-------------|
+| Existing | src/[actual-path] | [Current implementation] |
+| New | src/[planned-path] | [Planned new creation] |
+
+### Integration Points (Include even for new implementations)
+- **Integration Target**: [What to connect with]
+- **Invocation Method**: [How it will be invoked]
+
+### Code Inspection Evidence
+
+| File/Function | Relevance |
+|---------------|-----------|
+| [path:function] | [similar functionality / integration point / pattern reference] |
+
+## Design
+
+### Change Impact Map
+
+```yaml
+Change Target: [Component/feature to change]
+Direct Impact:
+  - [Files/functions requiring direct changes]
+  - [Interface change points]
+Indirect Impact:
+  - [Data format changes]
+  - [Processing time changes]
+No Ripple Effect:
+  - [Explicitly specify unaffected features]
+```
+
+### Architecture Overview
+
+[How this feature is positioned within the overall system]
+
+### Data Flow
+
+```
+[Express data flow using diagrams or pseudo-code]
+```
+
+### Integration Points List
+
+| Integration Point | Location | Old Implementation | New Implementation | Switching Method |
+|-------------------|----------|-------------------|-------------------|------------------|
+| Integration Point 1 | [Class/Function] | [Existing Process] | [New Process] | [DI/Factory etc.] |
+
+### Main Components
+
+#### Component 1
+
+- **Responsibility**: [Scope of responsibility for this component]
+- **Interface**: [APIs and contract definitions provided]
+- **Dependencies**: [Relationships with other components]
+
+### Data Representation Decision (When Introducing New Structures)
+
+| Criterion | Assessment | Reason |
+|-----------|-----------|--------|
+| Semantic Fit | [Yes/No] | [Does existing structure's meaning align?] |
+| Responsibility Fit | [Yes/No] | [Same bounded context?] |
+| Lifecycle Fit | [Yes/No] | [Same creation/mutation/deletion timing?] |
+| Boundary/Interop Cost | [Low/Medium/High] | [Cost of sharing across boundaries?] |
+
+**Decision**: [reuse / extend / new] -- [rationale in 1-2 sentences]
+
+### Contract Definitions
+
+```
+// Record major contract/interface definitions here
+```
+
+### Data Contract
+
+#### Component 1
+
+```yaml
+Input:
+  Type: [Type/interface definition]
+  Preconditions: [Required items, format constraints]
+  Validation: [Validation method]
+
+Output:
+  Type: [Type/interface definition]
+  Guarantees: [Conditions that must always be met]
+  On Error: [Exception/null/default value]
+
+Invariants:
+  - [Conditions that remain unchanged before and after processing]
+```
+
+### Field Propagation Map (When Fields Cross Boundaries)
+
+| Field | Boundary | Status | Detail |
+|-------|----------|--------|--------|
+| [field name] | [Component A to B] | preserved / transformed / dropped | [logic or reason] |
+
+### State Transitions and Invariants (When Applicable)
+
+```yaml
+State Definition:
+  - Initial State: [Initial values and conditions]
+  - Possible States: [List of states]
+
+State Transitions:
+  Current State -> Event -> Next State
+
+System Invariants:
+  - [Conditions that hold in any state]
+```
+
+### UI Error State Design (when feature includes frontend)
+
+| Component / Screen | Loading | Empty | Error | Partial |
+|-------------------|---------|-------|-------|---------|
+| [Component name] | [Skeleton / spinner] | [Empty state + CTA] | [Error message + Retry] | [Cached display + Banner] |
+
+### Client State Design (when feature includes frontend)
+
+| State Category | State | Management Method | Sync Strategy |
+|---------------|-------|-------------------|---------------|
+| Server state | [Fetched data] | [Cache library / custom hook] | [Polling / WebSocket / manual refresh] |
+| Local UI state | [Modal open, tab selection] | [useState / useReducer] | - |
+| Temporary state | [Form input, draft] | [useState / form library] | [Auto-save / manual save] |
+
+### UI Action - API Contract Mapping (when feature includes frontend)
+
+| UI Action | API Endpoint | Request | Response | Error Contract |
+|-----------|-------------|---------|----------|----------------|
+| [Button click / form submit] | [POST /api/xxx] | [Request body fields] | [Response fields] | [Error codes and UI handling] |
+
+### Error Handling
+
+[Types of errors and how to handle them]
+
+### Logging and Monitoring
+
+[What to record in logs and how to monitor]
+
+## Implementation Plan
+
+### Implementation Approach
+
+**Selected Approach**: [Approach name or combination]
+**Selection Reason**: [Reason considering project constraints and technical dependencies]
+
+### Technical Dependencies and Implementation Order
+
+#### Required Implementation Order
+1. **[Component/Feature A]**
+   - Technical Reason: [Why this needs to be implemented first]
+   - Dependent Elements: [Other components that depend on this]
+
+2. **[Component/Feature B]**
+   - Technical Reason: [Technical necessity to implement after A]
+   - Prerequisites: [Required pre-implementations]
+
+### Integration Points
+Each integration point requires E2E verification:
+
+**Integration Point 1: [Name]**
+- Components: [Component A] to [Component B]
+- Verification: [How to verify integration works]
+
+### Migration Strategy
+
+[Technical migration approach, ensuring backward compatibility]
+
+## Test Strategy
+
+### Basic Test Design Policy
+
+Automatically derive test cases from acceptance criteria:
+- Create at least one test case for each acceptance criterion
+- Implement measurable standards from acceptance criteria as assertions
+
+### Unit Tests
+
+[Unit testing policy and coverage goals]
+
+### Integration Tests
+
+[Integration testing policy and important test cases]
+
+### E2E Tests
+
+[E2E testing policy]
+
+### Performance Tests
+
+[Performance testing methods and standards]
+
+## Security Considerations
+
+[Security concerns and countermeasures]
+
+## Future Extensibility
+
+[Considerations for future feature additions or changes]
+
+## Alternative Solutions
+
+### Alternative 1
+
+- **Overview**: [Description of alternative solution]
+- **Advantages**: [Advantages]
+- **Disadvantages**: [Disadvantages]
+- **Reason for Rejection**: [Why it wasn't adopted]
+
+## Risks and Mitigation
+
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| [Risk 1] | High/Medium/Low | High/Medium/Low | [Countermeasure] |
+
+## References
+
+- [Related documentation and links]
+
+## Update History
+
+| Date | Version | Changes | Author |
+|------|---------|---------|--------|
+| YYYY-MM-DD | 1.0 | Initial version | [Name] |

package/.agents/skills/documentation-criteria/references/plan-template.md

@@ -0,0 +1,131 @@
+# Work Plan: [Feature Name] Implementation
+
+Created Date: YYYY-MM-DD
+Type: feature|fix|refactor
+Estimated Duration: X days
+Estimated Impact: X files
+Related Issue/PR: #XXX (if any)
+
+## Related Documents
+- Design Doc(s):
+  - [docs/design/XXX.md]
+  - [docs/design/YYY.md] (if multiple, e.g. backend + frontend)
+- ADR: [docs/adr/ADR-XXXX.md] (if any)
+- PRD: [docs/prd/XXX.md] (if any)
+
+## Objective
+[Why this change is necessary, what problem it solves]
+
+## Background
+[Current state and why changes are needed]
+
+## Risks and Countermeasures
+
+### Technical Risks
+- **Risk**: [Risk description]
+  - **Impact**: [Impact assessment]
+  - **Countermeasure**: [How to address it]
+
+### Schedule Risks
+- **Risk**: [Risk description]
+  - **Impact**: [Impact assessment]
+  - **Countermeasure**: [How to address it]
+
+## Implementation Phases
+
+(Note: Phase structure is determined based on Design Doc technical dependencies and implementation approach)
+
+### Phase 1: [Phase Name] (Estimated commits: X)
+**Purpose**: [What this phase aims to achieve]
+
+#### Tasks
+- [ ] Task 1: Specific work content
+- [ ] Task 2: Specific work content
+- [ ] Quality check: Implement staged quality checks (refer to ai-development-guide skill)
+- [ ] Unit tests: All related tests pass
+
+#### Phase Completion Criteria
+- [ ] [Functional completion criteria]
+- [ ] [Quality completion criteria]
+
+#### Operational Verification Procedures
+1. [Operation verification steps]
+2. [Expected result verification]
+3. [Performance verification (when applicable)]
+
+### Phase 2: [Phase Name] (Estimated commits: X)
+**Purpose**: [What this phase aims to achieve]
+
+#### Tasks
+- [ ] Task 1: Specific work content
+- [ ] Task 2: Specific work content
+- [ ] Quality check: Implement staged quality checks (refer to ai-development-guide skill)
+- [ ] Integration tests: Verify overall feature functionality
+
+#### Phase Completion Criteria
+- [ ] [Functional completion criteria]
+- [ ] [Quality completion criteria]
+
+#### Operational Verification Procedures
+1. [Operation verification steps]
+2. [Expected result verification]
+3. [Performance verification (when applicable)]
+
+### Phase 3: [Phase Name] (Estimated commits: X)
+**Purpose**: [What this phase aims to achieve]
+
+#### Tasks
+- [ ] Task 1: Specific work content
+- [ ] Task 2: Specific work content
+- [ ] Quality check: Implement staged quality checks (refer to ai-development-guide skill)
+- [ ] Integration tests: Verify component coordination
+
+#### Phase Completion Criteria
+- [ ] [Functional completion criteria]
+- [ ] [Quality completion criteria]
+
+#### Operational Verification Procedures
+[Copy relevant integration point operational verification from Design Doc]
+
+### Final Phase: Quality Assurance (Required) (Estimated commits: 1)
+**Purpose**: Overall quality assurance and Design Doc consistency verification
+
+#### Tasks
+- [ ] Verify all Design Doc acceptance criteria achieved
+- [ ] Quality checks (types, lint, format)
+- [ ] Execute all tests
+- [ ] Coverage 70%+
+- [ ] Document updates
+
+#### Operational Verification Procedures
+[Copy operational verification procedures from Design Doc]
+
+### Quality Assurance
+- [ ] Implement staged quality checks (details: refer to ai-development-guide skill)
+- [ ] All tests pass
+- [ ] Static check pass
+- [ ] Lint check pass
+- [ ] Build success
+
+## Completion Criteria
+- [ ] All phases completed
+- [ ] Each phase's operational verification procedures executed
+- [ ] Design Doc acceptance criteria satisfied
+- [ ] Staged quality checks completed (zero errors)
+- [ ] All tests pass
+- [ ] Necessary documentation updated
+- [ ] User review approval obtained
+
+## Progress Tracking
+### Phase 1
+- Start: YYYY-MM-DD HH:MM
+- Complete: YYYY-MM-DD HH:MM
+- Notes: [Any special remarks]
+
+### Phase 2
+- Start: YYYY-MM-DD HH:MM
+- Complete: YYYY-MM-DD HH:MM
+- Notes: [Any special remarks]
+
+## Notes
+[Special notes, reference information, important points, etc.]

package/.agents/skills/documentation-criteria/references/prd-template.md

@@ -0,0 +1,119 @@
+# PRD: [Feature Name]
+
+## Overview
+
+### One-line Summary
+[Describe this feature in one line]
+
+### Background
+[Why is this feature needed? What problem does it solve?]
+
+## User Stories
+
+### Primary Users
+[Define the main target users]
+
+### User Stories
+```
+As a [user type]
+I want to [goal/desire]
+So that [expected value/benefit]
+```
+
+### Use Cases
+1. [Specific usage scenario 1]
+2. [Specific usage scenario 2]
+3. [Specific usage scenario 3]
+
+## Functional Requirements
+
+### Must Have (MVP)
+- [ ] Requirement 1: [Detailed description]
+  - AC: [Acceptance criteria - Given/When/Then format or measurable standard]
+- [ ] Requirement 2: [Detailed description]
+  - AC: [Acceptance criteria]
+- [ ] Requirement 3: [Detailed description]
+  - AC: [Acceptance criteria]
+
+### Nice to Have
+- [ ] Requirement 1: [Detailed description]
+- [ ] Requirement 2: [Detailed description]
+
+### Out of Scope
+- Item 1: [Description and reason]
+- Item 2: [Description and reason]
+
+## Non-Functional Requirements
+
+### Performance
+- Response Time: [Target value]
+- Throughput: [Target value]
+- Concurrency: [Target value]
+
+### Reliability
+- Availability: [Target value]
+- Error Rate: [Target value]
+
+### Security
+- [Security requirements details]
+
+### Scalability
+- [Considerations for future scaling]
+
+### Accessibility (when feature includes UI)
+- Compliance standard: [Default: WCAG 2.1 AA (use organization standard if available)]
+- Target assistive technologies: [Screen reader, keyboard operation, voice control, etc.]
+- Platform requirements: [e.g., app store review requirements]
+- Known constraints: [e.g., external library limitations]
+
+## Success Criteria
+
+### Quantitative Metrics
+1. [Measurable success metric 1]
+2. [Measurable success metric 2]
+3. [Measurable success metric 3]
+
+### Qualitative Metrics
+1. [User experience metric 1]
+2. [User experience metric 2]
+
+### UI Quality Metrics (when feature includes UI)
+1. [Key operation completion rate / error recovery rate / retry success rate]
+2. [Accessibility audit target score]
+
+## Technical Considerations
+
+### Dependencies
+- [Dependencies on existing systems]
+- [Dependencies on external services]
+
+### Constraints
+- [Technical constraints]
+- [Resource constraints]
+
+### Assumptions
+- [Prerequisite requiring validation 1]
+- [Prerequisite requiring validation 2]
+
+### Risks and Mitigation
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| [Risk 1] | High/Medium/Low | High/Medium/Low | [Countermeasure] |
+| [Risk 2] | High/Medium/Low | High/Medium/Low | [Countermeasure] |
+
+## Undetermined Items
+
+- [ ] [Question 1]: [Description of options or impacts]
+- [ ] [Question 2]: [Description of options or impacts]
+
+*Discuss with user until this section is empty, then delete after confirmation*
+
+## Appendix
+
+### References
+- [Related document 1]
+- [Related document 2]
+
+### Glossary
+- **Term 1**: [Definition]
+- **Term 2**: [Definition]

package/.agents/skills/documentation-criteria/references/task-template.md

@@ -0,0 +1,38 @@
+# Task: [Task Name]
+
+Metadata:
+- Dependencies: task-01 -> Deliverable: docs/plans/analysis/research-results.md
+- Provides: docs/plans/analysis/api-spec.md (for research/design tasks)
+- Size: Small (1-2 files)
+
+## Implementation Content
+[What this task will achieve]
+*Reference dependency deliverables if applicable
+
+## Target Files
+- [ ] [Implementation file path]
+- [ ] [Test file path]
+
+## Implementation Steps (TDD: Red-Green-Refactor)
+### 1. Red Phase
+- [ ] Review dependency deliverables (if any)
+- [ ] Verify/create contract definitions
+- [ ] Write failing tests
+- [ ] Run tests and confirm failure
+
+### 2. Green Phase
+- [ ] Add minimal implementation to pass tests
+- [ ] Run only added tests and confirm they pass
+
+### 3. Refactor Phase
+- [ ] Improve code (maintain passing tests)
+- [ ] Confirm added tests still pass
+
+## Completion Criteria
+- [ ] All added tests pass
+- [ ] Operation verified (select L1/L2/L3, per implementation-approach skill)
+- [ ] Deliverables created (for research/design tasks)
+
+## Notes
+- Impact scope: [Areas where changes may propagate]
+- Constraints: [Areas not to be modified]