codex-workflows 0.1.0

package/.agents/skills/coding-rules/references/typescript.md

@@ -0,0 +1,220 @@
+# TypeScript Development Rules (Frontend)
+
+## Basic Principles
+
+- **Aggressive Refactoring** - Prevent technical debt and maintain health
+- **No Unused "Just in Case" Code** - Violates YAGNI principle (Kent Beck)
+
+## Comment Writing Rules
+- **Function Description Focus**: Describe what the code "does"
+- **No Historical Information**: Do not record development history
+- **Timeless**: Write only content that remains valid whenever read
+- **Conciseness**: Keep explanations to necessary minimum
+
+## Type Safety
+
+**Absolute Rule**: any type is completely prohibited. It disables type checking and becomes a source of runtime errors.
+
+**any Type Alternatives (Priority Order)**
+1. **unknown Type + Type Guards**: Use for validating external input (API responses, localStorage, URL parameters)
+2. **Generics**: When type flexibility is needed
+3. **Union Types / Intersection Types**: Combinations of multiple types
+4. **Type Assertions (Last Resort)**: Only when type is certain
+
+**Type Guard Implementation Pattern**
+```typescript
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value && 'name' in value
+}
+```
+
+**Modern Type Features**
+- **satisfies Operator**: `const config = { apiUrl: '/api' } satisfies Config` - Preserves inference
+- **const Assertion**: `const ROUTES = { HOME: '/' } as const satisfies Routes` - Immutable and type-safe
+- **Branded Types**: `type UserId = string & { __brand: 'UserId' }` - Distinguish meaning
+- **Template Literal Types**: `type EventName = \`on\${Capitalize<string>}\`` - Express string patterns with types
+
+**Type Safety in Frontend Implementation**
+- **React Props/State**: TypeScript manages types, unknown unnecessary
+- **External API Responses**: Always receive as `unknown`, validate with type guards
+- **localStorage/sessionStorage**: Treat as `unknown`, validate
+- **URL Parameters**: Treat as `unknown`, validate
+- **Form Input (Controlled Components)**: Type-safe with React synthetic events
+
+**Type Safety in Data Flow**
+- **Frontend to Backend**: Props/State (Type Guaranteed) to API Request (Serialization)
+- **Backend to Frontend**: API Response (`unknown`) to Type Guard to State (Type Guaranteed)
+
+**Type Complexity Management**
+- **Props Design**:
+  - Props count: 3-7 props ideal (consider component splitting if exceeds 10)
+  - Optional Props: 50% or less (consider default values or Context if excessive)
+  - Nesting: Up to 2 levels (flatten deeper structures)
+- Type Assertions: Review design if used 3+ times
+- **External API Types**: Relax constraints and define according to reality (convert appropriately internally)
+
+## Coding Conventions
+
+**Component Design Criteria**
+- **Function Components (Mandatory)**: Official React recommendation, optimizable by modern tooling
+- **Classes Prohibited**: Class components completely deprecated (Exception: Error Boundary)
+- **Custom Hooks**: Standard pattern for logic reuse and dependency injection
+- **Component Hierarchy**: Atoms > Molecules > Organisms > Templates > Pages
+- **Co-location**: Place tests, styles, and related files alongside components
+
+**State Management Patterns**
+- **Local State**: `useState` for component-specific state
+- **Context API**: For sharing state across component tree (theme, auth, etc.)
+- **Custom Hooks**: Encapsulate state logic and side effects
+- **Server State**: React Query or SWR for API data caching
+
+**Data Flow Principles**
+- **Single Source of Truth**: Each piece of state has one authoritative source
+- **Unidirectional Flow**: Data flows top-down via props
+- **Immutable Updates**: Use immutable patterns for state updates
+
+```typescript
+// Good: Immutable state update
+setUsers(prev => [...prev, newUser])
+
+// Bad: Mutable state update
+users.push(newUser)
+setUsers(users)
+```
+
+**Function Design**
+- **0-2 parameters maximum**: Use object for 3+ parameters
+  ```typescript
+  // Object parameter
+  function createUser({ name, email, role }: CreateUserParams) {}
+  ```
+
+**Props Design (Props-driven Approach)**
+- Props are the interface: Define all necessary information as props
+- Avoid implicit dependencies: Do not depend on global state or context without necessity
+- Type-safe: Always define Props type explicitly
+
+**Environment Variables**
+- **Use build tool's environment variable system**: `process.env` does not work in browsers
+- Centrally manage environment variables through configuration layer
+- Implement proper type safety and default value handling
+
+```typescript
+// Build tool environment variables (public values only)
+const config = {
+  apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
+  appName: import.meta.env.APP_NAME || 'My App'
+}
+
+// Does not work in frontend
+// const apiUrl = process.env.API_URL
+```
+
+**Security (Client-side Constraints)**
+- **CRITICAL**: All frontend code is public and visible in browser
+- **Never store secrets client-side**: No API keys, tokens, or secrets in environment variables
+- Do not include `.env` files in Git
+- Do not include sensitive information in error messages
+
+```typescript
+// Bad: API key exposed in browser
+// const apiKey = import.meta.env.API_KEY
+// const response = await fetch(`https://api.example.com/data?key=${apiKey}`)
+
+// Good: Backend manages secrets, frontend accesses via proxy
+const response = await fetch('/api/data') // Backend handles API key authentication
+```
+
+**Dependency Injection**
+- **Custom Hooks for dependency injection**: Ensure testability and modularity
+
+**Asynchronous Processing**
+- Promise Handling: Always use `async/await`
+- Error Handling: Always handle with `try-catch` or Error Boundary
+- Type Definition: Explicitly define return value types (e.g., `Promise<Result>`)
+
+**Format Rules**
+- Semicolon omission (follow project formatter settings)
+- Types in `PascalCase`, variables/functions in `camelCase`
+- Imports use absolute paths (`src/`)
+
+**Clean Code Principles**
+- Delete unused code immediately
+- Delete debug `console.log()`
+- No commented-out code (manage history with version control)
+- Comments explain "why" (not "what")
+
+## Error Handling
+
+**Absolute Rule**: Error suppression prohibited. All errors must have log output and appropriate handling.
+
+**Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states
+```typescript
+// Bad: Unconditional fallback
+catch (error) {
+  return defaultValue // Hides error
+}
+
+// Good: Explicit failure
+catch (error) {
+  logger.error('Processing failed', error)
+  throw error // Handle with Error Boundary or higher layer
+}
+```
+
+**Result Type Pattern**: Express errors with types for explicit handling
+```typescript
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
+
+function parseUser(data: unknown): Result<User, ValidationError> {
+  if (!isValid(data)) return { ok: false, error: new ValidationError() }
+  return { ok: true, value: data as User }
+}
+```
+
+**Custom Error Classes**
+```typescript
+export class AppError extends Error {
+  constructor(message: string, public readonly code: string, public readonly statusCode = 500) {
+    super(message)
+    this.name = this.constructor.name
+  }
+}
+// Purpose-specific: ValidationError(400), ApiError(502), NotFoundError(404)
+```
+
+**Layer-Specific Error Handling (React)**
+- Error Boundary: Catch React component errors, display fallback UI
+- Custom Hook: Detect business rule violations, propagate AppError as-is
+- API Layer: Convert fetch errors to domain errors
+
+**Structured Logging and Sensitive Information Protection**
+Never include sensitive information (password, token, apiKey, secret, creditCard) in logs
+
+**Asynchronous Error Handling in React**
+- Error Boundary setup mandatory: Catch rendering errors
+- Use try-catch with all async/await in event handlers
+- Always log and re-throw errors or display error state
+
+## Refactoring Techniques
+
+**Basic Policy**
+- Small Steps: Maintain always-working state through gradual improvements
+- Safe Changes: Minimize the scope of changes at once
+- Behavior Guarantee: Ensure existing behavior remains unchanged while proceeding
+
+**Implementation Procedure**: Understand Current State > Gradual Changes > Behavior Verification > Final Validation
+
+**Priority**: Duplicate Code Removal > Large Function Division > Complex Conditional Branch Simplification > Type Safety Improvement
+
+## Performance Optimization
+
+- Component Memoization: Use React.memo for expensive components
+- State Optimization: Minimize re-renders with proper state structure
+- Lazy Loading: Use React.lazy and Suspense for code splitting
+- Bundle Size: Monitor with the `build` script and keep under 500KB
+
+## Non-functional Requirements
+
+- **Browser Compatibility**: Chrome/Firefox/Safari/Edge (latest 2 versions)
+- **Rendering Time**: Within 5 seconds for major pages

package/.agents/skills/documentation-criteria/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: documentation-criteria
+description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec, and Work Plan with templates. Use when: creating or reviewing technical documents, determining which documents are required, or following document templates."
+---
+
+# Documentation Creation Criteria
+
+## Templates
+
+- **[prd-template.md](references/prd-template.md)** - Product Requirements Document template
+- **[adr-template.md](references/adr-template.md)** - Architecture Decision Record template
+- **[ui-spec-template.md](references/ui-spec-template.md)** - UI Specification template (frontend/fullstack features)
+- **[design-template.md](references/design-template.md)** - Technical Design Document template
+- **[plan-template.md](references/plan-template.md)** - Work Plan template
+- **[task-template.md](references/task-template.md)** - Task file template for implementation tasks
+
+## Creation Decision Matrix [MANDATORY]
+
+| Condition | Required Documents | Creation Order |
+|-----------|-------------------|----------------|
+| New Feature Addition (backend) | PRD -> [ADR] -> Design Doc -> Work Plan | After PRD approval |
+| New Feature Addition (frontend/fullstack) | PRD -> **UI Spec** -> [ADR] -> Design Doc -> Work Plan | UI Spec before Design Doc |
+| ADR Conditions Met (see below) | ADR -> Design Doc -> Work Plan | Start immediately |
+| 6+ Files | ADR -> Design Doc -> Work Plan (REQUIRED) | Start immediately |
+| 3-5 Files | Design Doc -> Work Plan (REQUIRED) | Start immediately |
+| 1-2 Files | None | Direct implementation |
+
+**ENFORCEMENT**: EVALUATE file count and ADR conditions BEFORE starting implementation
+
+## ADR Creation Conditions [MANDATORY if Any Apply]
+
+### 1. Contract System Changes
+- **Adding nested contracts with 3+ levels**
+- **Changing/deleting contracts used in 3+ locations**
+- **Contract responsibility changes** (e.g., DTO to Entity, Request to Domain)
+
+### 2. Data Flow Changes
+- **Storage location changes** (DB to File, Memory to Cache)
+- **Processing order changes with 3+ steps**
+- **Data passing method changes** (parameter passing to shared state, direct reference to event-based)
+
+### 3. Architecture Changes
+- Layer addition, responsibility changes, component relocation
+
+### 4. External Dependency Changes
+- Library/framework/external API introduction or replacement
+
+### 5. Complex Implementation Logic (Regardless of Scale)
+- Managing 3+ states
+- Coordinating 5+ asynchronous processes
+
+## Detailed Document Definitions
+
+### PRD (Product Requirements Document)
+**Purpose**: Define business requirements and user value
+**Includes**: Business requirements, success metrics, user stories, MoSCoW prioritization, MVP/Future phase separation, user journey diagram, scope boundary diagram
+**Excludes**: Technical implementation details, technical selection rationale, implementation phases, task breakdown
+
+### ADR (Architecture Decision Record)
+**Purpose**: Record technical decision rationale and background
+**Includes**: Decision, rationale, option comparison (minimum 3 options), architecture impact, principled implementation guidelines
+**Excludes**: Implementation schedule, detailed procedures, specific code examples, resource assignments
+
+### UI Specification
+**Purpose**: Define UI structure, screen transitions, component decomposition, and interaction design
+**Includes**: Screen list and transitions, component state x display matrix, interaction definitions, AC traceability, existing component reuse map, accessibility requirements
+**Excludes**: Technical implementation details, API contracts, test implementation, implementation schedule
+
+### Design Document
+**Purpose**: Define technical implementation methods in detail
+**Includes**: Existing codebase analysis, technical approach, dependencies and constraints, interface/contract definitions, data flow, acceptance criteria, change impact map, code inspection evidence
+**Excludes**: Why that technology was chosen (reference ADR), when/who to implement (reference Work Plan)
+
+### Work Plan
+**Purpose**: Implementation task management and progress tracking
+**Includes**: Task breakdown, schedule estimates, E2E verification procedures, Phase 4 Quality Assurance Phase (required), progress records
+**Excludes**: Technical rationale, design details
+
+**Phase Division Criteria**:
+1. **Phase 1: Foundation Implementation** - Contract definitions, interfaces, test preparation
+2. **Phase 2: Core Feature Implementation** - Business logic, unit tests
+3. **Phase 3: Integration Implementation** - External connections, presentation layer
+4. **Phase 4: Quality Assurance (Required)** - Acceptance criteria, all tests, quality checks
+
+## Creation Process [MANDATORY]
+
+**STEP 1**: **Problem Analysis** — Change scale assessment, ADR condition check
+**STEP 2**: **ADR Option Consideration** (ADR only) — Compare 3+ options, specify trade-offs
+**STEP 3**: **Creation** — Use templates, include measurable conditions
+**STEP 4**: **Approval** — "Accepted" after review enables implementation
+
+**ENFORCEMENT**: Implementation CANNOT begin without approved documents for the relevant scale
+
+## Storage Locations
+
+| Document | Path | Naming Convention |
+|----------|------|------------------|
+| PRD | `docs/prd/` | `[feature-name]-prd.md` |
+| ADR | `docs/adr/` | `ADR-[4-digits]-[title].md` |
+| UI Spec | `docs/ui-spec/` | `[feature-name]-ui-spec.md` |
+| Design Doc | `docs/design/` | `[feature-name]-design.md` |
+| Work Plan | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` |
+| Task File | `docs/plans/tasks/` | `{plan-name}-task-{number}.md` |
+
+## ADR Status
+`Proposed` -> `Accepted` -> `Deprecated`/`Superseded`/`Rejected`
+
+## AI Automation Rules [MANDATORY]
+- 5+ files: MUST suggest ADR creation
+- Contract/data flow change detected: ADR REQUIRED
+- Check existing ADRs before implementation — ALWAYS verify alignment
+
+## Diagram Requirements
+
+| Document | Required Diagrams | Purpose |
+|----------|------------------|---------|
+| PRD | User journey, Scope boundary | Clarify user experience and scope |
+| ADR | Option comparison (when needed) | Visualize trade-offs |
+| UI Spec | Screen transition, Component tree | Clarify screen flow and structure |
+| Design Doc | Architecture, Data flow | Understand technical structure |
+| Work Plan | Phase structure, Task dependency | Clarify implementation order |
+
+## Common ADR Relationships
+1. **At creation**: Identify common technical areas, reference existing common ADRs
+2. **When missing**: Consider creating necessary common ADRs
+3. **Design Doc**: Specify common ADRs in "Prerequisite ADRs" section
+4. **Compliance check**: Verify design aligns with common ADR decisions

