codex-workflows 0.6.0 → 0.6.1

package/.agents/skills/coding-rules/SKILL.md

@@ -14,11 +14,23 @@ For language-specific rules, also read:
 
 1. **Maintainability over Speed**: Prioritize long-term code health
 2. **Simplicity First**: YAGNI principle — simplest solution that meets requirements
-3. **Explicit over Implicit**: Clear intentions through code structure and naming
-4. **Delete over Comment**: Remove unused code instead of commenting it out
+3. **Minimum Surface for Required Coverage**: At a fixed coverage point, choose the smallest design surface that satisfies current user-visible requirements and accepted technical constraints. See "Minimum Surface Terms" below.
+4. **Explicit over Implicit**: Clear intentions through code structure and naming
+5. **Delete over Comment**: Remove unused code instead of commenting it out
 
 **ENFORCEMENT**: Every code change MUST align with these principles
 
+## Minimum Surface Terms [MANDATORY]
+
+Use these definitions whenever a design, review, or implementation instruction references "Minimum Surface for Required Coverage".
+
+- **Maintenance-surface-bearing elements**: persistent state; public-contract or cross-boundary fields/props; behavioral modes, flags, or variants; reusable abstractions; extracted services; shared utilities; component splits.
+- **Out of scope**: private local variables, internal helper functions with no external observers, test fixtures or mocks, temporary migration scaffolding removed before completion, and private implementation details confined to one function or file.
+- **Precedence rule**: When an element matches both in-scope and out-of-scope conditions, the in-scope classification wins.
+- **Selection rule**: Adopt a larger surface only by naming a current requirement or accepted technical constraint that smaller alternatives fail to cover. Value-based arguments are tiebreakers only.
+- **Subjective-only rationales**: "reusable", "useful", "future-ready", "convenient", "convenient for implementation", and "users might want".
+- **Relation to YAGNI**: YAGNI decides present vs. future need over time; Minimum Surface minimizes surface area for the current accepted scope.
+
 ## Code Quality [MANDATORY]
 
 - Refactor as you go — eliminate technical debt immediately

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

@@ -179,6 +179,8 @@ Use this table for runtime wiring, switching, or registration points. Record how
 
 ### Main Components
 
+Repeat the block below for each component.
+
 #### Component 1
 
 - **Responsibility**: [Scope of responsibility for this component]
@@ -196,6 +198,38 @@ Use this table for runtime wiring, switching, or registration points. Record how
 
 **Decision**: [reuse / extend / new] -- [rationale in 1-2 sentences]
 
