Quickstart

Install Komputa Practice, then make one small, verified change in the sample repo.

This tutorial is for an engineer who uses Claude Code and has not used the practice yet. You install the practice on your machine. Then you make one small change in a sample Python repo, and you see each layer of the quality funnel catch what it can. It takes about 30 minutes.

Before you start

You need these tools:

Tool	What it is for
Claude Code	The agent that does the work.
pstack for Claude Code	The playbooks and the model for each role.
Linux with `bash`, `git` and `jq`	The hooks are Bash scripts and read their input with `jq`.
`uv`	Runs the Python tools of the sample repo.
`gh`, signed in	Makes your copy of the sample repo and opens its pull request.

Both repos are private for now. Ask your team for access to komputa-io/komputa-practice and komputa-io/komputa-practice-sample.

You do not need herdr for this tutorial.

Install the practice

You link the practice to one clone of its repo, so a git pull later updates the rules and the skills at once.

Install pstack. Follow the README of the Claude Code port. Then run this in Claude Code:
```
/pstack:setup-pstack
```
It writes ~/.claude/pstack-models.md, which sets the model for each role.

Clone the practice to a fixed path. The next steps name this path.

git clone https://github.com/komputa-io/komputa-practice.git ~/Code/komputa-practice

Link the skills into Claude Code:

mkdir -p ~/.claude/skills
for s in ~/Code/komputa-practice/skills/*/; do
  ln -s "$s" ~/.claude/skills/
done

Import the working rules into your global CLAUDE.md:
```
echo '@~/Code/komputa-practice/rules/working-rules.md' >> ~/.claude/CLAUDE.md
```
The rules talk about “the operator”. Add one line to ~/.claude/CLAUDE.md that says the operator is you.

Copy the guard hooks and register them. Run this once; a second run adds the entries again.

mkdir -p ~/.claude/hooks
cd ~/Code/komputa-practice/hooks
cp $(jq -r '.PreToolUse[].hooks[].command | sub("^~/.claude/hooks/"; "")' gates.json) \
  block-test-weakening.py ~/.claude/hooks/
settings=~/.claude/settings.json
[ -f "$settings" ] || echo '{}' > "$settings"
jq --slurpfile g gates.json \
  '.hooks.PreToolUse = ((.hooks.PreToolUse // []) + $g[0].PreToolUse)' \
  "$settings" > "$settings.new" && mv "$settings.new" "$settings"

The hooks are copies, not links. After a git pull that changes hooks/, copy them again.

Check the install

Check that each registered hook matches its copy in the repo:

~/Code/komputa-practice/hooks/check-live.sh

You see one line for each of the six hooks, and the exit code is 0:

in step: block-credential-read.sh
in step: block-dangerous-git.sh
in step: block-destructive-delete.sh
in step: block-operator-screen.sh
in step: block-secret-write.sh
in step: block-test-weakening.sh

Check that a hook refuses what it must. Send the git hook a forced push:
```
jq -nc '{tool_name:"Bash",tool_input:{command:"git push --force origin main"}}' \
  | ~/.claude/hooks/block-dangerous-git.sh; echo "exit $?"
```
The hook prints a line that starts with BLOCKED: and gives the one forced push it allows. The exit code is 2.
Check that a skill links back to your clone:
```
readlink -f ~/.claude/skills/house-python/SKILL.md
```
The path is inside ~/Code/komputa-practice.

Make your own copy of the sample repo

The sample repo is a small Python invoice library made from the practice’s project template. It has one domain rule: a line’s quantity is at least 1, and its price is never negative. CI runs the gate on each pull request.

Make your own copy and clone it:

gh repo create my-practice-sample --private --clone \
  --template komputa-io/komputa-practice-sample
cd my-practice-sample

Switch on the repo’s git hooks. The commit hook runs the fast gate.
```
git config core.hooksPath .githooks
```
Run the full gate once:
```
scripts/gate.sh --full
```
It formats, lints, type-checks and runs the tests. The last line is:
```
gate: every check passed
```

Make your first change

Start Claude Code in the repo:
```
claude
```
First, see a hook refuse a command. Give the agent this prompt:
```
Run git push --force origin main.
```
The git hook refuses the command before it runs, and the agent tells you why. If the push runs, the hooks are not registered: go back to Check the install. (You have changed nothing yet, so a push that ran would only send the same commit again.)

Now ask for a feature. Give the agent this prompt:

Add a discount to the invoice: a whole-number percentage from 0 to 100 that
comes off the total. Round the discount to the nearest penny in the
customer's favour. Open a pull request when it is done.

Watch what the agent does. The working rules make it:
- Put the work in a tier. A discount changes behaviour that a user sees, so it is a feature (tier 2).
- Write a short plan: one paragraph with the acceptance checks, and the risks. Money is a risk.
- Write the tests for the new domain rules: the percentage range and the rounding.
- Run the gate until it passes.
- Ask a verifier subagent, which did not write the change, to run the acceptance checks and read the diff.
- Open the pull request, and report the commands it ran and what they printed.
Read the report, check that CI passed on the pull request, and merge it. The agent asks you before it merges, unless your own CLAUDE.md lets it merge.

What you just saw

Each step was one layer of the quality funnel:

What happened	Funnel layer
`new_line` returns an `InvalidLine` instead of a bad line, so code that skips the check does not type-check.	1. Codebase
The gate (format, lint, types, tests) and the git hook refused mistakes with nobody watching.	2. Static analysis
The verifier ran the acceptance checks on the real code.	3. Verification
The working rules set the tier, the plan and the test budget.	4. Prose
You decided to merge.	5. Human review

Next steps

How it fits: where the rules, the hooks and the template live, and how a rule changes.
The quality funnel: why each mistake is caught at the highest layer that can hold it.
The rules: the working rules that the agent followed.