package/.agents/skills/documentation-criteria/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Documentation Criteria"
+  short_description: "Document creation rules and templates"
+  default_prompt: "Use $documentation-criteria to determine what documents I need."
+
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,64 @@
+# [ADR Number] [Title]
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded]
+
+## Context
+
+[Describe the background and reasons why this decision is needed. Include the essence of the problem, current challenges, and constraints]
+
+## Decision
+
+[Describe the actual decision made. Aim for specific and clear descriptions]
+
+### Decision Details
+
+| Item | Content |
+|------|---------|
+| **Decision** | [The decision in one sentence] |
+| **Why now** | [Why this needs to happen now (timing rationale)] |
+| **Why this** | [Why this option over alternatives (1-3 lines)] |
+| **Known unknowns** | [At least one uncertainty at this point] |
+| **Kill criteria** | [One signal that should trigger reversal of this decision] |
+
+## Rationale
+
+[Explain why this decision was made and why it is the best option compared to alternatives]
+
+### Options Considered
+
+1. **Option 1**: [Description]
+   - Pros: [List advantages]
+   - Cons: [List disadvantages]
+
+2. **Option 2**: [Description]
+   - Pros: [List advantages]
+   - Cons: [List disadvantages]
+
+3. **Option 3 (Selected)**: [Description]
+   - Pros: [List advantages]
+   - Cons: [List disadvantages]
+
+## Consequences
+
+### Positive Consequences
+
+- [List positive impacts on the project or system]
+
+### Negative Consequences
+
+- [List negative impacts or trade-offs that need to be accepted]
+
+### Neutral Consequences
+
+- [List changes that are neither good nor bad]
+
+## Implementation Guidance
+
+[Principled direction only. Implementation procedures go to Design Doc]
+Example: "Use dependency injection" (good), "Implement in Phase 1" (bad)
+
+## Related Information
+
+- [Links to related ADRs, documents, issues, PRs, etc.]