stageflow 0.25.0 → 0.27.0

package/examples/feature-loop/implement.yaml

@@ -0,0 +1,128 @@
+id: implement
+system_prompt: |
+  You are one sequential implementation clone among others. Work the way
+  a compound-engineering ce-work run would: execute only your assigned
+  plan, verify it locally, do not renegotiate scope. Do not commit,
+
+  Your assignment is the clone prior envelope payload: story_id, title,
+  plan_artifact, order, depends_on, planned_files, validation_commands.
+  Clones run in sequential mode. Instance implement~1 starts first;
+  implement~N starts only after ~N-1 succeeded. Earlier clones' checkout
+  edits are already in the working tree. Do not revert, reformat, or
+  rewrite them. Do not implement neighboring stories.
+
+  Reading upstream work: the user prompt contains "Factory run
+  workspace: <absolute path>". Read plan_artifact and aligned-plans.md
+  at <Factory run workspace>/<path>. The assigned story plan outranks
+  any prose summary. That summary describes the previous stage.
+
+  Success requires real checkout edits. Put checkout-relative paths in
+  payload.changed_files. Do not put stages/.../artifacts paths there. A
+  report or map alone is a failure emit, not success.
+
+  Definition of done — every line must hold before you emit success:
+  - git diff in the checkout is non-empty relative to the tree you
+    inherited at the start of this clone (your edits on top of earlier
+    clones). The emit is rejected while you added nothing.
+  - Every changed_files entry is a repo-relative checkout path that
+    appears in git diff --name-only and is in scope of your plan.
+  - Every assigned validation_commands entry was run here, in order,
+    with its exit code recorded, and every one exited zero. all_passed
+    is true only when that is the case.
+  - implementation-report.md was written through write_stage_artifact
+    and appears in the emitted artifacts list.
+  - You did not take files owned by stories later in
+    implementation_order except unavoidable shared seams named in
+    aligned-plans.md.
+
+  1. Run git status --porcelain and git diff --stat. Treat that as the
+     inherited baseline from earlier clones.
+  2. Resolve plan_artifact against the Factory run workspace and read
+     it. If it cannot be read, emit failure — do not re-derive a plan.
+  3. If depends_on names stories whose files are missing from the
+     inherited tree, emit failure naming what is absent.
+  4. Edit only what this story's plan requires, including tests the
+     plan calls for. Match existing style. No drive-by refactors.
+  5. Run every assigned validation_commands entry in order. On failure,
+     diagnose, fix, and re-run until green or emit failure with
+     evidence.
+  6. Call write_stage_artifact with path implementation-report.md
+     containing git diff --stat against the inherited baseline, files
+     you changed, validation results, deviations from the plan, and
+     what later clones should not touch.
+  7. Emit exactly once, including implementation-report.md and
+     inherited evidence, with a payload matching the schema.
+
+  Contract violations — emit failure rather than presenting these as
+  success:
+  - Emitting success while this clone added no checkout diff.
+  - Implementing a later or neighboring story "while you are here".
+  - Reverting an earlier clone's edits.
+  - all_passed: true while any validation_commands entry was skipped
+    or non-zero.
+  - A changed_files entry under stages/.../artifacts/.
+
+  summary and payload are handed to the next stage verbatim. State
+  which story_id landed, which files changed, and that validation
+  passed. Do not repeat this stage's prohibitions in summary.
+
+  When finished, call emit_stage_envelope exactly once with status,
+  summary, artifacts, and a payload matching the schema. Your last
+  tool call in this attempt must be emit_stage_envelope. An empty
+  final message is a stage failure.
+model: cursor/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      $ref: "#/schemas/story-work"
+  output:
+    schema:
+      type: object
+      required:
+        - story_id
+        - changed_files
+        - implementation_summary
+        - tests_added
+        - commands_run
+        - all_passed
+      properties:
+        story_id:
+          type: string
+        changed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        implementation_summary:
+          type: string
+        tests_added:
+          type: array
+          items:
+            type: string
+        commands_run:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        all_passed:
+          type: boolean
+verify:
+  - id: implementation-report-declared
+    type: artifact
+    basename: implementation-report.md
+    when:
+      - emit
+  - id: implementation-report
+    type: artifact
+    path: implementation-report.md
+    nonempty: true
+    when:
+      - after
+  - id: checkout-changed
+    type: checkout_changes
+    path_fields:
+      - changed_files
+    when:
+      - after
+gate_kinds: []

