# Usage ## Select, queue, and run a task Normal implementation uses one explicit workflow contract: 1. Start with `takt-pi-orchestrator` and resolve the exact target/profile. 2. Call `takt_workflow_catalog`. It reads effective project > user-global > builtin standalone workflows, honors `enable_builtin_workflows` and `disabled_builtins`, and returns categories, descriptions, and source. 3. Always show/select one workflow for a fresh route. Explicit workflow directives and resume workflows are displayed as locked. Catalog failure is fail-closed; never silently choose `default`. 4. Planner produces one task body with an exact `workflow: ` line, resolves explicit per-task `worktree` and PR mode choices, and asks for confirmation. 5. `takt_enqueue_task` directly writes `.takt/tasks.yaml` and the task's `order.md`, then verifies the persisted workflow and delivery fields. A post-write verification failure preserves the pending task as unverified and blocks execution. 6. After explicit user run intent, call `takt_run_pending` with the named profile. It starts public `takt run` for **all pending tasks** in the shared PTY/widget lifecycle. `/takt:start` does the same with interactive confirmation. The bridge owns direct task-file persistence with TAKT-compatible locking and atomic replacement. `takt exec` is separate instant/interactive mode, not the normal queue/run path. For agent-driven work, start with the bundled `takt-pi-orchestrator` Skill. It asks the minimum TAKT target/intent/setup questions, then routes to `takt-pi-next-step`, `takt-pi-task-planner`, or `takt-pi-runner`. `takt-pi-next-step` is the ask-matt-style navigator: it reads current evidence, names one concrete next action, and hands off to the Skill that owns that boundary. Its preflight phases are `takt-pi-intake`, `takt-pi-project-setup`, `takt-pi-workflow-selection`, `takt-pi-queue-gate`, and `takt-pi-run-gate`. They cover target resolution through the final execution-intent decision. The planner discusses the goal, scope, non-goals, acceptance criteria, and validation in Pi, asks for confirmation, then calls `takt_enqueue_task`. The tool queues and verifies the finalized body directly and does not start execution. The runner handles explicit queue/run execution and recovery. ## Start and stop `/takt:start` asks for confirmation, then starts `takt run` in the selected project inside a PTY. Pass an absolute folder path to target another registered or unregistered project, for example `/takt:start C:\\work\\repo`. TAKT owns task execution and worktree creation. The live widget shows the same terminal output that a normal `takt run` terminal shows, including intermediate output. `/takt:stop [path]` sends Ctrl-C and uses a bounded force-kill fallback when the child does not exit. A stop timeout is reported as an error; Pi never retries indefinitely or stops a PTY it did not create. `/takt:project C:\\work\\repo` registers a folder for recurring detection. The registry is stored in the user config directory, not in the vault. The current Pi folder is always included. For a one-shot project bootstrap, use `/takt:project:init [profile]`. It creates the project-local `.takt/exec/presets/` and `.takt/workflows/` directories, registers the project, and saves a named profile. The equivalent agent tool is `takt_project_setup`: ```json { "profile": "pi-takt-marionette", "cwd": "C:/work/repo", "preset": "pi-docs", "copyGlobalPreset": true } ``` When the selected preset is absent locally, setup copies only that preset from the global TAKT directory. It does not copy tasks, runs, sessions, logs, or credentials. Existing local presets are never overwritten, so the operation is safe to repeat. ### Named project profiles Use a profile when a project is used repeatedly. Register the path and default exec preset once: ```text /takt:profile:add pi-docs ``` Enter `C:\\Users\\Keisu\\Projects\\OSS\\takt` as the folder and `pi-docs` as the optional preset. Later, the profile name resolves to that folder for all project-targeting commands: ```text /takt:clear pi-docs /takt:exec pi-docs /takt:send pi-docs /takt:status pi-docs ``` `/takt:profile` lists saved profiles and `/takt:profile:remove pi-docs` removes the alias without removing the watched project folder. Profile data lives in the user config directory. The bridge never searches arbitrary directories or silently selects a similarly named repository. `@pi-docs` is accepted as an explicit alias form. ## Agent Skill automation The package includes `takt-pi-runner` and `to-takt-tasks`. In the `grill-with-docs → to-spec → to-takt-tasks` route, one Spec is one TAKT execution group: child tickets remain separate artifacts, but one aggregate task is enqueued on one branch/worktree. `to-takt-tasks` requires an explicit per-task worktree choice and PR mode (`none`, `regular`, or `draft`); regular and draft PRs require an isolated worktree. The bridge persists and verifies the selected `auto_pr` / `draft_pr` fields. For normal implementation, the runner preserves the orchestrator's locked `workflow: ` contract and calls `takt_run_pending` only after explicit user run intent. The tool resolves the named profile, starts all pending tasks through public `takt run`, and shares the live raw PTY/widget lifecycle with `/takt:start`. It returns after the PTY starts; use `takt_read_screen` and the widget for progress. `takt_exec_prompt` remains available only for an explicit instant/interactive `takt exec` request. That path owns clear → exec → prompt → `/go` and may enter `pi-auto`; it is not used for the normal planner → enqueue → queue/run path. When the user requires an exact builtin or project workflow, the runner uses `takt_run_workflow` instead of treating `workflow:` as prompt prose. The tool starts a bridge-owned direct TAKT run and forwards `--task`, `--workflow`, provider/model, repository, and PR flags as separate arguments. Pass `prNumber` instead of `task` for PR-review fixes; the bridge emits `--pr ` so TAKT fetches review comments and preserves the PR base/head and branch context. `task` and `prNumber` are mutually exclusive. Pi extension sources can be injected temporarily for that run without modifying Pi settings. An exact `#` task remains a positional issue reference so TAKT fetches the issue instead of treating it as literal task prose. `autoPr` and `draftPr` require `pipeline:true`, matching TAKT's CLI contract; the bridge rejects that invalid combination before launching a child process. ### Pi provider/model preflight For Pi execution, `provider` is the TAKT executor and must remain `pi`. `model` is a fully qualified Pi route in the form `/`, for example `opencode-go/muse-spark-1.3-contributor`. On older/global TAKT releases that support it, add the thinking level after the route: `opencode-go/muse-spark-1.3-contributor:xhigh`. This suffix is not a provider option or a model name; verify the selected TAKT release's syntax first. `pi --list-models` only supplies candidates. The embedded TAKT runtime may resolve models from its shipped catalog and `models.json` while not loading Pi's `models-store.json`, so a candidate can still fail with a model-not-found error. The model preflight must verify the exact route before enqueue/run and must preserve the target profile/cwd. After launch, inspect the target's `.takt/runs/*/meta.json`; the shared widget can show a stale row, and a PTY start acknowledgement does not prove model resolution or task progress. Do not create `.takt/runtime.yaml` or mutate global model settings just to retry a missing route. Use `takt_stop` to stop a stuck bridge-owned session without confirmation, and `takt_set_mode` for explicit mode changes. `takt_read_screen` reports status, PID, stage, and last exit so agents can tell `live` / `stale` / `completed` / `unknown` apart and distinguish `pasting` / `sending_go` / `running`. During paste stages the widget shows a truncated prompt preview instead of the full body. `running` describes workflow activity. `ptyRunning` separately reports whether the bridge still owns a live interactive TAKT terminal. A completed workflow can therefore report `status: completed`, `running: false`, and `ptyRunning: true` until that reusable terminal exits or is stopped; this does not mean the workflow is still executing. To continue a checkpoint without resubmitting the task, call `takt_resume_run` after the owned PTY has stopped: ```json { "profile": "dtm-cursor", "provider": "devin", "model": "swe-1-7" } ``` For DTM Cursor, the bridge runs `takt --provider devin --model swe-1-7 resume`, waits for TAKT's `Requeue` menu, and selects it with a literal Enter. It does not run `takt clear` or paste the original task again. `takt_stop` also accepts `forceObserved: true` to close stale/ownerless `running` metadata while preserving unknown fields such as TAKT's checkpoint data. It never kills an external live PID. For non-DTM projects using a custom Pi provider, configure required Pi extensions in the project's `.takt/config.yaml` under `provider_options.pi.extensions`. TAKT 0.61 does not reliably carry actor-local `provider_options` from an exec preset into the generated immutable workflow, so the project-level setting is the stable route for models such as `cursor/composer-2.5-fast`. ## Manual GO mode Use manual mode when task clarification should never start execution automatically: ```json { "profile": "dtm-cursor", "prompt": "", "goMode": "manual", "replace": true } ``` The bridge waits for the assistant's clarification response and a fresh `Assistant>` prompt, then returns `sentGo: false` and `awaitingGo: true`. Nothing sends `/go` until `takt_submit_go` is called. Legacy `sendGo: false` selects the same manual behavior. Auto and explicit GO both send raw `/go` plus Enter; bracketed paste remains reserved for multiline task bodies. Force the skill with `/skill:takt-pi-runner `. If the bridge tool or profile is unavailable, or the named profile resolves to a different cwd, the skill stops with the exact reload/package or profile/cwd mismatch; it never uses `taskkill`, Computer Use, a guessed cwd, direct shell `takt exec`, or another provider. The extension only controls child processes it started. A `takt run` or `takt exec` process started in another terminal is observed through `.takt` metadata once it creates a run, but Pi cannot safely attach to that terminal's raw PTY. Such external activity never renders in the live widget automatically; inspect it explicitly with `/takt:status [path]` or `takt_read_screen`, and Pi still never kills it. Typing `@