@bastani/atomic 0.9.5-alpha.2 → 0.9.5-alpha.4

package/docs/workflows.md

@@ -58,7 +58,7 @@ Use direct chat only for tiny, deterministic, low-risk work where workflow track
 
 ## Quick Start
 
-On a fresh first run with no prior Atomic startup state, Atomic can route your first pasted ticket, issue, spec path, or task prompt into normal workflow-driven agent work. Returning users with prior startup state are marked onboarded automatically and continue directly into the normal chat UI; stored credentials by themselves do not skip onboarding. If you are not logged in or configured yet, Atomic keeps the latest seed in memory only, asks you to run `/login`, and resumes after login succeeds. Once ready, onboarding raises the selected model to high reasoning when supported and hands the seed to the normal coding-agent session with instructions to first estimate likely scope from the seed text alone. Tickets, GitHub issues, and especially specs often list enough work items, files, tests, docs, migrations, or acceptance criteria to make an initial tiny/small/medium/large/unknown call without immediately inspecting the repo. That text-only estimate is only a routing confidence signal, not final implementation planning. If the seed makes the task clearly tiny or small and high-confidence, the parent can route directly; if referenced context must be read or the scope is medium, large, unclear, risky, or not obviously tiny, the parent inspects only the necessary issue/spec/path/repo area and can use targeted read-only subagents such as `codebase-locator`, `codebase-analyzer`, and `codebase-pattern-finder` at their normal defaults before making the high-reasoning routing decision: `goal` for small fixes/quick fixes, `ralph` for non-trivial work around 2k+ changed lines or many files/areas. It then starts the selected workflow and continues normally. Type `/chat` before handoff to skip this one-time routing and use Atomic as a normal coding-agent chat.
+On a fresh first run with no prior Atomic startup state, Atomic shows a one-time explanation after any What's New notes and directly above the normal input box describing Atomic as a verifiable coding agent runtime for building and running agent workflows you can feel confident in. It no longer intercepts the first message, saves a pasted seed, routes to `goal` or `ralph`, raises reasoning, or requires `/chat` to use normal chat. Type a normal message or slash command immediately; run `/login` first if no provider is connected, use `/atomic` for guides, `/workflow list` to discover built-ins, or launch a workflow command directly when you already know what you want.
 
 The fastest way to get a workflow running is to **describe it in natural language** and let Atomic write it for you. If you'd rather write the TypeScript yourself, jump to [Or hand-write the TypeScript](#or-hand-write-the-typescript) below.
 
