@bastani/atomic 0.5.18-0 → 0.5.19-0

package/.agents/skills/workflow-creator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-creator
-description: Create multi-agent workflows for Atomic CLI using defineWorkflow().run().compile() with ctx.stage() for session orchestration across Claude, Copilot, and OpenCode SDKs. Use whenever the user wants to create, edit, or debug workflows, build agent pipelines, define multi-stage automations, set up review loops, declare workflow inputs, run background/headless stages, or mentions .atomic/workflows/, defineWorkflow, ctx.stage, ctx.inputs, headless, background stages, or the atomic workflow picker.
+description: Create multi-agent workflows for Atomic CLI using defineWorkflow().run().compile() with ctx.stage() for session orchestration across Claude, Copilot, and OpenCode SDKs, AND invoke existing workflows on behalf of the user. Use whenever the user wants to create, edit, debug, or RUN workflows ("run the ralph workflow", "kick off deep-research-codebase", "start the gen-spec workflow"), build agent pipelines, define multi-stage automations, set up review loops, declare workflow inputs, run background/headless stages, or mentions .atomic/workflows/, defineWorkflow, ctx.stage, ctx.inputs, headless, background stages, the atomic workflow picker, or `atomic workflow -n`.
 ---
 
 # Workflow Creator
@@ -209,6 +209,9 @@ Workflows that accept a free-form prompt should declare it explicitly: `{ name:
 | Named, structured | `atomic workflow -n gen-spec -a claude --research_doc=notes.md` | Scripted structured runs |
 | Interactive picker | `atomic workflow -a claude` | Discovery; shows fuzzy list + form |
 | List | `atomic workflow -l` | Browse everything by source |
+| Detached (background) | `atomic workflow -n ralph -a claude -d "..."` | Scripted/CI runs where the caller shouldn't block on the TUI — the orchestrator keeps running on the atomic tmux socket; attach later with `atomic workflow session connect <name>` |
+
+Any of the named shapes above (positional or structured) accepts `-d` / `--detach` to run without attaching. Use it when you're automating from a script and want the CLI to return as soon as the session is spawned.
 
 **Builtin workflows are reserved** — local/global workflows cannot shadow them. Pick distinct names.
 
@@ -341,4 +344,110 @@ atomic workflow -n <workflow-name> -a <agent> --research_doc=notes.md --focus=st
 
 # Interactive picker (discovery)
 atomic workflow -a <agent>
+
+# Detached — run in the background without attaching. Useful when testing
+# from scripts or CI, or when the workflow will run long enough that you
+# want your terminal back. Reattach later with:
+#   atomic workflow session connect <printed-session-name>
+atomic workflow -n <workflow-name> -a <agent> -d "<your prompt>"
 ```
