ai-eng-system 0.2.1 → 0.2.3

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/README.md CHANGED
@@ -65,6 +65,8 @@ See [docs/spec-driven-workflow.md](./docs/spec-driven-workflow.md) for complete
65
65
 
66
66
  > **🔄 Ralph Wiggum**: Add `--ralph` flag to any phase command for persistent iteration. Perfect for complex tasks requiring multiple refinement cycles. [Learn more →](./docs/ralph-wiggum-integration-complete.md)
67
67
 
68
+ > **🛠️ Fixed (v0.2.2)**: Ralph Wiggum now runs continuously without stopping between phases. Full backward compatibility maintained. [Fix details →](./docs/ralph-wiggum-autonomous-looping-fix.md)
69
+
68
70
  ### Additional Commands (13 total)
69
71
  - `/ai-eng/optimize` - Prompt enhancement (+45% quality)
70
72
  - `/ai-eng/deploy` - Pre-deployment checklists
@@ -493,25 +493,11 @@ Successful planning achieves:
493
493
  - ✅ Dependencies are clearly documented
494
494
  - ✅ All spec acceptance criteria are covered (if spec exists)
495
495
  - ✅ Supporting artifacts generated (data-model, contracts)
496
- - ✅ Risk assessment completed
497
- - ✅ Testing strategy defined
498
- - ✅ Ready to feed into `/ai-eng/work`
499
-
500
- ## Execution
501
-
502
- After planning, execute the plan using:
503
-
504
- ```bash
505
- bun run scripts/run-command.ts plan "$ARGUMENTS" [options]
506
- ```
507
-
508
- For example:
509
- - `bun run scripts/run-command.ts plan "implement auth" --from-spec=specs/auth/spec.md --output=plans/auth.yaml`
510
- - `bun run scripts/run-command.ts plan --from-research=docs/research/auth.md --scope=implementation`
511
-
512
- After creating the plan, rate your confidence in its completeness and accuracy (0.0-1.0). Identify any uncertainties about task decomposition, missing dependencies, or areas where acceptance criteria may be ambiguous. Note any implementation risks that weren't adequately addressed in the plan.
513
-
514
- ## Ralph Wiggum Iteration Mode
496
+ - ✅ Risk assessment completed
497
+ - ✅ Testing strategy defined
498
+ - ✅ Ready to feed into `/ai-eng/work`
499
+
500
+ ## Ralph Wiggum Iteration Mode
515
501
 
516
502
  When `--ralph` flag is enabled, the planning process follows a persistent refinement cycle:
517
503
 
@@ -65,6 +65,21 @@ I bet you can't manage continuous iteration across all workflow phases without g
65
65
  /ai-eng/ralph-wiggum "user authentication" --dry-run
66
66
  ```
67
67
 
68
+ ## How This Command Works
69
+
70
+ This command is a **self-orchestrating prompt** - when you invoke `/ai-eng/ralph-wiggum`, the AI reads these instructions and executes each phase directly within the conversation.
71
+
72
+ **Execution Model:**
73
+ 1. **NOT a CLI script** - There is no external runner. The AI IS the executor.
74
+ 2. **Phase commands are internal** - When instructions say "Execute `/ai-eng/research`", the AI follows that command's instructions directly (not spawning a subprocess).
75
+ 3. **Continuous flow** - The AI proceeds through all phases autonomously unless checkpoints are set.
76
+
77
+ **To run this command:**
78
+ - Claude Code: Type `/ai-eng/ralph-wiggum "your feature description"`
79
+ - OpenCode: Type `/ai-eng/ralph-wiggum "your feature description"`
80
+
81
+ The AI will then follow all phases in this document from start to finish.
82
+
68
83
  ## Options
69
84
 
70
85
  | Option | Type | Default | Description |
@@ -85,6 +100,7 @@ I bet you can't manage continuous iteration across all workflow phases without g
85
100
  | `--dry-run` | boolean | false | Show plan without executing |
86
101
  | `--resume` | boolean | false | Resume from last checkpoint |
87
102
  | `--parallel` | boolean | false | Run phases in parallel where safe |
103
+ | `--refine-each-phase` | boolean | false | Re-invoke prompt-refinement at each phase (interactive mode) |
88
104
 
89
105
  **Default Completion Promise:**
90
106
  ```