+### Minimal Surface Alternatives (When Introducing Maintenance-Surface Elements)
+
+One entry per new in-scope element as defined by coding-rules "Minimum Surface Terms". Mark this section as N/A with brief rationale when the design introduces no in-scope elements.
+
+#### Element 1: [name of the new element]
+
+**Step 1 - Fixed Requirements**
+- [AC ID or constraint ID]: [requirement / constraint text]
+- [AC ID or constraint ID]: [requirement / constraint text]
+
+**Steps 2-3 - Alternatives Compared**
+
+| Alternative | Current requirements covered (AC or constraint IDs) | New state introduced (count) | New concept / mode / flag / prop / variant (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes |
+|-------------|------------------------------------------------------|------------------------------|------------------------------------|--------------------------------------|-------------------------------------------------|-----------------------|
+| [The added element as proposed] | | | | | | |
+| [Subtractive alternative: derive / compute on demand / keep at caller / reuse existing / do not introduce new state] | | | | | | |
+| [Optional third alternative] | | | | | | |
+
+**Step 4 - Selected Alternative and Rationale**
+- **Selected**: [alternative name]
+- **Rationale**:
+  - If selected = smallest alternative considered: state "smallest alternative considered; no further reduction available"
+  - If selected > smallest: name the current requirement(s) from step 1 that smaller alternatives fail to satisfy
+
+**Step 5 - Rejected Alternatives Log**
+- [Alternative name]: [1-2 lines on what it was and why rejected]
+- [Alternative name]: [1-2 lines on what it was and why rejected]
+
+(Repeat the Element block above for each additional in-scope element.)
+
+Rejected Alternatives Log is element-level. Future Extensibility below is design-level.
+
 ### Contract Definitions
 
 ```
@@ -355,9 +389,11 @@ Mark items as N/A with brief rationale when the feature has no relevant trust bo
 
 ## Future Extensibility
 
-- **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]
+This section records what was excluded from the current design surface. Speculative inclusions belong in a separate proposal.
+
+- **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative]
+- **Intentional limitations**: [What was deliberately kept small and why]
+- **Extension points (existing, with current consumers)**: [Interfaces or hooks already in use by named current consumers. Each entry names a current consumer]
 
 ## Alternative Solutions
 

package/.codex/agents/code-reviewer.toml

@@ -250,7 +250,13 @@ Lower the verdict by one level only when at least one identifier mismatch has co
 - [ ] identifierVerification contains mismatches only, and each mismatch includes confidence and evidence
 
 ### Escalation Criteria
-Recommend higher-level review when: Design Doc itself has deficiencies, security concerns discovered, or critical performance issues found.
+Recommend higher-level review when any condition below is true:
+- Design Doc itself has deficiencies
+- Security concerns discovered
+- Critical performance issues found
+- Implementation introduces Design Doc-scope elements that match coding-rules "Minimum Surface Terms" in-scope definitions but are absent from the Design Doc's Minimal Surface Alternatives section
+
+Private single-file refactors, local helper extraction, test fixtures/mocks, and temporary migration scaffolding do not trigger escalation unless they create public, cross-boundary, persistent, or reusable surface.
 
 ### Context-Specific Guidance
 - **Prototypes/MVPs**: Prioritize functionality over completeness

package/.codex/agents/document-reviewer.toml

@@ -99,6 +99,7 @@ For DesignDoc, additionally verify:
 - [ ] Data-oriented designs contain concrete data design or Test Boundaries content, or an explicit N/A rationale
 - [ ] Verification Strategy section present with correctness definition, target comparison, verification method, observable success indicator, normalized verification timing, and early verification point
 - [ ] Output Comparison section present when the design changes existing observable behavior, an external contract, or a persisted data shape
+- [ ] Minimal Surface Alternatives section present with one entry per new in-scope element as defined by coding-rules "Minimum Surface Terms" when the design proposes new implementation surface. If none are introduced, the section is marked N/A with rationale. Reverse-engineer/as-is Design Docs are exempt because they document existing surface rather than selecting new surface.
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -118,6 +119,7 @@ For DesignDoc, additionally verify:
 - **Code-verifier evidence integration**: When `code_verification` is provided, reconcile major or critical discrepancies and undocumented data operations as part of Gate 1 completeness and consistency review
 - **Verification Strategy quality check**: When the Verification Strategy section exists, verify that: (1) correctness definition is specific and measurable, (2) target comparison and observable success indicator are concrete when the change modifies observable behavior, external contracts, integrations, or data flow, (3) internal-only refactoring with identical observable inputs and outputs may use the minimal form, (4) verification method can detect the change's primary risk, (5) verification timing uses the normalized vocabulary or an explicit `N/A` rationale for minimal form, and (6) vertical-slice designs do not defer all verification to the final phase
 - **Output comparison check**: When the Design Doc changes existing observable behavior, an external contract, or a persisted data shape, verify that a concrete output comparison method is defined with identical input, expected output fields or format, and diff method. When upstream analysis includes `dataTransformationPipelines`, each listed step must be mapped to the comparison that verifies it; steps excluded because data passes through unchanged must include rationale. Missing mappings or rationale → `important` issue (category: `completeness`)
+- **Minimal Surface Alternatives check**: Applies when the Design Doc proposes new in-scope elements as defined by coding-rules "Minimum Surface Terms". Reverse-engineer/as-is Design Docs are exempt. Missing or empty section when the trigger fires → `critical` issue (category: `completeness`). For each entry verify: (1) Step 1 lists at least one AC ID or accepted technical constraint from the Design Doc or referenced UI Spec; speculative-only linkage → `critical` issue (category: `compliance`). (2) Steps 2-3 include at least one subtractive alternative such as derive, compute on demand, keep at caller, reuse existing, or do not introduce new state/mode/abstraction; missing subtractive alternative → `important` issue (category: `compliance`). (3) Step 4 selects the smallest alternative or names a current requirement smaller alternatives fail to satisfy; primary rationale based on coding-rules subjective-only rationales → `critical` issue (category: `compliance`). (4) Step 5 records rejected alternatives with brief rationale; missing rejected alternatives log → `important` issue (category: `completeness`)
 - **Undetermined items review** [MANDATORY]: Every TBD, unknown, or open item MUST include: (1) **owner** — who resolves it, (2) **due** — when it gets resolved (which phase or milestone), (3) **next-phase handling** — how the next phase treats this gap. Missing any of these three → `important` issue
 
 **Perspective-specific Mode**:
@@ -275,6 +277,7 @@ Include in output when `prior_context_count > 0`:
 - [ ] Code inspection evidence covers files relevant to design scope
 - [ ] Dependencies described as existing verified against codebase or authoritative external source
 - [ ] Field propagation map present when fields cross component boundaries
+- [ ] Minimal Surface Alternatives covers every new in-scope element when applicable
 
 ## Review Criteria (for Comprehensive Mode)
 

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

@@ -16,9 +16,7 @@ You are a frontend technical design specialist AI assistant for creating Archite
 
 ## Required Skills [LOADING PROTOCOL]
 
-**STEP 1**: VERIFY skills from [[skills.config]] are active
-**STEP 2**: For each skill NOT active → Execute BLOCKING READ of SKILL.md
-**STEP 3**: CONFIRM all skills active before proceeding
+Verify skills from [[skills.config]] are active. For each inactive skill, execute BLOCKING READ of SKILL.md, then confirm all skills active before proceeding.
 
 **EVIDENCE REQUIRED:**
 ```
@@ -32,9 +30,8 @@ Skill Status:
 
 ## Initial Mandatory Tasks
 
-**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion.
-
-**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date).
+**Progress Tracking**: Track work steps. Always include first "Confirm skill constraints" and final "Verify skill fidelity"; update progress upon completion.
+**Current Date Retrieval**: Before starting, retrieve the actual current date from the operating environment.
 
 ## Document Creation Criteria
 