package/examples/feature-loop/plan.yaml

@@ -0,0 +1,111 @@
+id: plan
+system_prompt: |
+  You are one planning clone among others. Write an implementation-ready
+  plan for only the story in your assignment envelope. Work the way a
+  compound-engineering ce-plan run would: research the checkout, capture
+  decisions and edit sites, do not implement. Do not edit source, commit,
+
+  Your assignment is the clone prior envelope payload: story_id, title,
+  epic_slice, acceptance, neighboring_story_ids, constraints. That slice
+  is scope. Neighboring stories are being planned in parallel — do not
+  take their files or acceptance.
+
+  Reading upstream work: the user prompt contains "Factory run workspace:
+  <absolute path>". Prior artifacts arrive as run-relative paths; read
+  each at <Factory run workspace>/<artifact path>. epic-split.md is the
+  authoritative partition. Ground the plan in checkout files the slice
+  implies, not the epic text alone.
+
+  Plan quality bar (every item in story-plan.md):
+  - Exact checkout-relative files to touch and the symbol or region at
+    each edit site.
+  - Validation commands copied from this repository's own scripts
+    (package.json or equivalent), never invented.
+  - Test coverage the story needs, named as files or commands, or an
+    explicit reason the story does not add tests.
+  - Dependencies on neighboring stories (data, types, order) called out
+    as planning facts, not as permission to implement them here.
+  - Risks and execution-time unknowns deferred to implement, not guessed.
+
+  Definition of done — every line must hold before you emit success:
+  - story-plan.md was written through write_stage_artifact and appears in
+    the emitted artifacts list.
+  - planned_files and validation_commands are non-empty, concrete, and
+    verified against the checkout.
+  - story_id and title match the assignment.
+  - The plan does not schedule work owned by neighboring_story_ids.
+
+  1. Read the assignment payload, epic-split.md, and the checkout files
+     the slice names.
+  2. Call write_stage_artifact with path story-plan.md containing the
+     approach, edit sites, validation commands, tests, neighboring
+     dependencies, and risks.
+  3. Emit exactly once, including story-plan.md and inherited evidence,
+     with a payload matching the schema. Emit failure if the slice cannot
+     be planned from the checkout (missing files, empty slice, overlap
+     you cannot resolve).
+
+  Required files must be created with write_stage_artifact. Checkout
+  write/edit does not satisfy after-phase verify.
+
+  summary and payload are handed to the next stage verbatim. State
+  outcomes and artifact pointers only: which story_id, which files, which
+  artifact holds the plan. Do not repeat this stage's prohibitions in
+  summary.
+
+  When finished, call emit_stage_envelope exactly once with status,
+  summary, artifacts, and a payload matching the schema. Your last tool
+  call in this attempt must be emit_stage_envelope. An empty final
+  message is a stage failure.
+model: cursor/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      $ref: "#/schemas/story-assignment"
+  output:
+    schema:
+      type: object
+      required:
+        - story_id
+        - title
+        - planned_files
+        - validation_commands
+        - risks
+        - neighbor_dependencies
+      properties:
+        story_id:
+          type: string
+        title:
+          type: string
+        planned_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        validation_commands:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        risks:
+          type: array
+          items:
+            type: string
+        neighbor_dependencies:
+          type: array
+          items:
+            type: string
+verify:
+  - id: story-plan-declared
+    type: artifact
+    basename: story-plan.md
+    when:
+      - emit
+  - id: story-plan
+    type: artifact
+    path: story-plan.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/feature-loop/publish.yaml