@@ -95,6 +111,18 @@ I bet you can't manage continuous iteration across all workflow phases without g
95
111
 
96
112
  Load `skills/prompt-refinement/SKILL.md` and use phase: `plan` to transform your prompt into structured TCRO format (Task, Context, Requirements, Output). Ask clarifying questions if feature description, acceptance criteria, technical approach, or quality gates are unclear.
97
113
 
114
+ **Store the refined output as `$REFINED_CONTEXT`** - this will be used for ALL subsequent phases without re-invoking prompt-refinement.
115
+
116
+ ### Autonomous Execution Model
117
+
118
+ After Phase 0 completes:
119
+ 1. **Context is locked**: The refined TCRO applies to ALL subsequent phases
120
+ 2. **No re-refinement**: Do NOT invoke prompt-refinement again (unless `--refine-each-phase` is set)
121
+ 3. **Continuous execution**: Proceed through phases without pausing for user input
122
+ 4. **Checkpoints are optional**: Only pause if `--checkpoint` flag is explicitly set
123
+
124
+ This enables overnight/unattended execution as intended by the Ralph Wiggum pattern.
125
+
98
126
  ## Phase 1: Git Setup
99
127
 
100
128
  ### 1.1 Create Feature Branch
@@ -137,7 +165,7 @@ This is the core Ralph Wiggum pattern - continuous iteration until completion.
137
165
 
138
166
  **Goal**: Gather context, patterns, and technical guidance
139
167
 
140
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
168
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
141
169
 
142
170
  **Execute**:
143
171
  ```bash
@@ -157,11 +185,13 @@ This is the core Ralph Wiggum pattern - continuous iteration until completion.
157
185
 
158
186
  **Checkpoint** (if `--checkpoint=all`): Pause and ask for approval before proceeding
159
187
 
188
+ **→ CONTINUE**: Immediately proceed to Phase 2.3 (Specify) without waiting for user input.
189
+
160
190
  ### 2.3 Specify Phase (if not skipped)
161
191
 
162
192
  **Goal**: Create detailed specification with user stories and acceptance criteria
163
193
 
164
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
194
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
165
195
 
166
196
  **Execute**:
167
197
  ```bash
@@ -186,11 +216,13 @@ This is the core Ralph Wiggum pattern - continuous iteration until completion.
186
216
 
187
217
  **Checkpoint** (if `--checkpoint=all`): Pause and ask for approval
188
218
 
219
+ **→ CONTINUE**: Immediately proceed to Phase 2.4 (Plan) without waiting for user input.
220
+
189
221
  ### 2.4 Plan Phase (if not skipped)
190
222
 
191
223
  **Goal**: Create implementation plan with tasks and dependencies
192
224
 
193
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
225
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
194
226
 
195
227
  **Execute**:
196
228
  ```bash
@@ -215,11 +247,13 @@ This is the core Ralph Wiggum pattern - continuous iteration until completion.
215
247
 
216
248
  **Checkpoint** (if `--checkpoint=all`): Pause and ask for approval
217
249
 
250
+ **→ CONTINUE**: Immediately proceed to Phase 2.5 (Work) without waiting for user input.
251
+
218
252
  ### 2.5 Work Phase
219
253
 
220
254
  **Goal**: Implement feature with TDD, quality gates, and iterative refinement
221
255
 
222
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
256
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
223
257
 
224
258
  **Execute**:
225
259
  ```bash
@@ -248,11 +282,13 @@ npm test && npm run lint && npm run build
248
282
 
249
283
  **Checkpoint** (if `--checkpoint=all` or `--checkpoint=review`): Pause and ask for approval
250
284
 
285
+ **→ CONTINUE**: Immediately proceed to Phase 2.6 (Review) without waiting for user input.
286
+
251
287
  ### 2.6 Review Phase