@@ -110,7 +110,7 @@ Then list and run it like any other workflow:
 /workflow <name> key=value ...
 ```
 
-Named workflow runs are background-oriented. After launch, expect a run id and monitor it with `/workflow status <run-id>`, F2, or `/workflow connect <run-id>`. First-run `goal`/`ralph` handoffs print those exact commands in the dispatched card; use connect to watch, attach, and steer, or ask in the current chat for status or steering at any point.
+Named workflow runs are background-oriented. After launch, expect a run id and monitor it with `/workflow status <run-id>`, F2, or `/workflow connect <run-id>`.
 
 ### Or hand-write the TypeScript
 
@@ -421,6 +421,25 @@ Workflows are the default path when a request is non-trivial, has inherent struc
 
 Use direct chat instead only for tiny, deterministic, low-risk edits or answers where stage tracking would add more overhead than value, usually a clearly single-file/no-test/no-review edit. If the task is only deterministic TypeScript with no LLM/session stage, use a script, custom tool, or extension command instead.
 
+### Decide before you explore
+
+Make the inline-vs-workflow decision **before the first tool call** on a request, and state it in one short line. Reconnaissance counts as inline execution — reading code, searching, and running probe scripts is already "doing the task" — so an unstated "look around first" default silently commits the session to unbounded inline work, which is exactly how workflow-fit tasks turn into hours of exploration with nothing committed.
+
+When a task passes the checklist above:
+
+- Keep pre-workflow scoping to a few quick reads whose only purpose is writing a sharper objective and validation criteria.
+- Put deep research, upstream/design comparison, and behavior probing *inside* the workflow — any workflow with a research or analysis stage, whether user-defined or builtin (for example `ralph`'s research stage) — not before it.
+
+### Course-correct instead of drifting
+
+If a session drifts anyway — roughly ten or more tool calls of exploration with no artifact, edit, or commit to show, or a repeating "let me verify one more thing" loop — stop and hand off:
+
+1. Write the findings so far to a context file.
+2. Launch the best-fit workflow with that file passed via `reads` and a prompt like ``Read the file at `<path>` ...`` — check `workflow({ action: "list" })` for named or user-defined workflows that match the task first, falling back to the builtin `goal` or `ralph` when nothing more specific fits.
+3. Let the workflow own the implementation while you monitor lifecycle notices.
+
+Sunk inline research is never a reason to stay inline; it transfers via files.
+
 | User goal | Use |
 |-----------|-----|
 | Run, inspect, attach to, pause, interrupt, resume, or check status for an existing workflow | `/workflow ...` or `workflow({ action: ... })` |

package/npm-shrinkwrap.json

@@ -1,15 +1,15 @@
 {
 	"name": "@bastani/atomic",
-	"version": "0.9.5-alpha.2",
+	"version": "0.9.5-alpha.4",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@bastani/atomic",
-			"version": "0.9.5-alpha.2",
+			"version": "0.9.5-alpha.4",
 			"license": "MIT",
 			"dependencies": {
-				"@bastani/atomic-natives": "0.9.5-alpha.2",
+				"@bastani/atomic-natives": "0.9.5-alpha.4",
 				"@bufbuild/protobuf": "^2.12.1",
 				"@earendil-works/pi-agent-core": "^0.80.3",
 				"@earendil-works/pi-ai": "^0.80.3",
@@ -514,16 +514,16 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives": {
-			"version": "0.9.5-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.5-alpha.2.tgz",
+			"version": "0.9.5-alpha.4",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.5-alpha.4.tgz",
 			"license": "MIT",
 			"optionalDependencies": {
-				"@bastani/atomic-natives-darwin-arm64": "0.9.5-alpha.2",
-				"@bastani/atomic-natives-darwin-x64": "0.9.5-alpha.2",
-				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.5-alpha.2",
-				"@bastani/atomic-natives-linux-x64-gnu": "0.9.5-alpha.2",
-				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.5-alpha.2",
-				"@bastani/atomic-natives-win32-x64-msvc": "0.9.5-alpha.2"
+				"@bastani/atomic-natives-darwin-arm64": "0.9.5-alpha.4",
+				"@bastani/atomic-natives-darwin-x64": "0.9.5-alpha.4",
+				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.5-alpha.4",
+				"@bastani/atomic-natives-linux-x64-gnu": "0.9.5-alpha.4",
+				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.5-alpha.4",
+				"@bastani/atomic-natives-win32-x64-msvc": "0.9.5-alpha.4"
 			},
 			"engines": {
 				"bun": ">=1.3.14",
@@ -531,8 +531,8 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives-darwin-arm64": {
-			"version": "0.9.5-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.5-alpha.2.tgz",
+			"version": "0.9.5-alpha.4",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.5-alpha.4.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -543,8 +543,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-darwin-x64": {
-			"version": "0.9.5-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.5-alpha.2.tgz",
+			"version": "0.9.5-alpha.4",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.5-alpha.4.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -555,8 +555,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-gnu": {
-			"version": "0.9.5-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.5-alpha.2.tgz",
+			"version": "0.9.5-alpha.4",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.5-alpha.4.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -570,8 +570,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-gnu": {
-			"version": "0.9.5-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.5-alpha.2.tgz",
+			"version": "0.9.5-alpha.4",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.5-alpha.4.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -585,8 +585,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-arm64-msvc": {
-			"version": "0.9.5-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.5-alpha.2.tgz",
+			"version": "0.9.5-alpha.4",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.5-alpha.4.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -597,8 +597,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-x64-msvc": {
-			"version": "0.9.5-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.5-alpha.2.tgz",
+			"version": "0.9.5-alpha.4",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.5-alpha.4.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.5-alpha.2",
+  "version": "0.9.5-alpha.4",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -77,7 +77,7 @@
     "prepublishOnly": "bun run clean && bun run build && bun run shrinkwrap"
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.5-alpha.2",
+    "@bastani/atomic-natives": "0.9.5-alpha.4",
     "@bufbuild/protobuf": "^2.12.1",
     "@earendil-works/pi-agent-core": "^0.80.3",
     "@earendil-works/pi-ai": "^0.80.3",