codex-workflows 0.4.1 → 0.4.2

package/.agents/skills/coding-rules/references/security-checks.md

@@ -49,12 +49,14 @@ Sources: OWASP Top 10:2025, DryRun Agentic Coding Security Report (2026-03)
 - Endpoints or route handlers defined without authentication middleware
 - Resource access operations (read, update, delete) without authorization verification
 - Administrative or destructive operations accessible without elevated permissions
-- Recent research indicates this pattern appears at elevated rates in AI-generated code — treat as high-priority review target
+- AI-generated code frequently omits authentication middleware and authorization checks; treat every route handler and resource access operation as an explicit verification target during review
+- Detection approach: search for route or endpoint handlers without authentication middleware, and resource operations (read, update, delete) without authorization checks in the call chain
 
 ### Mishandling of Exceptional Conditions (OWASP A10:2025)
 - Error handlers that expose internal system details (stack traces, database errors, file paths) in responses
-- Error handlers that fail open (grant access or skip validation on error)
+- Error handlers that grant access, skip authentication, or bypass authorization when an exception occurs
 - Missing error handling on security-critical operations (authentication, authorization, cryptographic operations)
+- Detection approach: search for catch or error-handler blocks that return stack traces, database errors, or file paths in responses, and for handlers that continue with success-path behavior without re-validating security state
 
 ### Software Supply Chain Patterns (OWASP A03:2025)
 - Dependencies imported without version pinning

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

@@ -7,13 +7,13 @@
 
 ## Comment Writing Rules
 - **Function Description Focus**: Describe what the code "does"
-- **No Historical Information**: Do not record development history
+- **History in Version Control**: Record development history in commits and PRs instead of code comments
 - **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.
+**Absolute Rule**: Use `unknown`, generics, unions, intersections, or validated assertions instead of `any`. `any` 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)
@@ -91,7 +91,7 @@ setUsers(users)
 
 **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
+- Declare dependencies explicitly through props, hooks, or injected modules instead of relying on ambient global state
 - Type-safe: Always define Props type explicitly
 
 **Environment Variables**
@@ -146,7 +146,7 @@ const response = await fetch('/api/data') // Backend handles API key authenticat
 
 ## Error Handling
 