252
288
 
253
289
  **Goal**: Comprehensive multi-perspective code review
254
290
 
255
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
291
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
256
292
 
257
293
  **Execute**:
258
294
  ```bash
@@ -271,6 +307,8 @@ npm test && npm run lint && npm run build
271
307
 
272
308
  **Checkpoint** (if `--checkpoint=all` or `--checkpoint=review`): Pause and ask for approval
273
309
 
310
+ **→ CONTINUE**: Immediately proceed to Phase 3 (Gap Analysis) without waiting for user input.
311
+
274
312
  ## Phase 3: Gap Analysis
275
313
 
276
314
  ### 3.1 Analyze Review Findings
@@ -354,6 +392,12 @@ Based on gap analysis from 3.1:
354
392
  "max_cycles": 5,
355
393
  "current_phase": "WORK",
356
394
  "completed_phases": ["RESEARCH", "SPECIFY", "PLAN"],
395
+ "refined_context": {
396
+ "task": "Specific, actionable task statement",
397
+ "context": "Broader system, goals, constraints from CLAUDE.md",
398
+ "requirements": ["Must-have requirement 1", "Must-have requirement 2"],
399
+ "output": "What should be delivered (working code, tests, docs, PR)"
400
+ },
357
401
  "artifacts": {
358
402
  "research": "docs/research/2026-01-05-user-authentication.md",
359
403
  "spec": "specs/user-authentication/spec.md",
@@ -739,22 +783,8 @@ Successful build achieves:
739
783
  - ✅ Checkpoints saved and can be loaded
740
784
  - ✅ Progress displayed at appropriate verbosity
741
785
  - ✅ Safety limits enforced (max cycles, stuck detection)
742
- - ✅ Token usage tracked and displayed
743
- - ✅ Draft PR created with comprehensive summary
744
- - ✅ Build report generated with all artifacts and metrics
745
-
746
- ---
747
-
748
- ## Execution
749
-
750
- After creating this command, the agent can invoke it with:
751
-
752
- ```bash
753
- bun run scripts/run-command.ts ralph-wiggum "feature description" [options]
754
- ```
755
-
756
- Examples:
757
- - `bun run scripts/run-command.ts ralph-wiggum "implement user auth" --checkpoint=all --verbose`
758
- - `bun run scripts/run-command.ts ralph-wiggum "API caching" --from-spec=specs/cache/spec.md --resume`
786
+ - ✅ Token usage tracked and displayed
787
+ - ✅ Draft PR created with comprehensive summary
788
+ - ✅ Build report generated with all artifacts and metrics
759
789
 
760
- After completing the full cycle, rate your confidence in feature completeness and quality (0.0-1.0). Identify any uncertainties about phase transitions, iterations that were inefficient, or areas where quality gates may have been too lenient or strict. Note any workflow improvements that could enhance future cycles.
790
+ ---
@@ -115,24 +115,12 @@ For each finding provide:
115
115
 
116
116
  ## Summary
117
117
 
118
+
118
119
  End with overall assessment: APPROVE, CHANGES_REQUESTED, or NEEDS_DISCUSSION.
119
120
 
120
121
  After completing review, rate your confidence in findings comprehensiveness (0.0-1.0). Identify any uncertainties about severity classifications, areas where review coverage may have been insufficient, or assumptions about code context. Note any perspectives that should have been applied or findings that may be false positives.
121
-
122
- ## Execution
123
-
124
- Run a review using:
125
-
126
- ```bash
127
- bun run scripts/run-command.ts review "$ARGUMENTS" [options]
128
- ```
129
-
130
- For example:
131
- - `bun run scripts/run-command.ts review "src/" --type=security --severity=high --output=security-review.json`
132
- - `bun run scripts/run-command.ts review "." --focus=performance --verbose`
133
-
134
- ## Ralph Wiggum Iteration Mode
135
-
122
+
123
+ ## Ralph Wiggum Iteration Mode
136
124
  When `--ralph` flag is enabled, the review process follows a persistent refinement cycle:
137
125
 
138
126
  ### Ralph Wiggum Review Cycle
@@ -288,28 +288,14 @@ Always consider these categories:
288
288
  ## Success Criteria
289
289
 
290
290
  Successful specification achieves:
291
- - ✅ Well-structured user stories with acceptance criteria
292
- - ✅ All non-functional requirements defined
293
- - ✅ Ambiguities marked with [NEEDS CLARIFICATION]
294
- - ✅ Aligned with project philosophy (CLAUDE.md)
295
- - ✅ Ready to feed into `/ai-eng/plan`
296
- - ✅ User reviewed and approved
297
-
298
- ## Execution
299
-
300
- After specification, create a plan using:
301
-
302
- ```bash
303
- bun run scripts/run-command.ts specify "$ARGUMENTS" [options]
304
- ```
305
-
306
- For example:
307
- - `bun run scripts/run-command.ts specify "user auth" --from-research=docs/research/auth.md --output=specs/auth/spec.md`
308
- - `bun run scripts/run-command.ts specify "payment system" --template=api --verbose`
309
-
310
- After creating specification, rate your confidence in its completeness and clarity (0.0-1.0). Identify any uncertainties about user requirements, areas where acceptance criteria may be ambiguous, or constraints that weren't adequately considered. Note any open questions or clarifications needed from stakeholders.
311
-
312
- ## Integration
291
+ - ✅ Well-structured user stories with acceptance criteria
292
+ - ✅ All non-functional requirements defined
293
+ - ✅ Ambiguities marked with [NEEDS CLARIFICATION]
294
+ - ✅ Aligned with project philosophy (CLAUDE.md)
295
+ - ✅ Ready to feed into `/ai-eng/plan`
296
+ - ✅ User reviewed and approved
297
+
298
+ ## Integration
313
299
 
314
300
  - Can use output from `/ai-eng/research` via `--from-research`
315
301
  - Feeds into `/ai-eng/plan` for implementation planning
@@ -573,29 +573,14 @@ This will:
573
573
  ## Success Criteria
574
574
 
575
575
  A work session is successful when:
576
- - ✅ All tasks completed
577
- - ✅ All quality gates passed
578
- - ✅ All tests passing
579
- - ✅ Build succeeds
580
- - ✅ PR created and reviewed
581
- - ✅ Code merged to main
582
-
583
- ## Execution
584
-
585
- Execute a plan using:
586
-
587
- ```bash
588
- bun run scripts/run-command.ts work "$ARGUMENTS" [options]
589
- ```
590
-
591
- For example:
592
- - `bun run scripts/run-command.ts work "specs/auth/plan.yaml" --verbose`
593
- - `bun run scripts/run-command.ts work --from-plan=plans/auth.yaml --continue`
594
- - `bun run scripts/run-command.ts work "FEAT-001" --dry-run`
595
-
596
- After completing implementation, rate your confidence in code quality and completeness (0.0-1.0). Identify any uncertainties about test coverage, areas where quality gates may have been too lenient, or implementation details that may need follow-up. Note any technical debt or known issues that should be tracked.
597
-
598
- ## Integration
576
+ - ✅ All tasks completed
577
+ - ✅ All quality gates passed
578
+ - ✅ All tests passing
579
+ - ✅ Build succeeds
580
+ - ✅ PR created and reviewed
581
+ - ✅ Code merged to main
582
+
583
+ ## Integration
599
584
 
600
585
  - Reads from `/ai-eng/plan` output (plan.yaml)
601
586
  - Validates against `/ai-eng/specify` output (spec.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-eng-system",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "AI Engineering System with context engineering and research orchestration for Claude Code",
5
5
  "author": {
6
6
  "name": "v1truv1us"
@@ -493,25 +493,11 @@ Successful planning achieves:
493
493
  - ✅ Dependencies are clearly documented
494
494
  - ✅ All spec acceptance criteria are covered (if spec exists)
495
495
  - ✅ Supporting artifacts generated (data-model, contracts)
496
- - ✅ Risk assessment completed
497
- - ✅ Testing strategy defined
498
- - ✅ Ready to feed into `/ai-eng/work`
499
-
500
- ## Execution
501
-
502
- After planning, execute the plan using:
503
-
504
- ```bash
505
- bun run scripts/run-command.ts plan "$ARGUMENTS" [options]
506
- ```
507
-
508
- For example:
509
- - `bun run scripts/run-command.ts plan "implement auth" --from-spec=specs/auth/spec.md --output=plans/auth.yaml`
510
- - `bun run scripts/run-command.ts plan --from-research=docs/research/auth.md --scope=implementation`
511
-
512
- After creating the plan, rate your confidence in its completeness and accuracy (0.0-1.0). Identify any uncertainties about task decomposition, missing dependencies, or areas where acceptance criteria may be ambiguous. Note any implementation risks that weren't adequately addressed in the plan.
513
-
514
- ## Ralph Wiggum Iteration Mode
496
+ - ✅ Risk assessment completed
497
+ - ✅ Testing strategy defined
498
+ - ✅ Ready to feed into `/ai-eng/work`
499
+
500
+ ## Ralph Wiggum Iteration Mode
515
501
 
516
502
  When `--ralph` flag is enabled, the planning process follows a persistent refinement cycle:
517
503
 
@@ -65,6 +65,21 @@ I bet you can't manage continuous iteration across all workflow phases without g
65
65
  /ai-eng/ralph-wiggum "user authentication" --dry-run
66
66
  ```
