Glossary
Short definitions of factory terms. Each entry links related terms and the docs page that covers it. Look a term up with `kusaw glossary <term>`.
Short definitions of factory terms. Each entry links related terms and the docs page that covers it. Look a term up with kusaw glossary <term>.
Attempt
One execution of a step's process for a run. A step that retries has several attempts; each has its own logs and result. An interrupted attempt is not counted as a retry.
Related: Step, Run, Resume Docs: Retry policy
Built-in step
A step the factory ships and lists as builtin: <name> in kusaw.yaml. You keep it, drop it, or point the same pipeline slot at a custom command step. To the pipeline, a built-in and a command you added look the same.
Related: Step, Custom command step, Pipeline Docs: Step
Capability
A named permission or feature a provider can offer a step, such as read-only, edit, or resume. The factory records the level for each pair (enforced, guarded, partial, or not supported) and refuses a step that needs something the provider cannot do.
Related: Provider, Preset, Step Docs: Providers
Checkpoint
A saved git ref the run can return to. The first start records the base commit; a gate checkpoints before waiting. Resume and requeue use the checkpoint rather than your working tree.
Related: Run, Resume, Requeue Docs: Rerun and steer
Custom command step
A step you write as a program and list with command: in kusaw.yaml. It speaks the same step protocol as a built-in step: handshake, request, events, result. Replacing a built-in keeps gates, loops, and feedback as long as you keep the same step id.
Related: Step, Built-in step, Step protocol Docs: Custom steps
Delivery
The local commit the run leaves you, plus SUMMARY.md. Each repository that passed gets one squashed commit on a shared branch. The factory does not merge, push, or open a pull request.
Related: Run, Worktree, Gate Docs: Delivery
Effect
A typed side effect a step may return for the factory to apply after the result, such as a note on the run. Allowed kinds, apply versus dry-run, and held effects are part of the step protocol. Command effect kinds run in the factory folder, not in a worktree.
Related: Step, Step protocol, Run Docs: Effect applier
Factory
One product's repositories, a pipeline, and the settings that go with them. One factory owns the checkouts that ship together. Separate products belong in separate factories, each with its own queue, budget, and data.
Related: Pipeline, Task, Repo label Docs: Factory
Feedback
Notes and findings a later try of a step or loop can see. A gate reject note, a requeue note, and review findings are feedback. They steer the next attempt; they are not a new task.
Related: Finding, Gate, Requeue Docs: Review and approve
Finally stage
The list of steps that run after the pipeline, including after a failure, so a retro or a scorer can still look at the run. Stopping the run outright skips finally.
Related: Pipeline, Stage, Retro Docs: Pipeline
Finding
One issue a review step reports: a severity, a rule id, a message, and optional file and line. Findings become feedback. Under the default fail_on: major, a minor finding is kept and does not fail the step.
Related: Feedback, Step, Gate Docs: Review and approve
Gate
A place in the pipeline where the run waits for you to approve or reject. Approve continues at the next step. Reject needs a note, which becomes feedback when the gate sits in a loop that still has tries. A gate is not a merge and not a push.
Related: Pipeline, Run, Feedback Docs: Gates
Grill
The interactive intake interview. Grill runs as a preset interview with your configured Claude Code, asks about the idea, and helps grow a task file. It is not a pipeline step on an unattended run.
Related: Intake, Preset, Task Docs: Claude Code CLI surface
Inbox
A folder trigger that queues a task file while kusaw serve runs. Dropping a spec in the inbox is the same add as kusaw add, without typing the command.
Related: Trigger, Task, Intake Docs: Factories
Intake
The interactive path you use when you are still writing the task. Grill is the interview. Adding a file with kusaw add skips intake and starts at the pipeline. Triage can group idea files first.
Related: Grill, Task, Pipeline, Triage Docs: Your first run
Needs attention
A run ending that needs a person: a loop that gave up, a rejected gate with no tries left, or a partial delivery. The worktree is kept. You requeue, resume, restart, dismiss, or take over.
Related: Run, Requeue, Delivery Docs: Run
Parallel group
Several steps that run together in the pipeline, then join. You choose whether the group stops at the first failure or lets every member finish.
Related: Pipeline, Step, Stage Docs: Pipeline
Pipeline
The order of steps a run walks through, written in the factory. Around a simple list sit loops, parallel groups, gates, and a finally stage. One factory, one pipeline.
Related: Step, Run, Stage Docs: Pipeline
Preset
A named permission shape the runner gives an agent step: edit, read_only, or interview. Built-ins pick a preset; a custom command step can print the same argv with kusaw agent-args --preset (kusaw claude-args is an alias for Claude Code).
Related: Capability, Provider, Grill Docs: Claude Code CLI surface
Proposal
A drafted factory change from retro: a scalar in kusaw.yaml, a step's instructions file, or a file in a declared skill folder. A person approves each proposal. It does not edit repository code.
Related: Retro, Factory, Scorer Docs: Measure and improve
Provider
The agent CLI a step runs, such as claude-code or cursor. The factory default is top-level provider; a step can override it. Intake stays on Claude Code in this version.
Related: Capability, Preset, Step Docs: Providers
Repo label
The short name of one checkout in kusaw.yaml, such as app or api. A task lists the labels it touches. Steps see those labels on repos[] in the step protocol.
Related: Factory, Task, Worktree Docs: Multi-repo runs
Requeue
Start a new run of the same task from the last checkpoint, on a new branch, with your note as feedback. The current run is dismissed when it was needs attention. Requeue is not resume and not restart.
Related: Resume, Restart, Run Docs: Rerun and steer
Restart
Rerun every repository of a finished run from its base commits. Earlier tips are kept aside. The run id stays the same. Restart is not requeue and not resume.
Related: Resume, Requeue, Checkpoint Docs: Rerun and steer
Resume
Continue the same run: unpause the queue, rerun failed repos with --failed-only, or continue a provider session. Resume is not restart and not requeue. kusaw resume with no run id still only unpauses the queue.
Related: Restart, Requeue, Run Docs: Rerun and steer
Retro
A finally stage step that reads a finished run and may draft proposals to improve the factory. A person approves each proposal. Retro does not edit the repository.
Related: Proposal, Finally stage, Scorer Docs: Measure and improve
Run
One task going through the pipeline, in a worktree so your checkout stays still. The same task can have more than one run. Requeue starts the next run; resume and restart continue this one.
Related: Task, Pipeline, Worktree Docs: Run
Sandbox
Isolation around a step process: what it can read, write, and reach on the network. Optional OS-native containment (Seatbelt on macOS, Bubblewrap on Linux and WSL2) wraps agent and custom steps when sandbox.mode is required. The network stays open. Native Windows has no backend.
Related: Step, Worktree, Capability Docs: What a step can reach
Scorer
A finally stage judge that scores a finished run. Sampling is fixed from the run id and the scorer name. Cost is charged to the finally allowance. Scorers stay opt-in until you add a score step.
Related: Finally stage, Retro, Run Docs: Measure and improve
Spec
The task Markdown file: title, what to change, and how to check it. kusaw add checks the structure and queues a run. The spec is the contract for that run, not a note to yourself.
Related: Task, Run, Intake Docs: Write a good task
Stage
A named stretch of the pipeline: a loop, a parallel group, a gate, or the finally stage. Events and status talk about stage transitions. A stage is not a step; a stage contains steps.
Related: Pipeline, Step, Finally stage Docs: Pipeline
Step
One program that does one job on the run's worktree. The pipeline is those jobs in order. A step may be a built-in step or a custom command step. Retries are per step; each try is an attempt.
Related: Pipeline, Attempt, Built-in step Docs: Step
Step protocol
The contract a step process speaks with the factory: handshake, request, events, and result. Protocol v2 is additive. Custom steps read the same request a built-in sees, including repos[].glossary_path.
Related: Step, Custom command step, Effect Docs: Step protocol
Task
The Markdown file you add: a title, what to change, and how to check it. A run is that task going through the pipeline. One task can name several repo labels.
Related: Spec, Run, Factory Docs: Task
Triage
Group raw idea files by shared root cause and assign a role before intake. kusaw triage runs in the CLI; nothing is queued until you start intake from an item or group.
Related: Intake, Task, Grill Docs: CLI
Trigger
Something that queues a task while serve runs: a schedule or an inbox folder. Triggers do not start a run by themselves; they add the spec the same way kusaw add does.
Related: Inbox, Task, Factory Docs: Factories
Worktree
A separate copy of a repo for one run, taken from the base branch. Steps edit the copy, not your checkout. The factory removes the copy when the run no longer needs you; the branch stays.
Related: Run, Repo label, Delivery Docs: Run
Delivery
[Delivery](../glossary.md#delivery) is a local commit per repo and a `SUMMARY.md`; you merge and push.
Write a good task
A [task](../glossary.md#task) is one Markdown file — the [spec](../glossary.md#spec) `kusaw add` checks and queues as a run. Write one change per task, with commands under `## Verification` that prove it worked.