Your first run

This walkthrough takes about fifteen minutes. Examples use the label demo and <path> placeholders; they do not use real names.

A real run starts your configured Claude Code, which uses your account and plan. The sample task is small. Intake, when you use it, starts with grill.

1. Make a sample repoCopy Anchor Link

Create a folder demo-app with one shell script and a test, then commit it. These commands only need git and a shell.

mkdir demo-app
cat > demo-app/hello.sh <<'EOF'
#!/bin/sh
echo hello
EOF
cat > demo-app/hello_test.sh <<'EOF'
#!/bin/sh
set -eu
got=$(sh hello.sh)
test "$got" = "hello"
EOF
chmod +x demo-app/hello.sh demo-app/hello_test.sh
git -C demo-app init -b main
git -C demo-app add hello.sh hello_test.sh
git -C demo-app -c user.name=demo -c user.email=demo@localhost commit -m "Initial commit"
( cd demo-app && sh hello_test.sh )

<path> in the next step is this demo-app folder.

2. Create a factoryCopy Anchor Link

kusaw new demo --repo app=<path>
kusaw validate --factory demo

kusaw new writes kusaw.yaml and registers the factory. kusaw validate --factory demo checks that config.

3. Start the factory and the DashboardCopy Anchor Link

kusaw serve --factory demo

kusaw ui --open --factory demo

kusaw serve is the worker. kusaw ui --open is the Dashboard at 127.0.0.1. Leave serve running while you add the task.

4. Write a task and add itCopy Anchor Link

A task is a short Markdown file: a title, what to change, and a ## Verification section with the test command. Save this as hello.md:

cat > hello.md <<'EOF'
---
id: demo-hello
title: Print hello, world
repos: [app]
---

## Goal

Make `hello.sh` print `hello, world`.

## Scope

The hello script and its test.

## Acceptance criteria

- [ ] `sh hello.sh` prints `hello, world`.

## Verification

- `sh hello_test.sh`

## Out of scope

Other files.
EOF
kusaw add hello.md --factory demo

kusaw add checks the spec and queues a run.

5. Watch itCopy Anchor Link

kusaw status --factory demo

The same run is on the run page in the Dashboard.

6. Review and approveCopy Anchor Link

If the pipeline has a gate, the run waits at waiting_for_human. Approve it with kusaw approve <run> or the Dashboard button. The default pipeline has no gate, so a first run does not stop for approval.

7. Stop the factoryCopy Anchor Link

Stop the factory with Ctrl-C in the terminal running kusaw serve.

When the run has finished, what success looks like is how to read the result.