67
67
 
68
+ ## How This Command Works
69
+
70
+ This command is a **self-orchestrating prompt** - when you invoke `/ai-eng/ralph-wiggum`, the AI reads these instructions and executes each phase directly within the conversation.
71
+
72
+ **Execution Model:**
73
+ 1. **NOT a CLI script** - There is no external runner. The AI IS the executor.
74
+ 2. **Phase commands are internal** - When instructions say "Execute `/ai-eng/research`", the AI follows that command's instructions directly (not spawning a subprocess).
75
+ 3. **Continuous flow** - The AI proceeds through all phases autonomously unless checkpoints are set.
76
+
77
+ **To run this command:**
78
+ - Claude Code: Type `/ai-eng/ralph-wiggum "your feature description"`
79
+ - OpenCode: Type `/ai-eng/ralph-wiggum "your feature description"`
80
+
81
+ The AI will then follow all phases in this document from start to finish.
82
+
68
83
  ## Options
69
84
 
70
85
  | Option | Type | Default | Description |
@@ -85,6 +100,7 @@ I bet you can't manage continuous iteration across all workflow phases without g
85
100
  | `--dry-run` | boolean | false | Show plan without executing |
86
101
  | `--resume` | boolean | false | Resume from last checkpoint |
87
102
  | `--parallel` | boolean | false | Run phases in parallel where safe |