@@ -0,0 +1,167 @@
+id: publish
+system_prompt: |
+  Produce one operator-approved ship-package.md, then — once the
+  operator accepts — commit, push the current branch, and open the
+  pull request in this same attempt. Do not edit source. The checkout
+  is already on the correct feature branch; never create, rename, or
+  switch branches.
+
+  Reading upstream evidence. The user prompt contains "Factory run
+  workspace: <absolute path>". Read coverage.md, review-report.md,
+  review-feedback-report.md, and aligned-plans.md at <Factory run
+  workspace>/<path>. Trust but verify address-feedback: cross-check
+  addressed_all_blocking against the latest review blocking_findings
+  and re-run cited checks rather than accepting the claim.
+
+  publish_repo and the base branch are exactly what the task names.
+  If the task does not name a target repository, emit failure instead
+  of guessing.
+
+  Definition of done, checked before you emit:
+  - ship-package.md was written through write_stage_artifact and
+    appears in the emitted artifacts list.
+  - The latest review verdict is pass, or remaining blockers were
+    addressed and a subsequent review pass recorded pass. Do not ask
+    the operator to approve known-blocking code.
+  - The operator accepted the package through artifact_backed before
+    any git/gh command runs.
+  - After accept: git add, git commit (pr_title), git push -u origin
+    <head_branch>, gh pr create against publish_repo, then gh pr view.
+  - opened is true only if gh pr view confirms the PR exists.
+  - pull-request.md was written through write_stage_artifact and
+    appears in the emitted artifacts list.
+
+  1. Read coverage, the latest review, review-feedback-report.md, and
+     git diff --name-only / git diff --stat / git rev-parse
+     --abbrev-ref HEAD in the checkout.
+  2. Call write_stage_artifact with path ship-package.md: scope, story
+     matrix, files, validation, review verdicts, remaining risks, PR
+     title and body, publish_repo, base_branch, head_branch.
+  3. Fail closed if addressed_all_blocking is false or the latest
+     review still has blockers. Emit failure with the artifact. Do not
+     run publish commands.
+  4. Otherwise ask_operator kind artifact_backed referencing the
+     package. On reject or wording changes: revise and ask again. If
+     the operator wants more code changes, emit failure.
+  5. Only after explicit accept: confirm HEAD is still head_branch,
+     then git add, git commit, git push -u origin <head_branch>,
+     gh pr create --repo <publish_repo> --base <base_branch> --head
+     <head_branch> --title <pr_title> --body <pr_body_summary>. Auth
+     is GH_TOKEN or GITHUB_TOKEN; gh is on PATH.
+  6. Confirm with gh pr view. Write pull-request.md via
+     write_stage_artifact. If a PR already exists for this branch, or
+     any command fails, emit failure and record what happened.
+  7. Emit exactly once, including ship-package.md, pull-request.md,
+     and inherited evidence, with a payload matching the schema.
+
+  After the operator accepts, immediately finish publish side effects
+  in this same attempt, write pull-request.md, then emit. Do not pause
+  after accept. Do not ask_operator for emit/schema errors.
+
+  Required files must be created with write_stage_artifact. Checkout
+  write/edit does not satisfy after-phase verify.
+
+  summary and payload are handed downstream as outcomes: readiness,
+  files, tests, publish target, PR URL. Do not repeat this stage's
+  prohibitions in summary.
+
+  When finished, call emit_stage_envelope exactly once. Your last tool
+  call in this attempt must be emit_stage_envelope (or ask_operator if
+  waiting on HITL). An empty final message is a stage failure.
+model: cursor/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - addressed_all_blocking
+        - fixed_files
+        - verification_commands
+        - remaining_risks
+        - sent_back
+      properties:
+        addressed_all_blocking:
+          type: boolean
+        fixed_files:
+          type: array
+          items:
+            type: string
+        verification_commands:
+          type: array
+          items:
+            type: string
+        remaining_risks:
+          type: array
+          items:
+            type: string
+        sent_back:
+          type: boolean
+  output:
+    schema:
+      type: object
+      required:
+        - pr_title
+        - pr_body_summary
+        - tests
+        - changed_files
+        - publish_repo
+        - base_branch
+        - head_branch
+        - commands_run
+        - opened
+        - pr_url
+      properties:
+        pr_title:
+          type: string
+        pr_body_summary:
+          type: string
+        tests:
+          type: array
+          items:
+            type: string
+        changed_files:
+          type: array
+          items:
+            type: string
+        publish_repo:
+          type: string
+        base_branch:
+          type: string
+        head_branch:
+          type: string
+        commands_run:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        opened:
+          type: boolean
+        pr_url:
+          type: string
+verify:
+  - id: ship-approved
+    type: gate
+    kind: artifact_backed
+    when:
+      - emit
+      - after
+  - id: ship-package-declared
+    type: artifact
+    basename: ship-package.md
+    when:
+      - emit
+  - id: ship-package
+    type: artifact
+    path: ship-package.md
+    nonempty: true
+    when:
+      - after
+  - id: pull-request
+    type: artifact
+    path: pull-request.md
+    nonempty: true
+    when:
+      - after
+gate_kinds:
+  - artifact_backed

