@ghostwater/soulforge 0.6.0 → 0.8.0

package/dist/workflow/types.d.ts

@@ -1,12 +1,18 @@
 export type ExecutorType = "openclaw" | "claude-code" | "codex" | "codex-cli" | "self";
 export type NotifyEvent = "on_complete" | "on_waiting" | "on_fail";
 export type LoopConfig = {
-    over: "stories";
+    over: string;
     completion: "all_done";
     freshSession?: boolean;
     verifyEach?: boolean;
     verifyStep?: string;
 };
+export type GateConfig = {
+    decision_var: string;
+    routes: Record<string, string>;
+    default: string;
+    max_loops: number;
+};
 export type StepFailure = {
     retry_step?: string;
     max_retries?: number;
@@ -18,14 +24,27 @@ export type StepFailure = {
 export type OnRejectConfig = {
     reset_to: string;
 };
+export type OutputFieldType = "string" | "number" | "boolean" | "array" | "object";
+export type OutputField = {
+    name: string;
+    type: OutputFieldType;
+    required: boolean;
+    description?: string;
+    items?: OutputField[];
+};
+export type OutputSchema = {
+    fields: OutputField[];
+};
 export type WorkflowStep = {
     id: string;
     executor?: ExecutorType;
     agent?: string;
     model?: string;
     workdir?: string;
-    type?: "single" | "loop";
+    type?: "single" | "loop" | "gate";
     loop?: LoopConfig;
+    gate?: GateConfig;
+    next?: string;
     input: string;
     expects?: string;
     timeout?: number;
@@ -33,6 +52,7 @@ export type WorkflowStep = {
     on_fail?: StepFailure;
     on_reject?: OnRejectConfig;
     notify?: NotifyEvent | NotifyEvent[];
+    output_schema?: OutputSchema;
 };
 export type AgentRole = "analysis" | "coding" | "verification" | "testing" | "pr" | "scanning";
 export type WorkflowAgent = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostwater/soulforge",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Pluggable executor workflow engine for AI coding agents. Dispatch workflow steps to Claude Code, Codex CLI, or human review checkpoints.",
   "type": "module",
   "engines": {

package/workflows/bugfix/workflow.yml

@@ -9,17 +9,43 @@ description: |
   Keeps scope tight — no "while I'm here" improvements.
 
 defaults:
-  executor: claude-code
-  model: opus
+  executor: "{{executor:codex-cli}}"
+  model: "{{model:gpt-5.3-codex}}"
   timeout: 600
   max_retries: 2
   notify: [on_complete, on_fail]
 
 steps:
   - id: diagnose
-    executor: claude-code
-    model: opus
+    executor: "{{executor:codex-cli}}"
+    model: "{{model:gpt-5.3-codex}}"
     workdir: "{{workdir}}"
+    output_schema:
+      fields:
+        - name: status
+          type: string
+          required: true
+          description: Must be "done"
+        - name: affected_files
+          type: string
+          required: true
+          description: Files and components involved in the bug
+        - name: root_cause
+          type: string
+          required: true
+          description: Exact defect and why it fails
+        - name: failing_test
+          type: string
+          required: true
+          description: Failing reproduction test details
+        - name: fix_proposal
+          type: string
+          required: true
+          description: Minimal approved change plan
+        - name: scope
+          type: string
+          required: true
+          description: Maximum file scope for the fix
     input: |
       You are working in {{workdir}}. Diagnose the following bug.
 
@@ -39,18 +65,20 @@ steps:
       - Keep the fix proposal minimal — bugfixes should be surgical
       - Commit the failing test: test: failing test for {{task}}
 
-      Reply with:
-      STATUS: done
-      AFFECTED_FILES: which files are involved
-      ROOT_CAUSE: exactly what's wrong and why
-      FAILING_TEST: what test you wrote and how it demonstrates the bug
-      FIX_PROPOSAL: what needs to change (be specific — file, function, what changes)
-      SCOPE: list of files that will be modified in the fix (max)
-    expects: "STATUS: done"
 
   - id: review-diagnosis
     executor: self
     notify: on_waiting
+    output_schema:
+      fields:
+        - name: status
+          type: string
+          required: true
+          description: Review outcome (approved or retry)
+        - name: notes
+          type: string
+          required: false
+          description: Optional feedback for revised diagnosis
     on_reject:
       reset_to: diagnose
     input: |
@@ -69,9 +97,23 @@ steps:
       - Is the scope reasonable?
 
   - id: fix
-    executor: claude-code
-    model: opus
+    executor: "{{executor:codex-cli}}"
+    model: "{{model:gpt-5.3-codex}}"
     workdir: "{{workdir}}"
+    output_schema:
+      fields:
+        - name: status
+          type: string
+          required: true
+          description: Must be "done"
+        - name: changes
+          type: string
+          required: true
+          description: Exact implementation changes made for the fix
+        - name: tests
+          type: string
+          required: true
+          description: Test execution summary after applying the fix
     input: |
       Implement the approved fix for this bug.
 
@@ -98,16 +140,33 @@ steps:
       - Change files outside SCOPE unless absolutely necessary
       - "Improve" things while you're in there
 
-      Reply with:
-      STATUS: done
-      CHANGES: exactly what you changed and why
-      TEST_RESULTS: full test suite results
-    expects: "STATUS: done"
 
   - id: verify
-    executor: claude-code
-    model: opus
+    executor: "{{executor:codex-cli}}"
+    model: "{{model:gpt-5.3-codex}}"
     workdir: "{{workdir}}"
+    output_schema:
+      fields:
+        - name: status
+          type: string
+          required: true
+          description: Verification decision ("done" or "retry")
+        - name: verified
+          type: string
+          required: true
+          description: Confirmed verification results
+        - name: issues
+          type: string
+          required: true
+          description: Problems found when retry is required
+        - name: diff_review
+          type: string
+          required: true
+          description: Diff scope review against approved plan
+        - name: verify_feedback
+          type: string
+          required: false
+          description: Retry feedback passed back to the fix step
     input: |
       Verify the bugfix independently.
 
@@ -127,46 +186,195 @@ steps:
       4. Does the fix actually address the root cause (not just mask symptoms)?
       5. Are there any edge cases the fix misses?
 
-      Reply with:
-      STATUS: done
-      VERIFIED: what you confirmed
-      DIFF_REVIEW: summary of actual changes vs approved scope
-
-      Or if issues found:
-      STATUS: retry
-      ISSUES:
-      - What's wrong
-    expects: "STATUS: done"
 
   - id: pr
-    executor: claude-code
-    model: opus
+    executor: "{{executor:codex-cli}}"
+    model: "{{model:gpt-5.3-codex}}"
     workdir: "{{workdir}}"
     notify: on_complete
+    output_schema:
+      fields:
+        - name: status
+          type: string
+          required: true
+          description: Must be "done"
+        - name: pr
+          type: string
+          required: true
+          description: Pull request URL
+        - name: pr_number
+          type: number
+          required: true
+          description: Pull request number
     input: |
-      Create a pull request for this bugfix.
+      Create or resolve a pull request for this bugfix.
 
       WORKDIR: {{workdir}}
       BUG: {{task}}
       ROOT_CAUSE: {{root_cause}}
       CHANGES: {{changes}}
 
-      Create a PR with gh pr create. The PR body should include:
+      IMPORTANT: this step is idempotent.
+
+      1) First check whether a PR already exists for the current branch.
+         - Use gh pr view --json number,url,state
+         - If that fails, search by head branch in this repo.
+
+      2) If an existing PR is found, DO NOT create a new one.
+         Immediately complete the step with that existing PR's URL and number.
+
+      3) Only run gh pr create when no PR exists.
+
+      PR body should include:
       - What the bug was
       - Root cause
       - What the fix does
       - Link to the issue if one exists
 
-      Reply with:
-      STATUS: done
-      PR: URL to the pull request
-    expects: "STATUS: done"
+
+  # ── Automated Review Loop ──────────────────────────────────────────
+  - id: code-review
+    executor: "{{executor:codex-cli}}"
+    model: "{{model:gpt-5.3-codex}}"
+    workdir: "{{workdir}}"
+    output_schema:
+      fields:
+        - name: status
+          type: string
+          required: true
+          description: Must be "done"
+        - name: review_decision
+          type: string
+          required: true
+          description: Gate decision ("pass" or "fix")
+        - name: findings
+          type: string
+          required: false
+          description: Review summary posted to the PR
+    input: |
+      Thorough code review of PR #{{pr_number}}.
+
+      WORKDIR: {{workdir}}
+      BUG: {{task}}
+      ROOT CAUSE: {{root_cause}}
+      SCOPE: {{scope}}
+      BUILD_CMD: {{build_cmd}}
+      TEST_CMD: {{test_cmd}}
+
+      Instructions:
+      1. Read ALL changed files in the PR
+      2. Check: does the fix address the root cause (not just mask symptoms)?
+      3. Check: are changes limited to the approved SCOPE?
+      4. Check: edge cases, regressions, test quality
+      5. Run build: {{build_cmd}}
+      6. Run tests: {{test_cmd}}
+      7. Post ALL findings as a single comment on the PR:
+           gh pr comment {{pr_number}} --body "<your review>"
+      8. Flag severity for each finding (High/Medium/Low)
+
+      Do NOT decide what should or shouldn't be fixed — just flag everything.
+
+      Reply with exactly one of:
+        REVIEW_DECISION: pass
+        REVIEW_DECISION: fix
+
+  - id: review-gate
+    type: gate
+    executor: self
+    notify: on_waiting
+    output_schema:
+      fields:
+        - name: status
+          type: string
+          required: true
+          description: Triage checkpoint status
+        - name: review_decision
+          type: string
+          required: true
+          description: Final triage decision ("pass" or "fix")
+        - name: triage_summary
+          type: string
+          required: false
+          description: Summary of triage decisions and issue filing
+    input: |
+      Triage the code review findings on PR #{{pr_number}}.
+
+      Read the latest review comment on the PR. For each finding, decide:
+      - FIX: any issue related to the task, introduced by this PR, or that
+        affects correctness of the changes. ALL task-related items get fixed.
+      - SEPARATE: only for genuine scope creep — pre-existing issues unrelated
+        to the task that were not introduced or affected by this PR.
+
+      Then:
+      1. Post a triage comment on the PR summarizing your decisions
+      2. File separate issues (if any) via: gh issue create --title "..." --body "..."
+      3. Approve with the appropriate routing decision
+    gate:
+      decision_var: REVIEW_DECISION
+      routes:
+        fix: review-fix
+        pass: final-review
+      default: final-review
+      max_loops: 5
+
+  - id: review-fix
+    executor: "{{executor:codex-cli}}"
+    model: "{{model:gpt-5.3-codex}}"
+    workdir: "{{workdir}}"
+    output_schema:
+      fields:
+        - name: status
+          type: string
+          required: true
+          description: Must be "done"
+        - name: changes
+          type: string
+          required: true
+          description: What was fixed from review findings
+        - name: tests
+          type: string
+          required: false
+          description: Build and test confirmation after fixes
+    input: |
+      Read the latest triage comment on PR #{{pr_number}} for the list of
+      items to fix. You can fetch it with:
+        gh pr view {{pr_number}} --comments --json comments --jq '.comments[-1].body'
+
+      WORKDIR: {{workdir}}
+      BUILD_CMD: {{build_cmd}}
+      TEST_CMD: {{test_cmd}}
+
+      Fix ONLY the items marked for fixing. Do not touch anything else.
+
+      After fixing:
+      1. Run build: {{build_cmd}}
+      2. Run tests: {{test_cmd}}
+      3. Commit and push
+
+      DO NOT:
+      - Refactor unrelated code
+      - Add features or improvements
+      - Touch files not related to the review findings
+
+    next: code-review
 
   - id: final-review
     executor: self
     notify: on_waiting
+    output_schema:
+      fields:
+        - name: status
+          type: string
+          required: true
+          description: Human sign-off decision
+        - name: notes
+          type: string
+          required: false
+          description: Optional final approval notes
     input: |
-      Final review of the bugfix PR.
+      PR #{{pr_number}} has passed automated code review.
+      Ready for human sign-off before merge.
+
       PR: {{pr}}
       BUG: {{task}}
       ROOT CAUSE: {{root_cause}}