-**Absolute Rule**: Error suppression prohibited. All errors must have log output and appropriate handling.
+**Absolute Rule**: Handle every error explicitly with log output, recovery logic, or escalation appropriate to the failure mode.
 
 **Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states
 ```typescript

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

@@ -53,23 +53,19 @@ description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec,
 
 ### 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
+**Scope**: Business requirements, user value, success metrics, user stories, MoSCoW prioritization, MVP/Future phase separation, user journey diagram, and scope boundary diagram only. Technical implementation details belong in Design Doc, technical decision rationale in ADR, and implementation phases or task breakdown belong in Work Plan.
 
 ### 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
+**Scope**: Decision, rationale, option comparison (minimum 3 options), architecture impact, and principled implementation guidance only. Implementation procedures and code examples belong in Design Doc, while schedule and resource assignments belong in Work Plan.
 
 ### 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 (generated by acceptance-test-generator), implementation schedule
+**Scope**: Screen list and transitions, component state x display matrix, component decomposition, interaction definitions, AC traceability, existing component reuse map, visual acceptance criteria, and accessibility requirements only. Technical implementation and API contracts belong in Design Doc, test implementation belongs in generated test skeletons, and schedule belongs in Work Plan.
 
 ### 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), detailed test strategy and test case selection (generated by acceptance-test-generator from acceptance criteria)
+**Scope**: Existing codebase analysis, technical approach, dependencies and constraints, interface and contract definitions, data flow, acceptance criteria, change impact map, code inspection evidence, and verification strategy only. Technology selection rationale belongs in ADR, schedule and assignments belong in Work Plan, and detailed test strategy or case selection belongs in generated test skeletons.
 
 **Required Structural Elements**:
 - Existing codebase analysis and code inspection evidence
@@ -85,8 +81,7 @@ description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec,
 
 ### Work Plan
 **Purpose**: Implementation task management and progress tracking
-**Includes**: Task breakdown, schedule estimates, test skeleton file paths, Verification Strategy summaries from each Design Doc, final Quality Assurance phase (required), progress records
-**Excludes**: Technical rationale, design details
+**Scope**: Task breakdown, dependencies, schedule estimates, test skeleton file paths, Verification Strategy summaries from each Design Doc, final Quality Assurance phase, and progress tracking only. Technical rationale belongs in ADR and design details belong in Design Doc.
 
 **Phase Division Criteria**:
 
@@ -103,7 +98,7 @@ description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec,
 
 **When Hybrid is selected**:
 - Combine vertical and horizontal phase structures as defined in the Design Doc
-- Final phase is always Quality Assurance
+- Final phase is always Quality Assurance with acceptance criteria verification, all tests passing, and quality checks complete
 
 ## Creation Process [MANDATORY]
 

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

@@ -2,7 +2,7 @@
 
 ## Status
 
-[Proposed | Accepted | Deprecated | Superseded]
+[Proposed | Accepted | Deprecated | Superseded | Rejected]
 
 ## Context
 
@@ -54,6 +54,10 @@
 
 - [List changes that are neither good nor bad]
 
+## Architecture Impact
+
+[Describe how this decision affects existing architecture: components changed, dependencies introduced or removed, and new architectural constraints]
+
 ## Implementation Guidance
 
 [Principled direction only. Implementation procedures go to Design Doc]

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

@@ -277,11 +277,16 @@ System Invariants:
 
 ### Error Handling
 
-[Types of errors and how to handle them]
+| Error Category | Example | Detection | Recovery Strategy | User Impact |
+|---------------|---------|-----------|-------------------|-------------|
+| [Validation / External / Infrastructure / Business logic] | [Specific error] | [How detected] | [Retry / Fallback / Propagate / Log-and-continue] | [User-facing message or silent handling] |
 
 ### Logging and Monitoring
 
-[What to record in logs and how to monitor]
+- **Log events**: [Key events to log: state transitions, external calls, error occurrences, performance thresholds]
+- **Log levels**: [Which events use DEBUG / INFO / WARN / ERROR]
+- **Sensitive data**: [Fields to mask or exclude; align with Security Considerations]
+- **Monitoring**: [Metrics to track, alert thresholds, dashboard requirements]
 
 ## Implementation Plan
 
@@ -301,12 +306,6 @@ System Invariants:
    - Technical Reason: [Technical necessity to implement after A]
    - Prerequisites: [Required pre-implementations]
 
-### Integration Points
-
-**Integration Point 1: [Name]**
-- Components: [Component A] to [Component B]
-- Contract: [Interface/API contract between components]
-
 ### Migration Strategy
 
 [Technical migration approach, ensuring backward compatibility]
@@ -323,7 +322,9 @@ Mark items as N/A with brief rationale when the feature has no relevant trust bo
 
 ## Future Extensibility
 
-[Considerations for future feature additions or changes]
+- **Extension points**: [Interfaces, hooks, or plugin mechanisms designed for future use]
+- **Known future requirements**: [Planned features that influenced current design decisions]
+- **Intentional limitations**: [What was deliberately kept simple and why]
 
 ## Alternative Solutions
 

package/.agents/skills/testing/SKILL.md

@@ -64,7 +64,7 @@ All tests MUST be:
 
 - **Independent**: No dependencies between tests
 - **Reproducible**: Same input always produces same output
-- **Fast**: Complete test suite runs in reasonable time
+- **Fast**: Complete the full test suite within the project's accepted feedback window and flag suites that materially slow local iteration or CI
 - **Self-checking**: Clear pass/fail without manual verification
 - **Timely**: Written close to the code they test
 
@@ -162,7 +162,7 @@ Test names should clearly describe:
 
 - Use setup hooks to prepare test environment
 - Use teardown hooks to clean up resources
-- Keep setup minimal and focused
+- Keep setup scoped to the data, dependencies, and fixtures required for the behavior under test
 - Ensure teardown runs even if test fails
 
 ## Mocking and Test Doubles
@@ -177,7 +177,7 @@ Test names should clearly describe:
 ### Mocking Principles [MANDATORY]
 
 - Mock at boundaries, not internally — use real implementations for internal utilities
-- Keep mocks simple and focused
+- Keep each mock limited to the behavior the test needs to control or observe
 - Verify mock expectations when relevant
 - Use adapters for external libraries/frameworks you do not control
 
@@ -345,7 +345,7 @@ Eliminate tests that fail intermittently:
 - Add test for every bug fix
 - Maintain comprehensive test suite
 - Run full suite regularly
-- Don't delete tests without good reason
+- Delete a test only when the covered behavior no longer exists or the same behavior is covered by a stronger test at the correct level
 
 ### Legacy Code
 

package/.codex/agents/acceptance-test-generator.toml

@@ -242,7 +242,8 @@ These annotations are used when planning and prioritizing test implementation.
 ## Constraints and Quality Standards
 
 **Mandatory Compliance**:
-- Output only test skeletons (prohibit implementation code, assertions, mocks)
+- Output test skeletons only: verification points, expected results, and pass criteria
+- Downstream consumers treat these skeletons as design artifacts rather than runnable tests
 - Clearly state verification points, expected results, and pass criteria for each test
 - Preserve original AC statements in comments (ensure traceability)
 - Stay within test budget; report if budget insufficient for critical tests
@@ -273,7 +274,7 @@ These annotations are used when planning and prioritizing test implementation.
 - Framework/Language: Auto-detect from existing test files
 - Placement: Identify test directory with project-specific patterns
 - Naming: Follow existing file naming conventions
-- Output: Test skeleton only (exclude implementation code)
+- Output: Test skeletons only (follow Constraints and Quality Standards for the boundary)
 
 **File Operations**:
 - Existing files: Append to end, prevent duplication (check existing tests)

package/.codex/agents/requirement-analyzer.toml

@@ -55,7 +55,7 @@ Scale determination and required document details follow the principles in docum
 - **Medium**: 3-5 files, spanning multiple components
 - **Large**: 6+ files, architecture-level changes
 
-※ADR conditions (contract system changes, data flow changes, architecture changes, external dependency changes) require ADR regardless of scale
+Note: ADR conditions (contract system changes, data flow changes, architecture changes, external dependency changes) require ADR regardless of scale
 
 ### Important: Clear Determination Expressions
 MUST use the following expressions to show clear determinations:
@@ -162,7 +162,7 @@ Return the JSON result as the final response. See Output Format for the schema.
 - [ ] Do I understand the user's true purpose?
 - [ ] Have I properly estimated the impact scope?
 - [ ] Have I correctly determined ADR necessity?
-- [ ] Have I not overlooked technical risks?
+- [ ] Have I identified all technical risks and dependencies?
 - [ ] Have I listed scopeDependencies for uncertain scale?
 - [ ] Final response is the JSON output
 

package/.codex/agents/task-executor.toml

@@ -162,7 +162,7 @@ Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have u
 **Unavailable**: Escalate with `status: "escalation_needed"`, `reason: "test_environment_not_ready"`
 
 #### Pre-implementation Verification (Pattern 5 Compliant)
-1. **Read relevant Design Doc sections** and understand accurately
+1. **Read relevant Design Doc sections** and extract interface contracts, data structures, dependency constraints, and verification expectations
 2. **Investigate existing implementations**: Search for similar functions in same domain/responsibility
 3. **Cross-check against Investigation Notes**: Ensure planned implementation is consistent with the observations recorded in the task file
 4. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above

package/.codex/agents/technical-designer-frontend.toml

@@ -80,7 +80,7 @@ Must be performed before Design Doc creation:
    - Search existing code for keywords related to planned component
    - Look for components with same domain, responsibilities, or UI patterns
    - Decision and action:
-     - Similar component found → Use that component (do not create new component)
+     - Similar component found → Reuse, compose, or extend that component path and document the reuse decision
      - Similar component is technical debt → Create ADR improvement proposal before implementation
      - No similar component → Proceed with new implementation
 

package/.codex/agents/technical-designer.toml

@@ -97,7 +97,7 @@ Must be performed before Design Doc creation:
    - Search existing code for keywords related to planned functionality
    - Look for implementations with same domain, responsibilities, or configuration patterns
    - Decision and action:
-     - Similar functionality found → Use that implementation (do not create new implementation)
+     - Similar functionality found → Reuse or extend that implementation path and document the reuse decision
      - Similar functionality is technical debt → Create ADR improvement proposal before implementation
      - No similar functionality → Proceed with new implementation
 

package/.codex/agents/work-planner.toml

@@ -111,7 +111,7 @@ Execute file output immediately. Final approval is managed by the orchestrator r
 1. **Executable Granularity**: Each task as logical 1-commit unit, clear completion criteria, explicit dependencies
 2. **Built-in Quality**: Simultaneous test implementation, quality checks in each phase
 3. **Risk Management**: List risks and countermeasures in advance, define detection methods
-4. **Ensure Flexibility**: Prioritize essential purpose, avoid excessive detail
+4. **Ensure Flexibility**: Prioritize essential purpose and include only details required for task execution, verification, and dependency management
 5. **Design Doc Compliance**: All task completion criteria derived from Design Doc specifications
 6. **Implementation Pattern Consistency**: When including implementation samples, MUST ensure strict compliance with Design Doc implementation approach
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflows",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",