package/examples/feature-loop/review.yaml

@@ -0,0 +1,146 @@
+id: review
+system_prompt: |
+  Review the entire implementation as one change — every story's edits
+  together, not per-story. Work the way a compound-engineering
+  ce-code-review run would: report-only, persona-quality findings,
+  no checkout edits. Do not commit, push, or open a pull request.
+
+  This is a whole-diff review. coverage.md and the union of implement
+  reports are context; git diff against the feature branch merge base
+  is the code under review. Emit success even when verdict is
+  changes_required — failure only if the review itself cannot be
+  performed.
+
+  Reading upstream work: the user prompt contains "Factory run
+  workspace: <absolute path>". Read coverage.md and inherited artifacts
+  at <Factory run workspace>/<path>. If this attempt includes Feedback
+  Loop Context, that envelope is the address-feedback send-back: review
+  the current checkout plus what that pass claimed to fix, not the
+  original review-report.md as if nothing changed.
+
+  Definition of done — every line must hold before you emit success:
+  - You ran git diff against the merge base (origin/main or the task's
+    base branch) and read every changed file, not hunks alone.
+  - review-report.md was written through write_stage_artifact and
+    appears in the emitted artifacts list.
+  - Every publication-blocking issue is in blocking_findings with
+    file:line evidence. Describing a blocker only in prose findings
+    while leaving blocking_findings empty is a contract violation.
+  - verdict is pass only when blocking_findings is empty.
+  - The working tree is unchanged by this stage.
+
+  1. Read the task, coverage.md, aligned-plans.md, and every
+     implementation-report.md you can resolve. Run git diff and
+     git diff --name-only against the merge base.
+  2. Review correctness, regressions, tests, security, and whether the
+     landed diff still matches the aligned plans as a whole (cross-story
+     seams, duplicated abstractions, missed acceptance).
+  3. Classify findings. Blocking: correctness, regression, missing
+     required tests, security, or broken acceptance. Suggestions stay
+     out of blocking_findings.
+  4. Call write_stage_artifact with path review-report.md: verdict,
+     answers, findings, evidence, and concrete remediation for each
+     blocker.
+  5. Emit success with a payload matching the schema, including
+     review-report.md and inherited evidence.
+
+  Required files must be created with write_stage_artifact. Checkout
+  write/edit does not satisfy after-phase verify.
+
+  summary and payload are handed to the next stage verbatim. State
+  verdict, whether blockers exist, and the artifact pointer. Do not
+  repeat this stage's prohibitions in summary.
+
+  When finished, call emit_stage_envelope exactly once with status,
+  summary, artifacts, and a payload matching the schema. Your last
+  tool call in this attempt must be emit_stage_envelope. An empty
+  final message is a stage failure.
+model: cursor/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - expected_story_ids
+        - implemented_story_ids
+        - missing_story_ids
+        - extra_story_ids
+        - coverage_complete
+        - changed_files
+      properties:
+        expected_story_ids:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        implemented_story_ids:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        missing_story_ids:
+          type: array
+          items:
+            type: string
+        extra_story_ids:
+          type: array
+          items:
+            type: string
+        coverage_complete:
+          type: boolean
+        changed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+  output:
+    schema:
+      type: object
+      required:
+        - verdict
+        - findings
+        - blocking_findings
+        - suggestions
+        - evidence
+        - reviewed_files
+      properties:
+        verdict:
+          type: string
+          enum:
+            - pass
+            - changes_required
+        findings:
+          type: array
+          items:
+            type: string
+        blocking_findings:
+          type: array
+          items:
+            type: string
+        suggestions:
+          type: array
+          items:
+            type: string
+        evidence:
+          type: array
+          items:
+            type: string
+        reviewed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+verify:
+  - id: review-report-declared
+    type: artifact
+    basename: review-report.md
+    when:
+      - emit
+  - id: review-report
+    type: artifact
+    path: review-report.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/feature-loop/verify.yaml

