# Interactive commands

Commands here **require a human in the session** and are deliberately kept out of `plugin/commands/`.

`plugin/commands/` is buildtime content: it is synced into every project and its descriptions are
loaded into every session, including unattended runs like the build benchmark. Anything in there
costs always-on context on runs that can never use it.

These two cannot proceed unattended:

| command | why it needs a human |
|---------|----------------------|
| `connector-onboarding` | opens with `AskUserQuestion` to choose a connector approach |
| `connector-test` | must ask whether testing may mutate provider data before it runs anything |

Measured on the build benchmark: neither was invoked in any run, while together with the skills
they route to they accounted for roughly 1,150 of ~2,725 always-on tokens, about 42% of the
budget, on every autonomous run.

## Status: parked, not yet wired

The CLI does not read this directory yet. `scaffoldConnectorEnv` copies exactly
`connector-guide.md`, `skills/`, `commands/` and `agents/`, so anything here is currently ignored
and syncing is unaffected.

Wiring it up needs a CLI change, and there is a real decision in it. Both `stackone agent setup
--local` and `stackone agent sync` call the same `scaffoldConnectorEnv`, so "install these only
for humans" cannot be expressed today. Two workable shapes:

1. **Install path decides.** `setup --local` (a person configuring their repo) installs these;
   `sync` does not. Simple, but a developer who runs `sync` after a CLI update silently loses
   them, which is surprising.
2. **Caller opts out.** Both paths install them by default and automation passes something like
   `--buildtime-only`. Humans keep everything; the benchmark opts out. More plumbing, no
   surprising loss.

Shape 2 is the safer default: the failure mode is paying some context you did not need, rather
than a developer losing commands they had yesterday.

Until then, these belong to an interactive Claude Code session in a project set up with
`stackone agent setup --local`. `connector-test` also overlaps `stackone run`, which is the
primitive it orchestrates, so some of it may belong in the CLI itself rather than as a command.