Skip to content

docs: point the workflow examples at the shipped DSL and workflow_run - #39873

Closed
bolichen97 wants to merge 2 commits into
mainfrom
docs/sweep-specs-h-3
Closed

bolichen97 wants to merge 2 commits into
mainfrom
docs/sweep-specs-h-3

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The workflow example scripts say how to run them on today's build and no longer claim the DSL is unimplemented.

The three scripts in docs/system-specs/modules/examples/workflows/ say "DSL not implemented yet", and 01_review_changes.py shows workflow run review-changes --args ..., a CLI command that does not exist. The folder README carried a note calling those docstrings out of date. src/kiro_crew/workflows/ implements the DSL, and a run starts through the workflow_run tool (mcp_tools/workflows.py), which takes source and args.

Why it matters

The Workflows app serves these files in its example picker (handle_examples), so users copy from them. A dead command and a false "not implemented" line mislead them.

Not a goal

  • No change to any script's code, META, or behaviour.
  • The README's caveats on .then, unwired ports and the budget counter stay; they were re-checked and still hold.

What changed (motivation → approach → change)

  • Docstrings of the three scripts point to the folder README for caveats instead of saying the DSL is unimplemented.
  • 01_review_changes.py names the workflow_run tool with source and args as the way to run it.
  • README drops the "docstrings are out of date" note, now that they are not.

Backwards compatibility

Compatible: docstring and README text only; every script still validates.

Removes nothing: no file, key or function is removed.

Tests

Proof: not provable -- docs or config only

test/test_workflows_app.py -k example and test/test_workflows_authoring_eval.py pass locally (they validate the shipped examples). ./scripts/docs-lint.sh exits 0.

Manual verification

N/A — the tests above cover the example picker and validation.

Real-machine verification

N/A -- docstrings and README only; no executed line changes.

Related Issues

None.

Checklist

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 20, 2026 08:36
@bolichen97
bolichen97 enabled auto-merge (squash) November 20, 2026 08:36
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b1df19754a4a0b80e72a4a48dda72925e67258c8 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing to check.

What this change ships

Inventory (3 items) — 3 justified

Intent: people copying a workflow example from the picker get run instructions that work on today's build and no "not implemented" claim. This is a FIX.

  1. The three example docstrings no longer say the DSL is unimplemented; they point to the folder README for caveats — justified
  2. 01_review_changes.py shows how to run it with the workflow_run tool, using source and args, in place of the workflow run CLI command, which doesn't exist — justified
  3. The folder README drops its "docstrings are out of date" note — justified

[FIRST-PRINCIPLES-REVIEWED] b1df197

Description read

[DESCRIPTION-READ] 9a6125cf385ba9c6c2241e86b5c82d5ae9fa5eeefd1495b79e19229d3cd3ebf5

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision b1df19754a4a0b80e72a4a48dda72925e67258c8 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b1df19754a4a0b80e72a4a48dda72925e67258c8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Docstring and README text only, and the workflow_run source/args call it now documents matches mcp_tools/workflows.py:98.

[DESIGN-REVIEWED] b1df197

Description read

[DESCRIPTION-READ] 1691f383ec83fc72cca0dda42ee95bcf48aef8d5e3dbce41ffcad996da0d3ec8

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of b1df19754a4a0b80e72a4a48dda72925e67258c8 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b1df197

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b1df19754a4a0b80e72a4a48dda72925e67258c8 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed b1df19754a4a0b80e72a4a48dda72925e67258c8 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] b1df197

Verdict parsed from the review's SHA-scoped output markers for commit b1df19754a4a0b80e72a4a48dda72925e67258c8.

False positive or not applicable? A repository writer can comment:
/ai-review override fable b1df19754a4a0b80e72a4a48dda72925e67258c8 false-positive: <reason, 20 to 500 characters>

@bolichen97

Copy link
Copy Markdown
Contributor Author

Folded into #39898 (docs sweep round 1b, module specs list A), which carries the same change to all four example files.

@bolichen97 bolichen97 closed this Nov 20, 2026
auto-merge was automatically disabled November 20, 2026 09:12

Pull request was closed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant