# A-1 Spike: Programmatic Invocation of Claude Code Dynamic Workflows

Tests the highest-risk assumption blocking Work Graph execution design
(`docs/sdd/00-SDD-生成记录.md` A-1; `docs/graphlemon_architecture.md` §10.1;
`docs/sdd/05-实施约束与依赖.md` §5.4/5.5).

## What's already confirmed by official docs (no need to re-derive)

From `code.claude.com/docs/en/workflows` and `code.claude.com/docs/en/headless`:

- Dynamic workflows are real: JS scripts using `agent()` / `pipeline()` / `parallel()`, saved under `.claude/workflows/*.js`, invoked as `/<name>` with an `args` object.
- They explicitly run in `claude -p` (headless) and the Agent SDK, not just interactively.
- Permission table states plainly: for `claude -p` and the Agent SDK, the run "starts immediately" — never prompted.
- `--output-format json` + `--json-schema` returns parseable `structured_output`, plus `total_cost_usd` / token usage.
- Requires Claude Code **v2.1.154+**; on Pro, "Dynamic workflows" must be turned on once via `/config` in an interactive session.

This resolves the doc-level question. What's *not* confirmed is whether it actually behaves this way end-to-end on a real account, with a real fan-out, unattended — that's what this spike runs.

## What this spike actually tests

1. **Unattended execution** — `claude -p ... < /dev/null` (no stdin available at all): does it complete without hanging on a prompt?
2. **Real fan-out** — the workflow computes squares of 3 numbers via 3 separate `agent()` calls, reduced in script code. Correct output (`sum == 29`) is only possible if the runtime actually executed the graph, not just echoed something.
3. **Structured, parseable output** — can the result be consumed programmatically (`structured_output.sum`), which is what `c_work_graph_execute`'s implementation would need to do?
4. **`--bare` mode compatibility** — docs recommend `--bare` for scripted/SDK calls, but `--bare` skips auto-discovery of things like skills/MCP/hooks; it's untested whether it still finds `.claude/workflows/`.

Note: I checked this sandbox — `claude` CLI v2.1.219 is present (well above the version requirement) but **not logged in**, so I can't run this spike myself. It needs to run on your machine, where `claude` is authenticated against your actual plan.

## Prerequisites

- Claude Code CLI installed and logged in (`claude /login`), v2.1.154+
- A plan with dynamic workflows available (Pro/Max/Team/Enterprise) — on Pro, enable it once via `/config` in an interactive `claude` session before running this
- `python3` on PATH

## Run it

```bash
cd spikes/a1-dynamic-workflows
./run-spike.sh /path/to/any/git/repo
```

Any git repo works as the target — it doesn't need to be graphlemon itself. The script copies `workflow-under-test.js` into `<target>/.claude/workflows/graphlemon-a1-spike.js`, runs it twice (normal and `--bare`), saves raw JSON results, and prints a pass/fail verdict.

## Interpreting the result

- **All Test 1 checks pass** → A-1 confirmed. Proceed with architecture.md §10.1 Option A. `check-results.py` prints the exact refinement to fold into `03-C-控制与接口.md` for `c_work_graph_execute` (spawn `claude -p` as a subprocess, parse `structured_output`).
- **Test 1 fails** → A-1 not confirmed as tested. Check the printed `result` field for the actual error (commonly: workflows not enabled on the plan, wrong CLI version, not logged in). If it can't be resolved, treat A-1 as rejected — fall back to architecture.md §10.1 Option B (fully custom Graph Engine), which cascades into rewriting SDD §3.4-3.6 and §5.4/5.5.
- **Test 2 (`--bare`) fails independently of Test 1** → not fatal to A-1 itself, just means `c_work_graph_execute` must invoke `claude -p` without `--bare` (slower cold start, but reliable workflow discovery).

## After running

Report back the printed verdict (and the two `result-test*.json` files if anything looks ambiguous) so A-1's status in `docs/sdd/00-SDD-生成记录.md` and `docs/sdd/sdd-mvcp-contract.json` can be updated from `pending` to `confirmed` or rejected, and 03-C can be refined with the concrete invocation contract.