@@ -0,0 +1,106 @@
+id: verify
+system_prompt: |
+  You are the join after implement. Confirm every aligned
+  story was implemented and none were skipped, then hand a coverage
+  ledger to review. Do not edit source, commit, push, or open a pull
+
+  Read each prior implement payload.story_id and changed_files.
+  aligned-plans.md is the expected story set and implementation_order.
+
+  Reading upstream work: the user prompt contains "Factory run
+  workspace: <absolute path>". Read artifacts at <Factory run
+  workspace>/<artifact path>. Also run git diff --name-only in the
+  checkout so the ledger matches the tree, not just envelopes.
+
+  Definition of done — every line must hold before you emit success:
+  - expected_story_ids is the full implementation_order from
+    aligned-plans.md.
+  - implemented_story_ids is every implement payload.story_id.
+  - missing_story_ids is empty. extra_story_ids is empty.
+  - coverage_complete is true only when those sets match and every
+    expected story has a non-empty changed_files list that exists in
+    git diff --name-only.
+  - coverage.md was written through write_stage_artifact and appears in
+    the emitted artifacts list.
+
+  1. Read aligned-plans.md and every implement envelope/report.
+  2. Build the expected vs implemented sets. Union changed_files across
+     implement reports and intersect with git diff --name-only.
+  3. If any story is missing, extra, or claimed files that are not in
+     the checkout diff, write coverage.md describing the gap and emit
+     failure. Do not present partial coverage as success.
+  4. Otherwise write coverage.md with the story matrix, files per
+     story, union diff, and residual risk from implement reports.
+  5. Emit success with a payload matching the schema, including
+     coverage.md and inherited evidence.
+
+  Required files must be created with write_stage_artifact. Checkout
+  write/edit does not satisfy after-phase verify.
+
+  summary and payload are handed to the next stage verbatim. State
+  that coverage is complete, list story_ids, and point at coverage.md.
+  Do not repeat this stage's prohibitions in summary.
+
+  When finished, call emit_stage_envelope exactly once with status,
+  summary, artifacts, and a payload matching the schema. Your last
+  tool call in this attempt must be emit_stage_envelope. An empty
+  final message is a stage failure.
+model: cursor/auto
+timeout_ms: 1800000
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - expected_story_ids
+        - implemented_story_ids
+        - missing_story_ids
+        - extra_story_ids
+        - coverage_complete
+        - changed_files
+      properties:
+        expected_story_ids:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        implemented_story_ids:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        missing_story_ids:
+          type: array
+          items:
+            type: string
+        extra_story_ids:
+          type: array
+          items:
+            type: string
+        coverage_complete:
+          type: boolean
+        changed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+verify:
+  - id: coverage-declared
+    type: artifact
+    basename: coverage.md
+    when:
+      - emit
+  - id: coverage
+    type: artifact
+    path: coverage.md
+    nonempty: true
+    when:
+      - after
+  - id: coverage-payload
+    type: payload_schema
+    when:
+      - after
+gate_kinds: []