SCION Task Force

Hand a ticket to an AI coding agent: tag it taskforce, and saving it starts a SCION worker. You review the worker's report on the ticket, then close the ticket, which stops the worker. Ticket in, report out: the ticket is the only interface, and the project does not need to be a git repository.

The plugin (tk-scion-taskforce) runs only when a ticket is saved. No daemon runs. For the narrative walkthrough, see the SCION Task Force Workflow. For design and internals, see SCION-TASKFORCE-SPEC.md.

Prerequisites¶

Install¶

./install.sh --scion-taskforce

This links tk-scion-taskforce into ~/.local/bin/. Keep that directory on your $PATH.

Quick start¶

tk scion-taskforce init                            # setup wizard; offers to run `test` at the end
tk scion-taskforce test                            # end-to-end check through a real ticket
tk create "Fix the login redirect" --tags taskforce # the save starts a worker
tk show <id>                                       # read the worker's report
tk add-note <id> "Also cover the logout path"      # forwarded to the worker
tk close <id>                                      # stops the worker

Setup wizard¶

tk scion-taskforce init runs tk init when .tickets/ is missing and scion init when .scion/ is missing. In a terminal it then asks eight questions. Each is a numbered menu: Enter takes the default (*), Other takes typed input, and q quits without changes. You confirm a summary before anything is written.

Auth follows the harness:

init writes or changes these files:

init also links the folder to the Scion Hub once (scion hub link). Dispatch links only a project that has a task force config and became unlinked. Re-running init keeps your config values and template edits. --defaults skips the questions and installs no role skills; --force starts over.

Lifecycle¶

Every successful ticket write (CLI or Web UI) runs tk scion-taskforce on-save <id> in the background. It acts only on tickets carrying the opt-in tag:

tk scion-taskforce gc deletes the stopped workers of tickets closed more than watcher.gc_retention_days (5) days ago.

Status notes start with **Task Force:**. They are written straight to the file, so they never re-trigger the hook and are never forwarded.

Writes that bypass tk fire no hook: hand edits, git pull and worker edits. A worker's report therefore lands on the next save of any ticket in the project, or when you run tk scion-taskforce sync. sync also checks each running pod:

• A dead pod gets a "worker lost" note.
• A pod whose Scion activity is completed, waiting_for_input or limits_exceeded has finished its turn. Its report is merged; without one, the worker is paused with a note, which frees its slot. Add a note to answer or redirect it.

To pick up reports without saving anything, keep tk scion-taskforce watch running in a terminal. It repeats sync every 60 seconds until you press Ctrl-C. Nothing runs in the background after that.

Git, privacy and role skills¶

Git is optional¶

worker.git sets what workers may do with git:

Privacy¶

worker.privacy defaults to confidential. Workers are then told not to upload or publish project content, push, or comment on external systems. skills install drops skills that publish content, and status warns when the Scion Hub endpoint is not local. Set standard to lift these limits, for example to let PR reviews post a gh pr comment.

Role skills¶

Every worker runs on the project's one worker template (how the pod runs). Role knowledge ships as skills (how to do the job). tk scion-taskforce skills install [<role>...] turns roles from scion-frontiers/agent-team into skills under .agents/skills/:

• Default set: developer, code-reviewer, investigator, doc-writer, test-engineer, security-auditor, researcher, architect. Name others explicitly (for example qa-tester). Coordinator roles are left out because tk is the coordinator.
• Upstream is fetched once at a pinned commit (--ref <sha> overrides), so nothing is downloaded when a worker starts. Per-role model and resource settings are not carried over.
• Re-running keeps existing skills. --force regenerates generated skills (those with UPSTREAM.md) only; hand-made skills and folders without the tk-scion- prefix are never touched. uninit removes generated skills.
• Offline or air-gapped: mirror the repos as <dir>/<owner>/<repo>/, then run skills install --from <dir>.
• Git: tk neither commits nor ignores the skills. Commit them to share (git add .agents/skills/tk-scion-*) or keep them local (echo '/.agents/skills/tk-scion-*/' >> .git/info/exclude). If Scion gives a worker its own worktree, that worktree holds only committed files, so commit the skills to use them there.
• The skills are plain SKILL.md files, so people and local agents can use them outside Scion too.

How the brief uses them (the brief names file paths, so this works with any harness):

Custom briefs (worker.prompt_file) get the same section through the {skills} placeholder.

Migrating from role templates. templates install and templates list still work as deprecated aliases of skills (removal after 2027-04-01). Old generated .scion/templates/tk-<role>/ templates keep working for a role that has no skill yet. To switch: run tk scion-taskforce skills install, then delete the old tk-<role> folders (uninit also removes them).

tk inside workers¶

Worker images do not ship tk. At each start the task force finds tk on this machine and mounts it read-only at /usr/local/bin/tk in the worker. It checks $TK_SCRIPT (the tk that is running) first, then tk and ticket on PATH, so nothing machine-specific is stored in the project. The mount travels as a Scion launch config (scion start --config), saved next to the brief as <id>.scion-config.json. It also sets TK_NO_HOOKS=1 inside the worker, because the shared checkout's save hook needs the plugin, which the container lacks.

If tk is not found, or provider.mount_tk is false, the worker edits .tickets/<id>.md directly. Turn the mount off when workers run on a remote Scion broker, where your local path does not exist.

The brief, the seeded template and the role skills tell workers to use tk as their only channel:

Workers never close, reopen or create tickets. init updates the old report section of an existing worker template in place; role skills update with skills install --force.

Automatic actions¶

The task force fixes safe, reversible plumbing on its own and records each fix. status lists the latest five under Automatic actions; logs has them all.

What only you can fix (Hub down, a runtime that will not start, missing credentials) appears as one ticket note with the next step, and under Needs you in status. Saving the ticket or running sync retries.

Commands¶

tk scion-taskforce [--config <path>] [--dry-run] <subcommand> [args...]

--config adds a config file on top of the others. --dry-run simulates every scion call.

The removed daemon commands (start, stop, restart, server, project) exit with code 2 and print what to use instead.

Configuration¶

init writes the full key reference, with a comment on every key, to .scion-taskforce/scion-taskforce.yaml. Files are deep-merged, low to high:

1. Built-in defaults
2. ~/.config/tk/scion-taskforce.yaml (or $XDG_CONFIG_HOME/tk/)
3. <project>/.scion-taskforce/scion-taskforce.yaml
4. The file in $TK_SCION_TASKFORCE_CONFIG
5. --config <path>

Commonly edited keys:

Logs and state¶

Logs rotate daily (UTC) or at 100 MB. Set TK_SCION_TASKFORCE_LOG_DIR or TK_SCION_TASKFORCE_STATE_DIR to move them.

Troubleshooting¶

Live test¶

After changing the plugin, run the black-box live test with real Scion workers in a scratch project (initialised, with tk scion-taskforce skills install doc-writer):

cd /path/to/scratch-project && bash /path/to/ticket/plugins/scion-taskforce/scripts/live-test.sh

It covers create, a note to a paused worker, close, reopen with a new note, and a role:doc-writer review ticket, and prints each step's time and PASS or the failing step. Outputs go to test-runs/<timestamp>/.

Uninstall¶

tk scion-taskforce uninit                         # per project: workers, config, template, hook
tk scion-taskforce uninit --global                # global config
./plugins/scion-taskforce/install.sh --uninstall  # remove the binaries