codex-workflows 0.6.0 → 0.6.2
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/coding-rules/SKILL.md +14 -2
- package/.agents/skills/documentation-criteria/references/design-template.md +39 -3
- package/.agents/skills/task-analyzer/references/skills-index.yaml +1 -0
- package/.codex/agents/code-reviewer.toml +7 -1
- package/.codex/agents/document-reviewer.toml +3 -0
- package/.codex/agents/technical-designer-frontend.toml +41 -17
- package/.codex/agents/technical-designer.toml +41 -17
- package/package.json +5 -1
|
@@ -14,11 +14,23 @@ For language-specific rules, also read:
|
|
|
14
14
|
|
|
15
15
|
1. **Maintainability over Speed**: Prioritize long-term code health
|
|
16
16
|
2. **Simplicity First**: YAGNI principle — simplest solution that meets requirements
|
|
17
|
-
3. **
|
|
18
|
-
4. **
|
|
17
|
+
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.
|
|
18
|
+
4. **Explicit over Implicit**: Clear intentions through code structure and naming
|
|
19
|
+
5. **Delete over Comment**: Remove unused code instead of commenting it out
|
|
19
20
|
|
|
20
21
|
**ENFORCEMENT**: Every code change MUST align with these principles
|
|
21
22
|
|
|
23
|
+
## Minimum Surface Terms [MANDATORY]
|
|
24
|
+
|
|
25
|
+
Use these definitions whenever a design, review, or implementation instruction references "Minimum Surface for Required Coverage".
|
|
26
|
+
|
|
27
|
+
- **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.
|
|
28
|
+
- **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.
|
|
29
|
+
- **Precedence rule**: When an element matches both in-scope and out-of-scope conditions, the in-scope classification wins.
|
|
30
|
+
- **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.
|
|
31
|
+
- **Subjective-only rationales**: "reusable", "useful", "future-ready", "convenient", "convenient for implementation", and "users might want".
|
|
32
|
+
- **Relation to YAGNI**: YAGNI decides present vs. future need over time; Minimum Surface minimizes surface area for the current accepted scope.
|
|
33
|
+
|
|
22
34
|
## Code Quality [MANDATORY]
|
|
23
35
|
|
|
24
36
|
- Refactor as you go — eliminate technical debt immediately
|
|
@@ -179,6 +179,8 @@ Use this table for runtime wiring, switching, or registration points. Record how
|
|
|
179
179
|
|
|
180
180
|
### Main Components
|
|
181
181
|
|
|
182
|
+
Repeat the block below for each component.
|
|
183
|
+
|
|
182
184
|
#### Component 1
|
|
183
185
|
|
|
184
186
|
- **Responsibility**: [Scope of responsibility for this component]
|
|
@@ -196,6 +198,38 @@ Use this table for runtime wiring, switching, or registration points. Record how
|
|
|
196
198
|
|
|
197
199
|
**Decision**: [reuse / extend / new] -- [rationale in 1-2 sentences]
|
|
198
200
|
|
|
201
|
+
### Minimal Surface Alternatives (When Introducing Maintenance-Surface Elements)
|
|
202
|
+
|
|
203
|
+
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.
|
|
204
|
+
|
|
205
|
+
#### Element 1: [name of the new element]
|
|
206
|
+
|
|
207
|
+
**Step 1 - Fixed Requirements**
|
|
208
|
+
- [AC ID or constraint ID]: [requirement / constraint text]
|
|
209
|
+
- [AC ID or constraint ID]: [requirement / constraint text]
|
|
210
|
+
|
|
211
|
+
**Steps 2-3 - Alternatives Compared**
|
|
212
|
+
|
|
213
|
+
| 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 |
|
|
214
|
+
|-------------|------------------------------------------------------|------------------------------|------------------------------------|--------------------------------------|-------------------------------------------------|-----------------------|
|
|
215
|
+
| [The added element as proposed] | | | | | | |
|
|
216
|
+
| [Subtractive alternative: derive / compute on demand / keep at caller / reuse existing / do not introduce new state] | | | | | | |
|
|
217
|
+
| [Optional third alternative] | | | | | | |
|
|
218
|
+
|
|
219
|
+
**Step 4 - Selected Alternative and Rationale**
|
|
220
|
+
- **Selected**: [alternative name]
|
|
221
|
+
- **Rationale**:
|
|
222
|
+
- If selected = smallest alternative considered: state "smallest alternative considered; no further reduction available"
|
|
223
|
+
- If selected > smallest: name the current requirement(s) from step 1 that smaller alternatives fail to satisfy
|
|
224
|
+
|
|
225
|
+
**Step 5 - Rejected Alternatives Log**
|
|
226
|
+
- [Alternative name]: [1-2 lines on what it was and why rejected]
|
|
227
|
+
- [Alternative name]: [1-2 lines on what it was and why rejected]
|
|
228
|
+
|
|
229
|
+
(Repeat the Element block above for each additional in-scope element.)
|
|
230
|
+
|
|
231
|
+
Rejected Alternatives Log is element-level. Future Extensibility below is design-level.
|
|
232
|
+
|
|
199
233
|
### Contract Definitions
|
|
200
234
|
|
|
201
235
|
```
|
|
@@ -355,9 +389,11 @@ Mark items as N/A with brief rationale when the feature has no relevant trust bo
|
|
|
355
389
|
|
|
356
390
|
## Future Extensibility
|
|
357
391
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
- **
|
|
392
|
+
This section records what was excluded from the current design surface. Speculative inclusions belong in a separate proposal.
|
|
393
|
+
|
|
394
|
+
- **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]
|
|
395
|
+
- **Intentional limitations**: [What was deliberately kept small and why]
|
|
396
|
+
- **Extension points (existing, with current consumers)**: [Interfaces or hooks already in use by named current consumers. Each entry names a current consumer]
|
|
361
397
|
|
|
362
398
|
## Alternative Solutions
|
|
363
399
|
|
|
@@ -250,7 +250,13 @@ Lower the verdict by one level only when at least one identifier mismatch has co
|
|
|
250
250
|
- [ ] identifierVerification contains mismatches only, and each mismatch includes confidence and evidence
|
|
251
251
|
|
|
252
252
|
### Escalation Criteria
|
|
253
|
-
Recommend higher-level review when
|
|
253
|
+
Recommend higher-level review when any condition below is true:
|
|
254
|
+
- Design Doc itself has deficiencies
|
|
255
|
+
- Security concerns discovered
|
|
256
|
+
- Critical performance issues found
|
|
257
|
+
- 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
|
|
258
|
+
|
|
259
|
+
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.
|
|
254
260
|
|
|
255
261
|
### Context-Specific Guidance
|
|
256
262
|
- **Prototypes/MVPs**: Prioritize functionality over completeness
|
|
@@ -99,6 +99,7 @@ For DesignDoc, additionally verify:
|
|
|
99
99
|
- [ ] Data-oriented designs contain concrete data design or Test Boundaries content, or an explicit N/A rationale
|
|
100
100
|
- [ ] Verification Strategy section present with correctness definition, target comparison, verification method, observable success indicator, normalized verification timing, and early verification point
|
|
101
101
|
- [ ] Output Comparison section present when the design changes existing observable behavior, an external contract, or a persisted data shape
|
|
102
|
+
- [ ] 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.
|
|
102
103
|
|
|
103
104
|
#### Gate 1: Quality Assessment (only after Gate 0 passes)
|
|
104
105
|
|
|
@@ -118,6 +119,7 @@ For DesignDoc, additionally verify:
|
|
|
118
119
|
- **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
|
|
119
120
|
- **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
|
|
120
121
|
- **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`)
|
|
122
|
+
- **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`)
|
|
121
123
|
- **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
|
|
122
124
|
|
|
123
125
|
**Perspective-specific Mode**:
|
|
@@ -275,6 +277,7 @@ Include in output when `prior_context_count > 0`:
|
|
|
275
277
|
- [ ] Code inspection evidence covers files relevant to design scope
|
|
276
278
|
- [ ] Dependencies described as existing verified against codebase or authoritative external source
|
|
277
279
|
- [ ] Field propagation map present when fields cross component boundaries
|
|
280
|
+
- [ ] Minimal Surface Alternatives covers every new in-scope element when applicable
|
|
278
281
|
|
|
279
282
|
## Review Criteria (for Comprehensive Mode)
|
|
280
283
|
|
|
@@ -16,9 +16,7 @@ You are a frontend technical design specialist AI assistant for creating Archite
|
|
|
16
16
|
|
|
17
17
|
## Required Skills [LOADING PROTOCOL]
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
**STEP 2**: For each skill NOT active → Execute BLOCKING READ of SKILL.md
|
|
21
|
-
**STEP 3**: CONFIRM all skills active before proceeding
|
|
19
|
+
Verify skills from [[skills.config]] are active. For each inactive skill, execute BLOCKING READ of SKILL.md, then confirm all skills active before proceeding.
|
|
22
20
|
|
|
23
21
|
**EVIDENCE REQUIRED:**
|
|
24
22
|
```
|
|
@@ -32,9 +30,8 @@ Skill Status:
|
|
|
32
30
|
|
|
33
31
|
## Initial Mandatory Tasks
|
|
34
32
|
|
|
35
|
-
**Progress Tracking**: Track
|
|
36
|
-
|
|
37
|
-
**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date).
|
|
33
|
+
**Progress Tracking**: Track work steps. Always include first "Confirm skill constraints" and final "Verify skill fidelity"; update progress upon completion.
|
|
34
|
+
**Current Date Retrieval**: Before starting, retrieve the actual current date from the operating environment.
|
|
38
35
|
|
|
39
36
|
## Document Creation Criteria
|
|
40
37
|
|
|
@@ -99,6 +96,37 @@ For each integration boundary, define:
|
|
|
99
96
|
- Output events or effects
|
|
100
97
|
- On Error behavior
|
|
101
98
|
|
|
99
|
+
### Minimal Surface Alternatives【Required when introducing maintenance-surface elements】
|
|
100
|
+
|
|
101
|
+
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".
|
|
102
|
+
|
|
103
|
+
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.
|
|
104
|
+
|
|
105
|
+
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.
|
|
106
|
+
|
|
107
|
+
1. **Fix Requirements**
|
|
108
|
+
- 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.
|
|
109
|
+
- 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.
|
|
110
|
+
|
|
111
|
+
2. **Diverge** (generate alternatives)
|
|
112
|
+
- Produce at least 2 alternative realizations that cover the same fixed requirements.
|
|
113
|
+
- 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.
|
|
114
|
+
|
|
115
|
+
3. **Compare** (record alternatives in a table)
|
|
116
|
+
|
|
117
|
+
| 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 |
|
|
118
|
+
|-------------|------------------------------------------------------|------------------------------|--------------------------------------|--------------------------------------|-------------------------------------------------|-----------------------|
|
|
119
|
+
|
|
120
|
+
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.
|
|
121
|
+
|
|
122
|
+
4. **Converge** (select)
|
|
123
|
+
- Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above.
|
|
124
|
+
- When the selected alternative is not the smallest, name the current requirement from step 1 that smaller alternatives fail to satisfy.
|
|
125
|
+
- Subjective-only rationales from coding-rules belong in the Subjective cost notes column as tiebreakers only.
|
|
126
|
+
|
|
127
|
+
5. **Record Rejected Alternatives**
|
|
128
|
+
- 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.
|
|
129
|
+
|
|
102
130
|
### Agreement Checklist【Most Important】
|
|
103
131
|
Must be performed at the beginning of Design Doc creation:
|
|
104
132
|
|
|
@@ -255,17 +283,14 @@ When external resources are recorded for the project:
|
|
|
255
283
|
## Document Output Format
|
|
256
284
|
|
|
257
285
|
### Document Creation
|
|
258
|
-
- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md
|
|
286
|
+
- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md`; check existing numbers, use max+1, initial status "Proposed"
|
|
259
287
|
- **Design Doc**: `docs/design/[feature-name]-design.md`
|
|
260
288
|
- Follow respective templates (see documentation-criteria skill: design-template.md, adr-template.md, ui-spec-template.md)
|
|
261
|
-
- For ADR, check existing numbers and use max+1, initial status is "Proposed"
|
|
262
289
|
|
|
263
290
|
## ADR Responsibility Boundaries
|
|
264
291
|
|
|
265
|
-
Include in ADR:
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
Implementation guidelines MUST only include principles (e.g., "Use custom hooks for logic reuse" is correct, "Implement in Phase 1" is not)
|
|
292
|
+
Include in ADR: decisions, rationale, principled guidelines. Exclude: schedules, implementation procedures, specific code.
|
|
293
|
+
Implementation guidelines MUST only include principles (e.g., "Use custom hooks for logic reuse" is correct, "Implement in Phase 1" is not).
|
|
269
294
|
|
|
270
295
|
## Implementation Sample Standards Compliance
|
|
271
296
|
|
|
@@ -320,6 +345,7 @@ Implementation sample creation checklist:
|
|
|
320
345
|
- [ ] Implementation approach selection rationale (vertical/horizontal/hybrid)
|
|
321
346
|
- [ ] Latest React best practices researched and references cited
|
|
322
347
|
- [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks
|
|
348
|
+
- [ ] **Minimal Surface Alternatives documented** (when maintenance-surface elements are introduced; N/A rationale when none)
|
|
323
349
|
|
|
324
350
|
**Reverse-engineer mode only**:
|
|
325
351
|
- [ ] Every architectural claim cites file:line evidence
|
|
@@ -352,13 +378,10 @@ Cover happy path, unhappy path, and edge cases including empty and loading state
|
|
|
352
378
|
|
|
353
379
|
## Latest Information Research
|
|
354
380
|
|
|
355
|
-
Use current-year queries and cite sources in
|
|
356
|
-
|
|
357
|
-
Reverse-engineer mode skips latest-information research because it documents the existing frontend.
|
|
381
|
+
Use current-year queries and cite sources in `## References` for create/update mode. Reverse-engineer mode skips this because it documents the existing frontend.
|
|
358
382
|
|
|
359
383
|
## Update Mode Operation
|
|
360
|
-
|
|
361
|
-
- **Design Doc**: Add revision section and record change history
|
|
384
|
+
ADR: update existing file for minor changes, create new file for major changes. Design Doc: add revision section and record change history.
|
|
362
385
|
|
|
363
386
|
## Reverse-Engineer Mode (As-Is Documentation)
|
|
364
387
|
|
|
@@ -369,6 +392,7 @@ What to skip:
|
|
|
369
392
|
- Option comparison
|
|
370
393
|
- Change Impact Map
|
|
371
394
|
- Implementation Approach Decision
|
|
395
|
+
- Minimal Surface Alternatives
|
|
372
396
|
- Latest Information Research
|
|
373
397
|
|
|
374
398
|
Execution steps:
|
|
@@ -16,9 +16,7 @@ You are a technical design specialist AI assistant for creating Architecture Dec
|
|
|
16
16
|
|
|
17
17
|
## Required Skills [LOADING PROTOCOL]
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
**STEP 2**: For each skill NOT active → Execute BLOCKING READ of SKILL.md
|
|
21
|
-
**STEP 3**: CONFIRM all skills active before proceeding
|
|
19
|
+
Verify skills from [[skills.config]] are active. For each inactive skill, execute BLOCKING READ of SKILL.md, then confirm all skills active before proceeding.
|
|
22
20
|
|
|
23
21
|
**EVIDENCE REQUIRED:**
|
|
24
22
|
```
|
|
@@ -32,9 +30,8 @@ Skill Status:
|
|
|
32
30
|
|
|
33
31
|
## Initial Mandatory Tasks
|
|
34
32
|
|
|
35
|
-
**Progress Tracking**: Track
|
|
36
|
-
|
|
37
|
-
**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date).
|
|
33
|
+
**Progress Tracking**: Track work steps. Always include first "Confirm skill constraints" and final "Verify skill fidelity"; update progress upon completion.
|
|
34
|
+
**Current Date Retrieval**: Before starting, retrieve the actual current date from the operating environment.
|
|
38
35
|
|
|
39
36
|
## Document Creation Criteria
|
|
40
37
|
|
|
@@ -130,6 +127,37 @@ When the design introduces or significantly modifies data structures:
|
|
|
130
127
|
- 3+ criteria fail → New structure justified
|
|
131
128
|
- Record decision and rationale in Design Doc
|
|
132
129
|
|
|
130
|
+
### Minimal Surface Alternatives【Required when introducing maintenance-surface elements】
|
|
131
|
+
|
|
132
|
+
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".
|
|
133
|
+
|
|
134
|
+
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.
|
|
135
|
+
|
|
136
|
+
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.
|
|
137
|
+
|
|
138
|
+
1. **Fix Requirements**
|
|
139
|
+
- 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.
|
|
140
|
+
- 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.
|
|
141
|
+
|
|
142
|
+
2. **Diverge** (generate alternatives)
|
|
143
|
+
- Produce at least 2 alternative realizations that cover the same fixed requirements.
|
|
144
|
+
- 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.
|
|
145
|
+
|
|
146
|
+
3. **Compare** (record alternatives in a table)
|
|
147
|
+
|
|
148
|
+
| 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 |
|
|
149
|
+
|-------------|------------------------------------------------------|------------------------------|------------------------------------|--------------------------------------|-------------------------------------------------|-----------------------|
|
|
150
|
+
|
|
151
|
+
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.
|
|
152
|
+
|
|
153
|
+
4. **Converge** (select)
|
|
154
|
+
- Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above.
|
|
155
|
+
- When the selected alternative is not the smallest, name the current requirement from step 1 that smaller alternatives fail to satisfy.
|
|
156
|
+
- Subjective-only rationales from coding-rules belong in the Subjective cost notes column as tiebreakers only.
|
|
157
|
+
|
|
158
|
+
5. **Record Rejected Alternatives**
|
|
159
|
+
- 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.
|
|
160
|
+
|
|
133
161
|
### Integration Points【Important】
|
|
134
162
|
Document all integration points with existing systems in a "## Integration Point Map" section.
|
|
135
163
|
|
|
@@ -285,17 +313,14 @@ Confirm and document conflicts with existing systems at each integration point t
|
|
|
285
313
|
## Document Output Format
|
|
286
314
|
|
|
287
315
|
### Document Creation
|
|
288
|
-
- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md
|
|
316
|
+
- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md`; check existing numbers, use max+1, initial status "Proposed"
|
|
289
317
|
- **Design Doc**: `docs/design/[feature-name]-design.md`
|
|
290
318
|
- Follow respective templates (`template.md`)
|
|
291
|
-
- For ADR, check existing numbers and use max+1, initial status is "Proposed"
|
|
292
319
|
|
|
293
320
|
## ADR Responsibility Boundaries
|
|
294
321
|
|
|
295
|
-
Include in ADR:
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
Implementation guidelines MUST only include principles (e.g., "Use dependency injection" is correct, "Implement in Phase 1" is not)
|
|
322
|
+
Include in ADR: decisions, rationale, principled guidelines. Exclude: schedules, implementation procedures, specific code.
|
|
323
|
+
Implementation guidelines MUST only include principles (e.g., "Use dependency injection" is correct, "Implement in Phase 1" is not).
|
|
299
324
|
|
|
300
325
|
## Implementation Sample Standards Compliance
|
|
301
326
|
|
|
@@ -343,6 +368,7 @@ Implementation sample creation checklist:
|
|
|
343
368
|
- [ ] Latest best practices researched and references cited
|
|
344
369
|
- [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks
|
|
345
370
|
- [ ] **Data representation decision documented** (when new structures introduced)
|
|
371
|
+
- [ ] **Minimal Surface Alternatives documented** (when maintenance-surface elements are introduced; N/A rationale when none)
|
|
346
372
|
- [ ] **Field propagation map included** (when fields cross boundaries)
|
|
347
373
|
- [ ] **Verification Strategy defined** (correctness definition, target comparison, verification method, observable success indicator, timing, early verification point)
|
|
348
374
|
- [ ] **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.
|
|
|
380
406
|
|
|
381
407
|
## Latest Information Research
|
|
382
408
|
|
|
383
|
-
Use current-year queries and cite sources in
|
|
384
|
-
|
|
385
|
-
Reverse-engineer mode skips latest-information research because it documents what exists.
|
|
409
|
+
Use current-year queries and cite sources in `## References` for create/update mode. Reverse-engineer mode skips this because it documents what exists.
|
|
386
410
|
|
|
387
411
|
## Update Mode Operation
|
|
388
|
-
|
|
389
|
-
- **Design Doc**: Add revision section and record change history
|
|
412
|
+
ADR: update existing file for minor changes, create new file for major changes. Design Doc: add revision section and record change history.
|
|
390
413
|
|
|
391
414
|
## Reverse-Engineer Mode (As-Is Documentation)
|
|
392
415
|
|
|
@@ -398,6 +421,7 @@ What to skip:
|
|
|
398
421
|
- Change Impact Map
|
|
399
422
|
- Field Propagation Map
|
|
400
423
|
- Implementation Approach Decision
|
|
424
|
+
- Minimal Surface Alternatives
|
|
401
425
|
- Latest Information Research
|
|
402
426
|
|
|
403
427
|
Execution steps:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "codex-workflows",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.2",
|
|
4
4
|
"description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Shinsuke Kagawa",
|
|
@@ -8,6 +8,10 @@
|
|
|
8
8
|
"type": "git",
|
|
9
9
|
"url": "https://github.com/shinpr/codex-workflows"
|
|
10
10
|
},
|
|
11
|
+
"scripts": {
|
|
12
|
+
"check:skills-index": "node scripts/check-skills-index.mjs",
|
|
13
|
+
"hooks:install": "git config core.hooksPath scripts/hooks"
|
|
14
|
+
},
|
|
11
15
|
"bin": {
|
|
12
16
|
"codex-workflows": "./bin/cli.js"
|
|
13
17
|
},
|