103
+ | `--refine-each-phase` | boolean | false | Re-invoke prompt-refinement at each phase (interactive mode) |
88
104
 
89
105
  **Default Completion Promise:**
90
106
  ```
@@ -95,6 +111,18 @@ I bet you can't manage continuous iteration across all workflow phases without g
95
111
 
96
112
  Load `skills/prompt-refinement/SKILL.md` and use phase: `plan` to transform your prompt into structured TCRO format (Task, Context, Requirements, Output). Ask clarifying questions if feature description, acceptance criteria, technical approach, or quality gates are unclear.
97
113
 
114
+ **Store the refined output as `$REFINED_CONTEXT`** - this will be used for ALL subsequent phases without re-invoking prompt-refinement.
115
+
116
+ ### Autonomous Execution Model
117
+
118
+ After Phase 0 completes:
119
+ 1. **Context is locked**: The refined TCRO applies to ALL subsequent phases
120
+ 2. **No re-refinement**: Do NOT invoke prompt-refinement again (unless `--refine-each-phase` is set)
121
+ 3. **Continuous execution**: Proceed through phases without pausing for user input
122
+ 4. **Checkpoints are optional**: Only pause if `--checkpoint` flag is explicitly set
123
+
124
+ This enables overnight/unattended execution as intended by the Ralph Wiggum pattern.
125
+
98
126
  ## Phase 1: Git Setup
99
127
 
100
128
  ### 1.1 Create Feature Branch
@@ -137,7 +165,7 @@ This is the core Ralph Wiggum pattern - continuous iteration until completion.
137
165
 
138
166
  **Goal**: Gather context, patterns, and technical guidance
139
167
 
140
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
168
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
141
169
 
142
170
  **Execute**:
143
171
  ```bash
