@bastani/atomic 0.8.26-alpha.1 → 0.8.26-alpha.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.
Files changed (51) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/dist/builtin/intercom/CHANGELOG.md +12 -0
  3. package/dist/builtin/intercom/package.json +1 -1
  4. package/dist/builtin/mcp/CHANGELOG.md +12 -0
  5. package/dist/builtin/mcp/package.json +1 -1
  6. package/dist/builtin/subagents/CHANGELOG.md +13 -0
  7. package/dist/builtin/subagents/package.json +1 -1
  8. package/dist/builtin/subagents/src/runs/background/subagent-runner.ts +8 -3
  9. package/dist/builtin/subagents/src/runs/foreground/execution.ts +42 -4
  10. package/dist/builtin/subagents/src/runs/shared/acceptance.ts +2 -1
  11. package/dist/builtin/subagents/src/runs/shared/worktree.ts +2 -2
  12. package/dist/builtin/web-access/CHANGELOG.md +12 -0
  13. package/dist/builtin/web-access/package.json +1 -1
  14. package/dist/builtin/workflows/CHANGELOG.md +19 -0
  15. package/dist/builtin/workflows/README.md +10 -8
  16. package/dist/builtin/workflows/builtin/index.d.ts +2 -0
  17. package/dist/builtin/workflows/builtin/ralph.d.ts +2 -0
  18. package/dist/builtin/workflows/builtin/ralph.ts +299 -89
  19. package/dist/builtin/workflows/package.json +1 -1
  20. package/dist/builtin/workflows/skills/create-spec/SKILL.md +14 -0
  21. package/dist/builtin/workflows/skills/research-codebase/SKILL.md +28 -9
  22. package/dist/builtin/workflows/src/runs/foreground/stage-runner.ts +6 -1
  23. package/dist/builtin/workflows/src/runs/shared/worktree.ts +2 -2
  24. package/dist/builtin/workflows/src/shared/store.ts +61 -7
  25. package/dist/builtin/workflows/src/tui/stage-chat-view.ts +37 -2
  26. package/dist/core/atomic-guide-command.d.ts.map +1 -1
  27. package/dist/core/atomic-guide-command.js +10 -8
  28. package/dist/core/atomic-guide-command.js.map +1 -1
  29. package/dist/core/footer-data-provider.d.ts.map +1 -1
  30. package/dist/core/footer-data-provider.js +3 -0
  31. package/dist/core/footer-data-provider.js.map +1 -1
  32. package/dist/core/package-manager.d.ts.map +1 -1
  33. package/dist/core/package-manager.js +14 -7
  34. package/dist/core/package-manager.js.map +1 -1
  35. package/dist/index.d.ts +1 -0
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +1 -0
  38. package/dist/index.js.map +1 -1
  39. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  40. package/dist/modes/interactive/components/footer.js +4 -1
  41. package/dist/modes/interactive/components/footer.js.map +1 -1
  42. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  43. package/dist/modes/interactive/interactive-mode.js +3 -2
  44. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  45. package/dist/utils/git-env.d.ts +10 -0
  46. package/dist/utils/git-env.d.ts.map +1 -0
  47. package/dist/utils/git-env.js +33 -0
  48. package/dist/utils/git-env.js.map +1 -0
  49. package/docs/quickstart.md +4 -4
  50. package/docs/workflows.md +16 -14
  51. package/package.json +1 -1