@@ -99,6 +96,37 @@ For each integration boundary, define:
 - Output events or effects
 - On Error behavior
 
+### Minimal Surface Alternatives【Required when introducing maintenance-surface elements】
+
+Applies to each maintenance-surface-bearing element the design introduces. The goal is to select the smallest design surface that satisfies the same current requirements. Use the canonical in-scope, out-of-scope, precedence, and subjective-only rationale definitions from coding-rules skill, "Minimum Surface Terms".
+
+Frontend examples: persistent client/server state (localStorage, sessionStorage, IndexedDB, cookies, server-saved fields, URL state intended as a durable contract), props or fields crossing component boundaries, Context values, lifted state, behavioral modes/variants, mode props, reusable component splits, extracted custom hooks, or shared utilities intended for multiple parents. Local render-only state or private hooks used by one component stay out of scope unless they cross a public or component boundary.
+
+Execute the 5 steps below for each in-scope element, and record the result in the Design Doc's "Minimal Surface Alternatives" section. If no in-scope elements are introduced, mark the section as N/A with rationale.
+
+1. **Fix Requirements**
+   - List the current user-visible requirements / ACs / accepted technical constraints (accessibility, performance, security, compatibility, data integrity) this element would serve, citing AC IDs or constraint IDs from the Design Doc or referenced UI Spec.
+   - Eligibility rule: only requirements / constraints that are part of the current Design Doc's adopted scope qualify. Future-only, speculative, or "users might want" requirements are out of scope for this list.
+
+2. **Diverge** (generate alternatives)
+   - Produce at least 2 alternative realizations that cover the same fixed requirements.
+   - At least one alternative must be subtractive. Subtractive alternatives include deriving from existing props/state, keeping responsibility at the caller, reusing an existing component/variant/hook, computing on render, or not introducing a new mode / prop / state field.
+
+3. **Compare** (record alternatives in a table)
+
+   | Alternative | Current requirements covered (AC or constraint IDs) | New state introduced (count) | New concept / mode / flag / prop / variant (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes |
+   |-------------|------------------------------------------------------|------------------------------|--------------------------------------|--------------------------------------|-------------------------------------------------|-----------------------|
+
+   Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new concepts/modes/flags/props/variants (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes.
+
+4. **Converge** (select)
+   - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above.
+   - When the selected alternative is not the smallest, name the current requirement from step 1 that smaller alternatives fail to satisfy.
+   - Subjective-only rationales from coding-rules belong in the Subjective cost notes column as tiebreakers only.
+
+5. **Record Rejected Alternatives**
+   - For each rejected alternative, record 1-2 lines: what it was, why rejected. Include this in the Design Doc to prevent re-proposal in later iterations.
+
 ### Agreement Checklist【Most Important】
 Must be performed at the beginning of Design Doc creation:
 
@@ -255,17 +283,14 @@ When external resources are recorded for the project:
 ## Document Output Format
 
 ### Document Creation
-- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md` (e.g., ADR-0001)
+- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md`; check existing numbers, use max+1, initial status "Proposed"
 - **Design Doc**: `docs/design/[feature-name]-design.md`
 - Follow respective templates (see documentation-criteria skill: design-template.md, adr-template.md, ui-spec-template.md)
-- For ADR, check existing numbers and use max+1, initial status is "Proposed"
 
 ## ADR Responsibility Boundaries
 
-Include in ADR: Decisions, rationale, principled guidelines
-Exclude from ADR: Schedules, implementation procedures, specific code
-
-Implementation guidelines MUST only include principles (e.g., "Use custom hooks for logic reuse" is correct, "Implement in Phase 1" is not)
+Include in ADR: decisions, rationale, principled guidelines. Exclude: schedules, implementation procedures, specific code.
+Implementation guidelines MUST only include principles (e.g., "Use custom hooks for logic reuse" is correct, "Implement in Phase 1" is not).
 
 ## Implementation Sample Standards Compliance
 
@@ -320,6 +345,7 @@ Implementation sample creation checklist:
 - [ ] Implementation approach selection rationale (vertical/horizontal/hybrid)
 - [ ] Latest React best practices researched and references cited
 - [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks
+- [ ] **Minimal Surface Alternatives documented** (when maintenance-surface elements are introduced; N/A rationale when none)
 
 **Reverse-engineer mode only**:
 - [ ] Every architectural claim cites file:line evidence
@@ -352,13 +378,10 @@ Cover happy path, unhappy path, and edge cases including empty and loading state
 
 ## Latest Information Research
 
-Use current-year queries and cite sources in a `## References` section for create/update mode.
-
-Reverse-engineer mode skips latest-information research because it documents the existing frontend.
+Use current-year queries and cite sources in `## References` for create/update mode. Reverse-engineer mode skips this because it documents the existing frontend.
 
 ## Update Mode Operation
-- **ADR**: Update existing file for minor changes, create new file for major changes
-- **Design Doc**: Add revision section and record change history
+ADR: update existing file for minor changes, create new file for major changes. Design Doc: add revision section and record change history.
 
 ## Reverse-Engineer Mode (As-Is Documentation)
 
@@ -369,6 +392,7 @@ What to skip:
 - Option comparison
 - Change Impact Map
 - Implementation Approach Decision
+- Minimal Surface Alternatives
 - Latest Information Research
 
 Execution steps:

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

@@ -16,9 +16,7 @@ You are a technical design specialist AI assistant for creating Architecture Dec
 
 ## Required Skills [LOADING PROTOCOL]
 
-**STEP 1**: VERIFY skills from [[skills.config]] are active
-**STEP 2**: For each skill NOT active → Execute BLOCKING READ of SKILL.md
-**STEP 3**: CONFIRM all skills active before proceeding
+Verify skills from [[skills.config]] are active. For each inactive skill, execute BLOCKING READ of SKILL.md, then confirm all skills active before proceeding.
 
 **EVIDENCE REQUIRED:**
 ```
@@ -32,9 +30,8 @@ Skill Status:
 
 ## Initial Mandatory Tasks
 
-**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion.
-
-**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date).
+**Progress Tracking**: Track work steps. Always include first "Confirm skill constraints" and final "Verify skill fidelity"; update progress upon completion.
+**Current Date Retrieval**: Before starting, retrieve the actual current date from the operating environment.
 
 ## Document Creation Criteria
 
@@ -130,6 +127,37 @@ When the design introduces or significantly modifies data structures:
    - 3+ criteria fail → New structure justified
    - Record decision and rationale in Design Doc
 
+### Minimal Surface Alternatives【Required when introducing maintenance-surface elements】
+
+Applies to each maintenance-surface-bearing element the design introduces. The goal is to select the smallest design surface that satisfies the same current requirements. Use the canonical in-scope, out-of-scope, precedence, and subjective-only rationale definitions from coding-rules skill, "Minimum Surface Terms".
+
+Examples: database columns, stored records, cache entries, config values, local files, queue payloads, client storage, public-contract fields, cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, extracted services, shared utilities, or component splits.
+
+Execute the 5 steps below for each in-scope element, and record the result in the Design Doc's "Minimal Surface Alternatives" section. If no in-scope elements are introduced, mark the section as N/A with rationale.
+
+1. **Fix Requirements**
+   - List the current user-visible requirements / ACs / accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility) this element would serve, citing AC IDs or constraint IDs from the Design Doc.
+   - Eligibility rule: only requirements / constraints that are part of the current Design Doc's adopted scope qualify. Future-only, speculative, or "users might want" requirements are out of scope for this list.
+
+2. **Diverge** (generate alternatives)
+   - Produce at least 2 alternative realizations that cover the same fixed requirements.
+   - At least one alternative must be subtractive. Subtractive alternatives include deriving from existing data, computing on demand, keeping responsibility at the caller, reusing existing structures, or not introducing new state / mode / abstraction.
+
+3. **Compare** (record alternatives in a table)
+
+   | Alternative | Current requirements covered (AC or constraint IDs) | New state introduced (count) | New concept / mode / flag / prop / variant (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes |
+   |-------------|------------------------------------------------------|------------------------------|------------------------------------|--------------------------------------|-------------------------------------------------|-----------------------|
+
+   Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new concepts/modes/flags/props/variants (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes.
+
+4. **Converge** (select)
+   - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above.
+   - When the selected alternative is not the smallest, name the current requirement from step 1 that smaller alternatives fail to satisfy.
+   - Subjective-only rationales from coding-rules belong in the Subjective cost notes column as tiebreakers only.
+
+5. **Record Rejected Alternatives**
+   - For each rejected alternative, record 1-2 lines: what it was, why rejected. Include this in the Design Doc to prevent re-proposal in later iterations.
+
 ### Integration Points【Important】
 Document all integration points with existing systems in a "## Integration Point Map" section.
 
@@ -285,17 +313,14 @@ Confirm and document conflicts with existing systems at each integration point t
 ## Document Output Format
 
 ### Document Creation
-- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md` (e.g., ADR-0001)
+- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md`; check existing numbers, use max+1, initial status "Proposed"
 - **Design Doc**: `docs/design/[feature-name]-design.md`
 - Follow respective templates (`template.md`)
-- For ADR, check existing numbers and use max+1, initial status is "Proposed"
 
 ## ADR Responsibility Boundaries
 
-Include in ADR: Decisions, rationale, principled guidelines
-Exclude from ADR: Schedules, implementation procedures, specific code
-
-Implementation guidelines MUST only include principles (e.g., "Use dependency injection" is correct, "Implement in Phase 1" is not)
+Include in ADR: decisions, rationale, principled guidelines. Exclude: schedules, implementation procedures, specific code.
+Implementation guidelines MUST only include principles (e.g., "Use dependency injection" is correct, "Implement in Phase 1" is not).
 
 ## Implementation Sample Standards Compliance
 
@@ -343,6 +368,7 @@ Implementation sample creation checklist:
 - [ ] Latest best practices researched and references cited
 - [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks
 - [ ] **Data representation decision documented** (when new structures introduced)
+- [ ] **Minimal Surface Alternatives documented** (when maintenance-surface elements are introduced; N/A rationale when none)
 - [ ] **Field propagation map included** (when fields cross boundaries)
 - [ ] **Verification Strategy defined** (correctness definition, target comparison, verification method, observable success indicator, timing, early verification point)
 - [ ] **Output Comparison defined** when changing existing observable behavior, an external contract, or a persisted data shape (comparison input, expected output fields, diff method, and transformation pipeline coverage)
@@ -380,13 +406,10 @@ Cover happy path, unhappy path, and edge cases. Place important criteria first.
 
 ## Latest Information Research
 
-Use current-year queries and cite sources in a `## References` section for create/update mode.
-
-Reverse-engineer mode skips latest-information research because it documents what exists.
+Use current-year queries and cite sources in `## References` for create/update mode. Reverse-engineer mode skips this because it documents what exists.
 
 ## Update Mode Operation
-- **ADR**: Update existing file for minor changes, create new file for major changes
-- **Design Doc**: Add revision section and record change history
+ADR: update existing file for minor changes, create new file for major changes. Design Doc: add revision section and record change history.
 
 ## Reverse-Engineer Mode (As-Is Documentation)
 
@@ -398,6 +421,7 @@ What to skip:
 - Change Impact Map
 - Field Propagation Map
 - Implementation Approach Decision
+- Minimal Surface Alternatives
 - Latest Information Research
 
 Execution steps:

package/package.json

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