@@ -157,11 +185,13 @@ This is the core Ralph Wiggum pattern - continuous iteration until completion.
157
185
 
158
186
  **Checkpoint** (if `--checkpoint=all`): Pause and ask for approval before proceeding
159
187
 
188
+ **→ CONTINUE**: Immediately proceed to Phase 2.3 (Specify) without waiting for user input.
189
+
160
190
  ### 2.3 Specify Phase (if not skipped)
161
191
 
162
192
  **Goal**: Create detailed specification with user stories and acceptance criteria
163
193
 
164
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
194
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
165
195
 
166
196
  **Execute**:
167
197
  ```bash
@@ -186,11 +216,13 @@ This is the core Ralph Wiggum pattern - continuous iteration until completion.
186
216
 
187
217
  **Checkpoint** (if `--checkpoint=all`): Pause and ask for approval
188
218
 
219
+ **→ CONTINUE**: Immediately proceed to Phase 2.4 (Plan) without waiting for user input.
220
+
189
221
  ### 2.4 Plan Phase (if not skipped)
190
222
 
191
223
  **Goal**: Create implementation plan with tasks and dependencies
192
224
 
193
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
225
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
194
226
 
195
227
  **Execute**:
196
228
  ```bash
@@ -215,11 +247,13 @@ This is the core Ralph Wiggum pattern - continuous iteration until completion.
215
247
 
216
248
  **Checkpoint** (if `--checkpoint=all`): Pause and ask for approval
217
249
 
250
+ **→ CONTINUE**: Immediately proceed to Phase 2.5 (Work) without waiting for user input.
251
+
218
252
  ### 2.5 Work Phase
219
253
 
220
254
  **Goal**: Implement feature with TDD, quality gates, and iterative refinement
221
255
 
222
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
256
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
223
257
 
224
258
  **Execute**:
225
259
  ```bash
@@ -248,11 +282,13 @@ npm test && npm run lint && npm run build
248
282
 
249
283
  **Checkpoint** (if `--checkpoint=all` or `--checkpoint=review`): Pause and ask for approval
250
284
 
285
+ **→ CONTINUE**: Immediately proceed to Phase 2.6 (Review) without waiting for user input.
286
+
251
287
  ### 2.6 Review Phase
252
288
 
253
289
  **Goal**: Comprehensive multi-perspective code review
254
290
 
255
- **Load Ralph Wiggum skill**: `skills/workflow/ralph-wiggum/SKILL.md`
291
+ **Context**: Use `$REFINED_CONTEXT` from Phase 0. Do NOT re-invoke prompt-refinement unless `--refine-each-phase` is set.
256
292
 
257
293
  **Execute**:
258
294
  ```bash
@@ -271,6 +307,8 @@ npm test && npm run lint && npm run build
271
307
 
272
308
  **Checkpoint** (if `--checkpoint=all` or `--checkpoint=review`): Pause and ask for approval
273
309
 
310
+ **→ CONTINUE**: Immediately proceed to Phase 3 (Gap Analysis) without waiting for user input.
311
+
274
312
  ## Phase 3: Gap Analysis
275
313
 
276
314
  ### 3.1 Analyze Review Findings
@@ -354,6 +392,12 @@ Based on gap analysis from 3.1:
354
392
  "max_cycles": 5,
355
393
  "current_phase": "WORK",
356
394
  "completed_phases": ["RESEARCH", "SPECIFY", "PLAN"],