@@ -0,0 +1,10 @@
1
+ export declare const GIT_LOCAL_ENV_VARS: readonly ["GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT", "GIT_OBJECT_DIRECTORY", "GIT_DIR", "GIT_WORK_TREE", "GIT_IMPLICIT_WORK_TREE", "GIT_GRAFT_FILE", "GIT_INDEX_FILE", "GIT_NO_REPLACE_OBJECTS", "GIT_REPLACE_REF_BASE", "GIT_PREFIX", "GIT_SHALLOW_FILE", "GIT_COMMON_DIR"];
2
+ /**
3
+ * Create an environment for Git subprocesses that target an explicit cwd/path.
4
+ *
5
+ * Git honors repository-local environment variables over cwd and `git -C`, so
6
+ * inherited values from hooks or unrelated worktrees can make a subprocess
7
+ * inspect the wrong repository. This list mirrors `git rev-parse --local-env-vars`.
8
+ */
9
+ export declare function createGitEnvironment(overrides?: NodeJS.ProcessEnv, baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
10
+ //# sourceMappingURL=git-env.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"git-env.d.ts","sourceRoot":"","sources":["../../src/utils/git-env.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,YAC9B,kCAAkC,EAClC,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,SAAS,EACT,eAAe,EACf,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,CACP,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,EAC7B,OAAO,GAAE,MAAM,CAAC,UAAwB,GACtC,MAAM,CAAC,UAAU,CAKnB","sourcesContent":["export const GIT_LOCAL_ENV_VARS = [\n\t\"GIT_ALTERNATE_OBJECT_DIRECTORIES\",\n\t\"GIT_CONFIG\",\n\t\"GIT_CONFIG_PARAMETERS\",\n\t\"GIT_CONFIG_COUNT\",\n\t\"GIT_OBJECT_DIRECTORY\",\n\t\"GIT_DIR\",\n\t\"GIT_WORK_TREE\",\n\t\"GIT_IMPLICIT_WORK_TREE\",\n\t\"GIT_GRAFT_FILE\",\n\t\"GIT_INDEX_FILE\",\n\t\"GIT_NO_REPLACE_OBJECTS\",\n\t\"GIT_REPLACE_REF_BASE\",\n\t\"GIT_PREFIX\",\n\t\"GIT_SHALLOW_FILE\",\n\t\"GIT_COMMON_DIR\",\n] as const;\n\n/**\n * Create an environment for Git subprocesses that target an explicit cwd/path.\n *\n * Git honors repository-local environment variables over cwd and `git -C`, so\n * inherited values from hooks or unrelated worktrees can make a subprocess\n * inspect the wrong repository. This list mirrors `git rev-parse --local-env-vars`.\n */\nexport function createGitEnvironment(\n\toverrides?: NodeJS.ProcessEnv,\n\tbaseEnv: NodeJS.ProcessEnv = process.env,\n): NodeJS.ProcessEnv {\n\tconst env: NodeJS.ProcessEnv = { ...baseEnv };\n\tif (overrides) Object.assign(env, overrides);\n\tfor (const key of GIT_LOCAL_ENV_VARS) delete env[key];\n\treturn env;\n}\n"]}
@@ -0,0 +1,33 @@
1
+ export const GIT_LOCAL_ENV_VARS = [
2
+ "GIT_ALTERNATE_OBJECT_DIRECTORIES",
3
+ "GIT_CONFIG",
4
+ "GIT_CONFIG_PARAMETERS",
5
+ "GIT_CONFIG_COUNT",
6
+ "GIT_OBJECT_DIRECTORY",
7
+ "GIT_DIR",
8
+ "GIT_WORK_TREE",
9
+ "GIT_IMPLICIT_WORK_TREE",
10
+ "GIT_GRAFT_FILE",
11
+ "GIT_INDEX_FILE",
12
+ "GIT_NO_REPLACE_OBJECTS",
13
+ "GIT_REPLACE_REF_BASE",
14
+ "GIT_PREFIX",
15
+ "GIT_SHALLOW_FILE",
16
+ "GIT_COMMON_DIR",
17
+ ];
18
+ /**
19
+ * Create an environment for Git subprocesses that target an explicit cwd/path.
20
+ *
21
+ * Git honors repository-local environment variables over cwd and `git -C`, so
22
+ * inherited values from hooks or unrelated worktrees can make a subprocess
23
+ * inspect the wrong repository. This list mirrors `git rev-parse --local-env-vars`.
24
+ */
25
+ export function createGitEnvironment(overrides, baseEnv = process.env) {
26
+ const env = { ...baseEnv };
27
+ if (overrides)
28
+ Object.assign(env, overrides);
29
+ for (const key of GIT_LOCAL_ENV_VARS)
30
+ delete env[key];
31
+ return env;
32
+ }
33
+ //# sourceMappingURL=git-env.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"git-env.js","sourceRoot":"","sources":["../../src/utils/git-env.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IACjC,kCAAkC;IAClC,YAAY;IACZ,uBAAuB;IACvB,kBAAkB;IAClB,sBAAsB;IACtB,SAAS;IACT,eAAe;IACf,wBAAwB;IACxB,gBAAgB;IAChB,gBAAgB;IAChB,wBAAwB;IACxB,sBAAsB;IACtB,YAAY;IACZ,kBAAkB;IAClB,gBAAgB;CACP,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CACnC,SAA6B,EAC7B,OAAO,GAAsB,OAAO,CAAC,GAAG;IAExC,MAAM,GAAG,GAAsB,EAAE,GAAG,OAAO,EAAE,CAAC;IAC9C,IAAI,SAAS;QAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,kBAAkB;QAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;IACtD,OAAO,GAAG,CAAC;AACZ,CAAC","sourcesContent":["export const GIT_LOCAL_ENV_VARS = [\n\t\"GIT_ALTERNATE_OBJECT_DIRECTORIES\",\n\t\"GIT_CONFIG\",\n\t\"GIT_CONFIG_PARAMETERS\",\n\t\"GIT_CONFIG_COUNT\",\n\t\"GIT_OBJECT_DIRECTORY\",\n\t\"GIT_DIR\",\n\t\"GIT_WORK_TREE\",\n\t\"GIT_IMPLICIT_WORK_TREE\",\n\t\"GIT_GRAFT_FILE\",\n\t\"GIT_INDEX_FILE\",\n\t\"GIT_NO_REPLACE_OBJECTS\",\n\t\"GIT_REPLACE_REF_BASE\",\n\t\"GIT_PREFIX\",\n\t\"GIT_SHALLOW_FILE\",\n\t\"GIT_COMMON_DIR\",\n] as const;\n\n/**\n * Create an environment for Git subprocesses that target an explicit cwd/path.\n *\n * Git honors repository-local environment variables over cwd and `git -C`, so\n * inherited values from hooks or unrelated worktrees can make a subprocess\n * inspect the wrong repository. This list mirrors `git rev-parse --local-env-vars`.\n */\nexport function createGitEnvironment(\n\toverrides?: NodeJS.ProcessEnv,\n\tbaseEnv: NodeJS.ProcessEnv = process.env,\n): NodeJS.ProcessEnv {\n\tconst env: NodeJS.ProcessEnv = { ...baseEnv };\n\tif (overrides) Object.assign(env, overrides);\n\tfor (const key of GIT_LOCAL_ENV_VARS) delete env[key];\n\treturn env;\n}\n"]}
@@ -73,12 +73,12 @@ Atomic ships with four workflows you can run immediately. Use `/workflow list` t
73
73
  |---|---|---|
74
74
  | `deep-research-codebase` | Broad, cross-cutting research before you decide what to change. Scout → research-history → parallel specialist waves → aggregator. | `/workflow deep-research-codebase prompt="How do payment retries work end to end?"` |
75
75
  | `goal` | Small-to-medium scope changes when you can identify the work surface, state the exact outcome, and name the validation that proves it is done — for example tests, lint/typecheck, docs builds, or observable behavior. Keeps the run bounded with a goal ledger, reviewer gates, and final status `complete`, `blocked`, or `needs_human`. | `/workflow goal objective="Implement specs/2026-03-rate-limit.md, run the focused tests, and finish when burst traffic returns 429"` |
76
- | `ralph` | Larger migrations, broad refactors, multi-package changes, and spec-to-PR work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and prepare a pull-request report. | `/workflow ralph prompt="Plan the database migration, implement it, review it, and prepare a PR"` |
76
+ | `ralph` | Larger migrations, broad refactors, multi-package changes, and spec-to-reviewed-change work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and optionally let only the final stage attempt PR creation with `create_pr=true`. | `/workflow ralph prompt="Plan the database migration, implement it, and review it" create_pr=true` |
77
77
  | `open-claude-design` | UI and design-system work with generation, critique, and refinement loops; renders a live `preview.html` you can iterate against. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy" output_type=page` |
78
78
 
79
79
  <p align="center"><img src="images/workflow-list.png" alt="Workflow List" width="600" /></p>
80
80
 
81
- Inputs are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=5`, `flag=true`, and `objective="multi word value"` preserve useful types. Some workflows expose reusable worktree inputs; for example, add `git_worktree_dir=../atomic-ralph-wt` to `ralph` to run its stages in a created/reused Git worktree while preserving your current repo-relative cwd. If you call `/workflow <name>` without required inputs, the TUI opens an inline picker; pass `--no-picker` to skip it.
81
+ Inputs are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=5`, `flag=true`, and `objective="multi word value"` preserve useful types. Some workflows expose reusable worktree inputs; for example, add `git_worktree_dir=../atomic-ralph-wt` to `ralph` to run its stages in a created/reused Git worktree while preserving your current repo-relative cwd. Ralph skips PR creation by default; prompt text alone does not opt in. Add `create_pr=true` only when you want its final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling; Ralph's own PR-creation instructions live in that final stage. If you call `/workflow <name>` without required inputs, the TUI opens an inline picker; pass `--no-picker` to skip it.
82
82
 
83
83
  You can also launch workflows with **natural language** — just describe the task in chat and ask Atomic to run the matching workflow:
84
84
 
@@ -94,7 +94,7 @@ Atomic picks the workflow, fills in inputs from the request, and confirms before
94
94
 
95
95
  Use `goal` for small-to-medium scope changes when you can identify the work surface, state the exact outcome you want, and name the validation that proves it is done — for example specific tests, lint/typecheck commands, docs builds, or observable behavior. It keeps the run bounded, captures receipts in a goal ledger, gates completion through reviewers, and stops as `complete`, `blocked`, or `needs_human`.
96
96
 
97
- Keep using `ralph` for larger migrations, broad refactors, multi-package changes, and spec-to-PR work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and prepare a pull-request report.
97
+ Keep using `ralph` for larger migrations, broad refactors, multi-package changes, and spec-to-reviewed-change work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`.
98
98
 
99
99
  ### Monitor and steer a run
100
100
 
@@ -125,7 +125,7 @@ Skills are reusable expert instructions. Trigger one with `/skill:<name>` follow
125
125
  | `tdd` | Test-first feature or bug work. | `/skill:tdd` |
126
126
  | `impeccable` | Critique or refine frontend and product UI. | `/skill:impeccable` |
127
127
 
128
- Use `/skill:research-codebase` for a focused area and `/workflow deep-research-codebase` when the answer spans the whole repo. A typical focused flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow goal` with an objective that identifies the work surface, states the exact outcome, and names the validation that proves it is done. Keep using `/workflow ralph` for larger migrations, broad refactors, multi-package changes, and spec-to-PR work where you want Atomic to plan, delegate through sub-agents, simplify, review, iterate, and prepare a pull-request report.
128
+ Use `/skill:research-codebase` for a focused area and `/workflow deep-research-codebase` when the answer spans the whole repo. A typical focused flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow goal` with an objective that identifies the work surface, states the exact outcome, and names the validation that proves it is done. Keep using `/workflow ralph` for larger migrations, broad refactors, multi-package changes, and spec-to-reviewed-change work where you want Atomic to plan, delegate through sub-agents, simplify, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`.
129
129
 
130
130
  ### Create your own workflow in natural language
131
131
 
package/docs/workflows.md CHANGED
@@ -153,7 +153,7 @@ For the builtin result tables below, `deep-research-codebase`, `goal`, and `ralp
153
153
  |---|---|---|
154
154
  | `deep-research-codebase` | Scout + research-history chain → parallel specialist waves → aggregator. Indexes the whole repo and synthesizes findings. | Broad or cross-cutting research before you decide what to change. Prefer `/skill:research-codebase` for one subsystem. |
155
155
  | `goal` | Persisted goal ledger → bounded worker turns → receipts → three-reviewer gate → deterministic reducer → final report. | Small-to-medium scope changes when you can identify the work surface, state the exact outcome, and name the validation that proves it is done — for example tests, lint/typecheck, docs builds, or observable behavior. |
156
- | `ralph` | RFC planning → sub-agent orchestration → simplification → parallel review → PR handoff. | Larger migrations, broad refactors, multi-package changes, and spec-to-PR work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and prepare a pull-request report. |
156
+ | `ralph` | RFC planning → sub-agent orchestration → simplification → parallel review → optional final-stage PR handoff. | Larger migrations, broad refactors, multi-package changes, and spec-to-reviewed-change work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`. |
157
157
  | `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `browser-use` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
158
158
 
159
159
  ### `deep-research-codebase`
@@ -248,20 +248,21 @@ Inputs:
248
248
 
249
249
  | Input | Type | Required | Default | Description |
250
250
  |---|---|---|---|---|
251
- | `prompt` | text | yes | — | Task, feature request, issue summary, or spec path to plan, execute, refine, review, and prepare for PR. |
252
- | `max_loops` | number | no | `10` | Maximum plan/orchestrate/review iterations before the workflow proceeds to PR handoff without reviewer approval. |
253
- | `base_branch` | string | no | `origin/main` | Branch reviewers and the PR-prep stage compare the current code delta against; also used to create a missing worktree. |
251
+ | `prompt` | text | yes | — | Task, feature request, issue summary, or spec path to plan, execute, refine, and review. |
252
+ | `max_loops` | number | no | `10` | Maximum plan/orchestrate/review iterations before the workflow completes or, when enabled, proceeds to final handoff without reviewer approval. |
253
+ | `base_branch` | string | no | `origin/main` | Branch reviewers and the optional final stage compare the current code delta against; also used to create a missing worktree. |
254
254
  | `git_worktree_dir` | string | no | `""` | Optional reusable Git worktree root. Empty runs in the invoking checkout; non-empty values run Ralph stages in the created/reused worktree. |
255
+ | `create_pr` | boolean | no | `false` | Safe-by-default PR creation flag. Omitted or `false` skips the final `pull-request` stage and omits `pr_report`; prompt text alone does not opt in, and only strict `true` authorizes the final `pull-request` stage to attempt provider-appropriate PR/MR/review creation. |
255
256
 
256
257
  Run examples:
257
258
 
258
259
  ```text
259
260
  /workflow ralph prompt="Plan and migrate the database layer to Drizzle" max_loops=3 base_branch=develop
260
- /workflow ralph prompt="Refactor authentication across the API, CLI, and web UI, then prepare the PR"
261
+ /workflow ralph prompt="Refactor authentication across the API, CLI, and web UI" create_pr=true
261
262
  /workflow ralph prompt="Safely implement the API refactor" git_worktree_dir=../atomic-ralph-api-wt base_branch=main
262
263
  ```
263
264
 
264
- Each `ralph` iteration writes an RFC-style technical design document under `specs/`, initializes an OS-temp implementation notes file, delegates implementation through sub-agents, runs a behavior-preserving code simplifier, and asks two reviewers to inspect the patch directly against `base_branch`. Reviewers discover any needed repository infrastructure themselves while inspecting the actual diff; Ralph no longer runs separate `infra-*` discovery stages. The loop stops when every reviewer approves or `max_loops` is reached, then runs a pull-request preparation stage.
265
+ Each `ralph` iteration writes an RFC-style technical design document under `specs/`, initializes an OS-temp implementation notes file, delegates implementation through sub-agents, runs a behavior-preserving code simplifier, and asks two reviewers to inspect the patch directly against `base_branch`. Reviewers discover any needed repository infrastructure themselves while inspecting the actual diff; Ralph no longer runs separate `infra-*` discovery stages. The loop stops when every reviewer approves or `max_loops` is reached. By default Ralph does not start the final `pull-request` stage, and `pr_report` is omitted. Prompt text alone does not opt in. Pass `create_pr=true` only when you explicitly want the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling; Ralph's own PR-creation instructions live in that final stage.
265
266
 
266
267
  Set `git_worktree_dir` when you want Ralph's worker stages isolated in a reusable Git worktree. Relative paths resolve from the invoking repository root, existing same-repository worktree roots are reused, and missing paths are created from `base_branch`. Ralph preserves the invoking repo-relative cwd inside the worktree, so launching from `repo/packages/api` with `git_worktree_dir=../repo-wt` runs stages from `../repo-wt/packages/api`.
267
268
 
@@ -273,13 +274,13 @@ Result fields:
273
274
  | `plan` | Latest RFC-style plan text. |
274
275
  | `plan_path` | Path to the latest generated spec under `specs/`. |
275
276
  | `implementation_notes_path` | OS-temp notes file containing decisions, deviations, blockers, and validation notes. |
276
- | `pr_report` | Pull-request preparation report: diff review, PR status, commands, and follow-up steps. |
277
- | `approved` | Whether the reviewer loop approved before PR handoff. |
277
+ | `pr_report` | Pull-request report emitted only when `create_pr=true` and the final `pull-request` stage runs. |
278
+ | `approved` | Whether the reviewer loop approved before completion or optional final handoff. |
278
279
  | `iterations_completed` | Number of plan/orchestrate/review loops completed. |
279
280
  | `review_report` | Compact reference to the latest reviewer payload artifact. |
280
281
  | `review_report_path` | JSON artifact path for the latest Ralph review round. |
281
282
 
282
- A typical end-to-end flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow goal objective="Implement the researched rate-limit behavior, run the focused tests, and finish when the documented burst behavior is validated"` when you can identify the work surface, state the exact outcome, and name the validation that proves it is done. Keep using `/workflow ralph` for larger migrations, broad refactors, multi-package changes, and spec-to-PR work where you want Atomic to plan, delegate through sub-agents, simplify, review, iterate, and prepare a pull-request report.
283
+ A typical end-to-end flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow goal objective="Implement the researched rate-limit behavior, run the focused tests, and finish when the documented burst behavior is validated"` when you can identify the work surface, state the exact outcome, and name the validation that proves it is done. Keep using `/workflow ralph` for larger migrations, broad refactors, multi-package changes, and spec-to-reviewed-change work where you want Atomic to plan, delegate through sub-agents, simplify, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`.
283
284
 
284
285
  ### `open-claude-design`
285
286
 
@@ -334,7 +335,7 @@ Use the goal workflow to implement specs/2026-03-rate-limit.md, run the focused
334
335
  ```
335
336
 
336
337
  ```text
337
- Use the ralph workflow to plan a database-layer migration, implement it, review it, and prepare a PR.
338
+ Use the ralph workflow to plan a database-layer migration, implement it, review it, and set `create_pr=true` for final-stage PR handoff.
338
339
  ```
339
340
 
340
341
  ```text
@@ -378,7 +379,7 @@ If the task is only deterministic TypeScript with no LLM/session stage, use a sc
378
379
  |-----------|-----|
379
380
  | Run, inspect, attach to, pause, interrupt, resume, or check status for an existing workflow | `/workflow ...` or `workflow({ action: ... })` |
380
381
  | Implement a small-to-medium scope change with an identifiable work surface, exact outcome, and named validation | `/workflow goal objective="..."` so Atomic keeps the run bounded, captures receipts in a goal ledger, gates completion through reviewers, and stops as `complete`, `blocked`, or `needs_human` |
381
- | Plan and execute a larger migration, broad refactor, multi-package change, or spec-to-PR effort | `/workflow ralph prompt="..."` so Atomic can plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and prepare a pull-request report |
382
+ | Plan and execute a larger migration, broad refactor, multi-package change, or spec-to-reviewed-change effort | `/workflow ralph prompt="..."` so Atomic can plan the approach, delegate implementation through sub-agents, simplify, review, and iterate; prompt text alone does not opt in to PR creation, so add `create_pr=true` only when you want the final `pull-request` stage and `pr_report` |
382
383
  | Create or edit reusable automation | a TypeScript workflow definition exported from `defineWorkflow(...).compile()` |
383
384
  | Track one-off work without saving a workflow file | direct `workflow({ task })`, `workflow({ tasks })`, or `workflow({ chain })` calls |
384
385
  | Make a workflow robust | design the stage graph, context handoffs, artifacts, validation gates, model fallbacks, and human approval points before coding |
@@ -1219,7 +1220,7 @@ Common builtin import targets:
1219
1220
  |---|---|---|---|
1220
1221
  | `deep-research-codebase` | `deepResearchCodebase` | `@bastani/workflows/builtin/deep-research-codebase` | Gather broad repo research before planning, synthesis, or implementation. |
1221
1222
  | `goal` | `goal` | `@bastani/workflows/builtin/goal` | Run a bounded implementation/check loop with receipts and reviewer-gated completion. |
1222
- | `ralph` | `ralph` | `@bastani/workflows/builtin/ralph` | Delegate a larger migration/refactor/spec-to-PR effort to Ralph's plan/orchestrate/review loop. |
1223
+ | `ralph` | `ralph` | `@bastani/workflows/builtin/ralph` | Delegate a larger migration/refactor/spec-to-reviewed-change effort to Ralph's plan/orchestrate/review loop; pass `create_pr=true` to authorize only the final PR-creation stage. |
1223
1224
  | `open-claude-design` | `openClaudeDesign` | `@bastani/workflows/builtin/open-claude-design` | Generate and refine a UI/design artifact and handoff spec. |
1224
1225
 
1225
1226
  Example parent workflow that runs builtin deep research, then chooses either `goal` or `ralph` as the nested implementation runner:
@@ -1234,7 +1235,7 @@ export default defineWorkflow("research-then-implement")
1234
1235
  "runner",
1235
1236
  Type.Union([Type.Literal("goal"), Type.Literal("ralph")], {
1236
1237
  default: "goal",
1237
- description: "Use goal for bounded changes or Ralph for broad spec-to-PR work.",
1238
+ description: "Use goal for bounded changes or Ralph for broad spec-to-reviewed-change work.",
1238
1239
  }),
1239
1240
  )
1240
1241
  .output("research_doc_path", Type.Optional(Type.String({ description: "Path to the deep-research document used for implementation." })))
@@ -1253,7 +1254,8 @@ export default defineWorkflow("research-then-implement")
1253
1254
  if (String(ctx.inputs.runner) === "ralph") {
1254
1255
  const implementation = await ctx.workflow(ralph, {
1255
1256
  inputs: {
1256
- prompt: `Use the research document at ${String(research.outputs.research_doc_path)} to plan, implement, review, and prepare a PR for: ${topic}`,
1257
+ prompt: `Use the research document at ${String(research.outputs.research_doc_path)} to plan, implement, and review: ${topic}`,
1258
+ create_pr: true,
1257
1259
  },
1258
1260
  stageName: "ralph implementation",
1259
1261
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bastani/atomic",
3
- "version": "0.8.26-alpha.1",
3
+ "version": "0.8.26-alpha.3",
4
4
  "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
5
5
  "type": "module",
6
6
  "atomicConfig": {