+
+## Running a Workflow on Behalf of the User
+
+When the user asks you to **run** (or "kick off" / "start" / "execute") a workflow — *not* author one — your job is to translate their request into a single `atomic workflow` invocation and run it. This section is the playbook for that flow. It is different from the authoring playbook above: the workflow already exists on disk; you just need to invoke it correctly.
+
+### You don't need to pass `-a` or `-d`
+
+When you (the agent) are running inside an atomic chat or workflow pane, the CLI reads `$ATOMIC_AGENT` from your environment and:
+
+- Fills in `-a <agent>` automatically if you don't pass it.
+- Forces detached mode on, so launching a workflow never takes over your pane.
+
+The practical result: your command is just `atomic workflow -n <name> <inputs>`. No provider flag, no detach flag, no chance of the orchestrator hijacking your terminal. The CLI prints the session name and returns immediately; you relay that name to the user.
+
+Override only when the user explicitly asks for a different provider (e.g. "run it on Copilot") — pass `-a copilot` and the CLI will honor it over the env var.
+
+### Always list first
+
+**Before anything else, run `atomic workflow list`.** (Optionally filter with `-a <agent>` if the user's pinned to one — usually unnecessary.) This is a cheap, read-only call that tells you three things in one shot:
+
+- Whether the workflow the user named actually exists.
+- What other workflows are available (so you can suggest close matches on a typo).
+- Source + metadata for every discoverable workflow (local vs. global vs. builtin).
+
+Skipping this step is how you end up guessing a name, typing it into `atomic workflow -n <name>`, and getting a `workflow not found` error you could have predicted. List first, decide second, run third.
+
+If the user's request is ambiguous ("run the research one"), the list output is also how you show them the candidates so they can pick — present the matching names and ask with AskUserQuestion.
+
+### If the workflow doesn't exist: offer to create it
+
+When the listed workflows don't include what the user asked for:
+
+1. **Tell the user explicitly** — "I don't see a `<name>` workflow in `.atomic/workflows/` or `~/.atomic/workflows/`. Available: \<short list from `atomic workflow list`>."
+2. **Check for typos first** — if one of the listed names is a close match, surface it via AskUserQuestion ("Did you mean `<close-match>`?") before offering to author anything.
+3. **Offer to create it** — ask with AskUserQuestion: "Want me to create a `<name>` workflow first?" with choices `Yes, create it` / `No, pick from the list` / `No, cancel`.
+4. **If yes → switch modes** — hand off to the authoring flow in the [Authoring Process](#authoring-process) section above (Steps 1-5). Interview the user for intent, write the file at `.atomic/workflows/<name>/<agent>/index.ts`, typecheck it, *then* come back to this runner section and invoke it. Do not skip the typecheck — an uncompiled workflow won't run.
+5. **If no → stop** — don't fabricate a command that will fail. Let the user redirect you.
+
+Never invent a workflow name or silently fall back to a different workflow. If the thing the user asked for doesn't exist, the correct answer is to say so and offer concrete next steps.
+
+### Collecting inputs with AskUserQuestion
+
+Once you've confirmed the workflow exists, you need to know two things about its invocation shape:
+
+1. **Does it declare a `prompt` input?** If so, it's free-form — you pass a positional string.
+2. **Does it declare structured inputs?** If so, you pass `--<field>=<value>` flags, one per required field.
+
+Read the workflow file at `.atomic/workflows/<name>/<agent>/index.ts` and inspect the `inputs` array. The `atomic workflow list` output is good for discovery but doesn't print the full schema — for accurate field types, requireds, and enum values, read the source.
+
+Once you know the schema, use the **AskUserQuestion tool** to collect any values the user hasn't already provided in their message. One question per missing input field. For enum fields, pass the declared `values` as multiple-choice options so the user sees exactly what's allowed. Keep questions tight and purposeful — if the user's message already answers a question, don't ask it again.
+
+Skip AskUserQuestion entirely when:
+- The user already supplied every required value in their message ("run ralph on 'add OAuth to the API'" — the prompt is right there).
+- The workflow declares no required inputs and needs no prompt.
+
+### End-to-end recipe
+
+1. **List available workflows** — run `atomic workflow list`. Always. This is your ground truth.
+2. **Resolve the target**:
+   - Exact match in the list → continue.
+   - Close match → confirm via AskUserQuestion before proceeding.
+   - No match → tell the user what's available and offer to author it (see previous section). If they decline, stop.
+3. **Discover the inputs schema** — read the workflow source file and inspect `inputs`.
+4. **Ask for missing inputs** — use AskUserQuestion, one question per unanswered required field. Enums become multiple-choice.
+5. **Invoke** — build one of these commands:
+   - Free-form: `atomic workflow -n <name> "<prompt>"`
+   - Structured: `atomic workflow -n <name> --<field1>=<value1> --<field2>=<value2>`
+6. **Report the session name** the CLI printed and tell the user: "attach any time with `atomic workflow session connect <session>` — or `atomic workflow session list` to see what's running."
+
+### Worked examples
+
+**Example A — workflow exists, structured inputs**
+
+> **User:** "run gen-spec on research/docs/2026-04-11-auth.md"
+
+1. Run `atomic workflow list`. Output includes `gen-spec` under local. Good.
+2. Target resolved exactly: `gen-spec`.
+3. Read the workflow source → inputs are `research_doc` (required string — already given), `focus` (required enum of `minimal|standard|exhaustive`, no default), `notes` (optional text).
+4. Ask via AskUserQuestion once: "What focus level for the spec?" with choices `minimal`, `standard`, `exhaustive`. User picks `standard`. Skip `notes` since it's optional.
+5. Run: `atomic workflow -n gen-spec --research_doc=research/docs/2026-04-11-auth.md --focus=standard`
+6. The CLI prints a session name like `atomic-wf-claude-gen-spec-a1b2c3d4`. Tell the user: "Started in the background. Attach with `atomic workflow session connect atomic-wf-claude-gen-spec-a1b2c3d4` or check progress with `atomic workflow session list`."
+
+**Example B — workflow does not exist**
+
+> **User:** "run the security-audit workflow on src/auth"
+
+1. Run `atomic workflow list`. Available: `ralph`, `deep-research-codebase`, `gen-spec`, `review-to-merge`. No `security-audit`.
+2. Tell the user: "I don't see a `security-audit` workflow. Available: ralph, deep-research-codebase, gen-spec, review-to-merge."
+3. Ask via AskUserQuestion: "Want me to create a `security-audit` workflow first?" with choices `Yes, create it`, `No, use one of the existing workflows`, `No, cancel`.
+4. If **Yes**: switch to the Authoring Process — interview the user for what the workflow should do, draft it, typecheck, *then* return here and invoke it.
+5. If **No, use existing**: ask which one via AskUserQuestion over the listed options, then continue from step 3 of the recipe.
+6. If **Cancel**: stop, no command runs.
+
+### Common mistakes to avoid
+
+- **Skipping `atomic workflow list`** — leads to guessing and `workflow not found` errors. It's a one-line command; always run it.
+- **Inventing a workflow name** — if it's not in the list, it doesn't exist. Say so and offer to author it.
+- **Asking everything at once** — let AskUserQuestion drive one question per field. Enum fields are multiple-choice, not free text.
+- **Re-asking what the user already said** — read their message first.
+- **Forgetting to report the session name** — the user needs it to reattach.

package/.agents/skills/workflow-creator/references/workflow-inputs.md

@@ -241,12 +241,22 @@ atomic workflow -n gen-spec -a claude \
 
 # Structured, long-form flag value (= form)
 atomic workflow -n gen-spec -a claude --focus standard --research_doc notes.md
+
+# Detached (background) — starts the orchestrator on the atomic tmux
+# socket and returns immediately. The command prints the session name
+# and hints for attaching later. Use this for scripted / CI runs where
+# the caller shouldn't block on the TUI.
+atomic workflow -n hello -a claude -d "hello world"
+atomic workflow session connect atomic-wf-claude-hello-<id>   # attach later
 ```
 
 Both `--flag=value` and `--flag value` forms are accepted. Short flags
 (`-x value`) are NOT parsed as structured inputs — only long-form
 `--<name>` flags resolve against the schema.
 
+The `-d` / `--detach` flag composes with any named shape (positional
+prompt, structured flags) and is independent of the inputs schema.
+
 ## Pitfalls
 
 ### Declare every field you access

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp",
+      "headers": { "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}" }
+    }
+  }
+}

package/.opencode/opencode.json

@@ -2,9 +2,12 @@
   "$schema": "https://opencode.ai/config.json",
   "permission": "allow",
   "mcp": {
-    "gh_grep": {
+    "github": {
       "type": "remote",
-      "url": "https://mcp.grep.app"
+      "url": "https://api.githubcopilot.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
     }
   }
 }