395
+ "refined_context": {
396
+ "task": "Specific, actionable task statement",
397
+ "context": "Broader system, goals, constraints from CLAUDE.md",
398
+ "requirements": ["Must-have requirement 1", "Must-have requirement 2"],
399
+ "output": "What should be delivered (working code, tests, docs, PR)"
400
+ },
357
401
  "artifacts": {
358
402
  "research": "docs/research/2026-01-05-user-authentication.md",
359
403
  "spec": "specs/user-authentication/spec.md",
@@ -739,22 +783,8 @@ Successful build achieves:
739
783
  - ✅ Checkpoints saved and can be loaded
740
784
  - ✅ Progress displayed at appropriate verbosity
741
785
  - ✅ Safety limits enforced (max cycles, stuck detection)
742
- - ✅ Token usage tracked and displayed
743
- - ✅ Draft PR created with comprehensive summary
744
- - ✅ Build report generated with all artifacts and metrics
745
-
746
- ---
747
-
748
- ## Execution
749
-
750
- After creating this command, the agent can invoke it with:
751
-
752
- ```bash
753
- bun run scripts/run-command.ts ralph-wiggum "feature description" [options]
754
- ```
755
-
756
- Examples:
757
- - `bun run scripts/run-command.ts ralph-wiggum "implement user auth" --checkpoint=all --verbose`
758
- - `bun run scripts/run-command.ts ralph-wiggum "API caching" --from-spec=specs/cache/spec.md --resume`
786
+ - ✅ Token usage tracked and displayed
787
+ - ✅ Draft PR created with comprehensive summary
788
+ - ✅ Build report generated with all artifacts and metrics
759
789
 
760
- After completing the full cycle, rate your confidence in feature completeness and quality (0.0-1.0). Identify any uncertainties about phase transitions, iterations that were inefficient, or areas where quality gates may have been too lenient or strict. Note any workflow improvements that could enhance future cycles.
790
+ ---
@@ -115,24 +115,12 @@ For each finding provide:
115
115
 
116
116
  ## Summary
117
117
 
118
+
118
119
  End with overall assessment: APPROVE, CHANGES_REQUESTED, or NEEDS_DISCUSSION.
119
120
 
120
121
  After completing review, rate your confidence in findings comprehensiveness (0.0-1.0). Identify any uncertainties about severity classifications, areas where review coverage may have been insufficient, or assumptions about code context. Note any perspectives that should have been applied or findings that may be false positives.
121
-
122
- ## Execution
123
-
124
- Run a review using:
125
-
126
- ```bash
127
- bun run scripts/run-command.ts review "$ARGUMENTS" [options]
128
- ```
129
-
130
- For example:
131
- - `bun run scripts/run-command.ts review "src/" --type=security --severity=high --output=security-review.json`
132
- - `bun run scripts/run-command.ts review "." --focus=performance --verbose`
133
-
134
- ## Ralph Wiggum Iteration Mode
135
-
122
+
123
+ ## Ralph Wiggum Iteration Mode
136
124
  When `--ralph` flag is enabled, the review process follows a persistent refinement cycle:
137
125
 
138
126
  ### Ralph Wiggum Review Cycle
@@ -288,28 +288,14 @@ Always consider these categories:
288
288
  ## Success Criteria
289
289
 
290
290
  Successful specification achieves:
291
- - ✅ Well-structured user stories with acceptance criteria
292
- - ✅ All non-functional requirements defined
293
- - ✅ Ambiguities marked with [NEEDS CLARIFICATION]
294
- - ✅ Aligned with project philosophy (CLAUDE.md)
295
- - ✅ Ready to feed into `/ai-eng/plan`
296
- - ✅ User reviewed and approved
297
-
298
- ## Execution
299
-
300
- After specification, create a plan using:
301
-
302
- ```bash
303
- bun run scripts/run-command.ts specify "$ARGUMENTS" [options]
304
- ```
305
-
306
- For example:
307
- - `bun run scripts/run-command.ts specify "user auth" --from-research=docs/research/auth.md --output=specs/auth/spec.md`
308
- - `bun run scripts/run-command.ts specify "payment system" --template=api --verbose`
309
-
310
- After creating specification, rate your confidence in its completeness and clarity (0.0-1.0). Identify any uncertainties about user requirements, areas where acceptance criteria may be ambiguous, or constraints that weren't adequately considered. Note any open questions or clarifications needed from stakeholders.
311
-
312
- ## Integration
291
+ - ✅ Well-structured user stories with acceptance criteria
292
+ - ✅ All non-functional requirements defined
293
+ - ✅ Ambiguities marked with [NEEDS CLARIFICATION]
294
+ - ✅ Aligned with project philosophy (CLAUDE.md)
295
+ - ✅ Ready to feed into `/ai-eng/plan`
296
+ - ✅ User reviewed and approved
297
+
298
+ ## Integration
313
299
 
314
300
  - Can use output from `/ai-eng/research` via `--from-research`
315
301
  - Feeds into `/ai-eng/plan` for implementation planning
@@ -573,29 +573,14 @@ This will:
573
573
  ## Success Criteria
574
574
 
575
575
  A work session is successful when:
576
- - ✅ All tasks completed
577
- - ✅ All quality gates passed
578
- - ✅ All tests passing
579
- - ✅ Build succeeds
580
- - ✅ PR created and reviewed
581
- - ✅ Code merged to main
582
-
583
- ## Execution
584
-
585
- Execute a plan using:
586
-
587
- ```bash
588
- bun run scripts/run-command.ts work "$ARGUMENTS" [options]
589
- ```
590
-
591
- For example:
592
- - `bun run scripts/run-command.ts work "specs/auth/plan.yaml" --verbose`
593
- - `bun run scripts/run-command.ts work --from-plan=plans/auth.yaml --continue`
594
- - `bun run scripts/run-command.ts work "FEAT-001" --dry-run`
595
-
596
- After completing implementation, rate your confidence in code quality and completeness (0.0-1.0). Identify any uncertainties about test coverage, areas where quality gates may have been too lenient, or implementation details that may need follow-up. Note any technical debt or known issues that should be tracked.
597
-
598
- ## Integration
576
+ - ✅ All tasks completed
577
+ - ✅ All quality gates passed
578
+ - ✅ All tests passing
579
+ - ✅ Build succeeds
580
+ - ✅ PR created and reviewed
581
+ - ✅ Code merged to main
582
+
583
+ ## Integration
599
584
 
600
585
  - Reads from `/ai-eng/plan` output (plan.yaml)
601
586
  - Validates against `/ai-eng/specify` output (spec.md)
package/dist/index.js CHANGED
@@ -68,8 +68,7 @@ var AiEngSystem = async ({
68
68
  const targetDir = findInstallationTarget(directory);
69
69
  if (!targetDir) {
70
70
  return {
71
- config: async (input) => {
72
- }
71
+ config: async (input) => {}
73
72
  };
74
73
  }
75
74
  const isFirstRun = !fs.existsSync(path.join(targetDir, "command", "ai-eng"));
@@ -82,8 +81,7 @@ var AiEngSystem = async ({
82
81
  console.error(`[ai-eng-system] Installation warning: ${error instanceof Error ? error.message : String(error)}`);
83
82
  }
84
83
  return {
85
- config: async (input) => {
86
- }
84
+ config: async (input) => {}
87
85
  };
88
86
  };
89
87
  var src_default = AiEngSystem;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-eng-system",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "Compounding engineering system for Claude Code and OpenCode. Shared agents, commands, skills, and plugin development tools.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -65,8 +65,6 @@
65
65
  ],
66
66
  "devDependencies": {
67
67
  "@biomejs/biome": "^1.9.4",
68
- "@types/commander": "^2.12.0",
69
- "@types/glob": "^8.1.0",
70
68
  "bun-types": "latest",
71
69
  "husky": "^9.1.7",
72
70
  "standard-version": "^9.5.0",