Add a README

.pi/orksorksorks/alanvardy-var-1037-add-a-readme/done.md

@@ -0,0 +1,7 @@
+# Done
+
+- **What was built**: `README.md` at the repo root for the orksorksorks Rust CLI — purpose/subcommand table, honest non-goals (never writes artifacts, never executes scripts, never calls LLM/network APIs, requires a git branch unless `--step` overrides), installation via `scripts/install.sh` + `init`, where the config lives, a minimal `orksorksorks.toml` example (byte-identical to the `template_commented_examples_validate` example in `templates/default.toml`, `version = "0.1.0"` == `CONFIG_VERSION`), JSON output, and license. Also deleted the tracked `DELETEME` bootstrap marker so it never reaches main.
+- **Commit SHA(s)**: `fdbb401` ("docs: add README.md" — implementation), `e2deddd` ("docs: qualify config validation and frontmatter caveats" — review fixes), both pushed to `origin/alanvardy-var-1037-add-a-readme` (draft PR #34).
+- **Verification**: `bash scripts/test.sh` green — cargo fmt, cargo check, clippy (zero warnings), 197/197 nextest tests passed, TODO/FIXME marker gate passed. Run twice (after implementation and after review fixes).
+- **Reviewer findings**: no blockers. Three P2 nits, all fixed: (1) `config:duplicate-name`/`config:empty-name` only apply to steps/models/prompts, not scripts — wording qualified; (2) the `prompt` still-touches-git caveat is conditional on `show_frontmatter` — documented; (3) missing trailing newline — added.
+- **Remaining manual items**: none code-wise. The deliverable targets draft PR #34 (already open on this branch, auto-updated). If a changelog entry is ever wanted, there is no `CHANGELOG.md` in the repo — the repo does not currently maintain one, so none was added per the ticket's conditional wording.

.pi/orksorksorks/alanvardy-var-1037-add-a-readme/small.md

@@ -0,0 +1,24 @@
+# Task
+
+Write a `README.md` at the repo root for **orksorksorks** (a Rust CLI, binary-only crate; no README currently exists — a draft PR #34 already targets this same deliverable).
+
+The README must cover, per the ticket:
+
+1. **Purpose of the project** — what orksorksorks is and does. Ground it in the actual source: it is a Rust CLI (`src/main.rs`, `src/commands/mod.rs`) whose subcommands are `init`, `branch`, `artifact_directory`, `step`, `model`, `thinking`, `prompt`, and `script`; it reads a `workspaces.toml`-style config — actually `orksorksorks.toml` — that defines "workspaces" (named config blocks), drives step prompts/config for coding agents, and stores artifacts under `.pi/orksorksorks/<branch>/`.
+2. **What it does not do** — be honest about non-goals (it is not a general-purpose agent, not a build tool, etc. — check the help text/CLI source for what is deliberately out of scope).
+3. **Installation** — the repo ships `scripts/install.sh`, which does `cargo install --path . --locked` into `~/.cargo/bin`. Cover prerequisites (Rust toolchain; see `rust-toolchain.toml`) and the `init` subcommand which writes a commented `templates/default.toml` config.
+4. **A basic `orksorksorks.toml`** — a worked minimal example derived from `templates/default.toml` and the `src/config.rs` schema: `version = "0.1.0"` (must equal `CONFIG_VERSION`), and one workspace block with `name`, `model`, prompt etc. as the schema and default template define; keep it consistent with what `init` actually generates.
+
+Also follow repo conventions: user-visible changes go in `CHANGELOG.md` under `[Unreleased]` (only if the repo deems a README-add a changelog entry — check existing CHANGELOG policy; there may be no CHANGELOG file yet), and the local gate `scripts/test.sh` must pass (it checks CI-adjacent markers in `*.rs` only, so a pure docs change should not affect it). Do not run `cargo` unless needed to verify facts. A draft PR (#34) for this branch already exists — reconcile with its content rather than duplicating or clobbering it.
+
+## Why SMALL
+
+Single new file at repo root following the standard README pattern; no unknowns (ticket enumerates the exact sections), no schema/migration, no new subsystem or shared/convention code, no design decision, and no test surface — criteria A–F all hold. No LARGE or breadth triggers apply.
+
+## Key files (if the recon found any)
+
+- `README.md` — not yet present, to be created at repo root
+- `scripts/install.sh` — the documented install path
+- `templates/default.toml` — source for the basic config example
+- `src/config.rs` + `src/commands/mod.rs` — ground the CLI surface and schema descriptions in what the code actually does
+- Existing draft PR #34 (attachment on VAR-1037) — reconcile with in-flight content

README.md

@@ -0,0 +1,164 @@
+# orksorksorks
+
+A small Rust CLI that drives step-based conventions for coding-agent
+workflows. It reads an `orksorksorks.toml` config that declares a workflow's
+steps, the model and prompt for each step, and optional scripts, then answers
+"which step am I on?" from the files present in the artifact directory and
+prints the step's prompt, model, or thinking budget on demand.
+
+The name is not a typo: it is a Warhammer reference to Orks shouting
+"Orks Orks Orks", and a tongue-in-cheek comparison with coding agents —
+individually a little dumb, but more powerful in larger numbers. Worth
+spelling carefully: artifacts live under `.pi/orksorksorks/`, and a
+`orksworksorks` misspelling would mis-create `.pi/orksworksorks/`
+parents.
+
+## What it is
+
+- **Binary-only Rust CLI** (no library target; Rust 2024 edition). Run it as
+  `orksorksorks <subcommand>`; `orksorksorks --help` lists everything.
+- **Reads one TOML config**: `orksorksorks.toml`, validated against a strict
+  schema (unknown keys are rejected).
+- **Step-based workflows**: a config declares named `[[steps]]`, each gated on
+  a *trigger artifact* — the current step is the last step whose trigger file
+  exists in the artifact directory. A step with an empty `trigger_artifact`
+  is the default fallback when nothing has matched yet (at most one allowed).
+- **Artifact directory**: `$PWD/.pi/orksorksorks/<branch>/` (slashes in the
+  branch name become `-`). The `artifact_directory` subcommand prints this
+  path; steps are derived from it.
+- **Coding-agent plumbing**: `prompt` prints the current step's prompt text,
+  prefixed by an `## Important variables` frontmatter block (step, branch,
+  artifact directory) that tells the agent where to write its artifacts —
+  `show_frontmatter = false` in the config suppresses the prefix. `model` and
+  `thinking` print the configured model and reasoning budget; `script` prints
+  the raw script text.
+
+### Subcommands
+
+| Subcommand        | What it prints                                       |
+| ----------------- | ---------------------------------------------------- |
+| `init`            | Writes a commented `orksorksorks.toml` template; refuses to overwrite an existing file |
+| `branch`          | The current git branch |
+| `artifact_directory` | The artifact directory path (`cwd/.pi/orksorksorks/<branch>/`) |
+| `step`            | The current step name (derived from trigger artifacts, or `--step NAME`) |
+| `model`           | The model for the current step |
+| `thinking`        | The thinking budget for the current step |
+| `prompt`          | The current step's prompt, with frontmatter unless disabled |
+| `script`          | The current step's raw script content (positional `STEP_NAME`) |
+
+`step`, `model`, `thinking`, and `prompt` take `--config PATH` and
+`--step NAME`; `script` takes a positional step name and `--config PATH`.
+`-j`/`--json` is a global flag for JSON output.
+
+## What it does not do
+
+- **It never creates the artifact directory or writes artifacts.** The
+  `artifact_directory` command only prints the path — no directory is
+  created — and step derivation only *checks existence* of trigger files.
+  Agents and scripts are responsible for producing the artifacts.
+- **It never executes scripts.** `script` prints raw content from the config
+  ("meant to be run/piped"); orksorksorks never runs it, and it never shells
+  out to the declared scripts.
+- **It never edits files.** The only write is `init` creating the config file
+  you asked it to create.
+- **It never calls an LLM or any network API.** `model`/`thinking` return the
+  strings configured in TOML; the crate has no networking code.
+- **It is not a general-purpose agent and not a build tool.** It is a
+  thin conventions spine (typed errors, colored output, JSON envelope, TOML
+  config) for resolving *where you are* in a workflow.
+- **It needs a git checkout on a branch** when deriving steps: step
+  derivation and `branch`/`artifact_directory` call `git branch
+  --show-current`, which fails on a detached HEAD. Pass `--step NAME` (or a
+  positional step name to `script`) to skip git for that command — except
+  `prompt`, which still resolves the branch for the frontmatter block unless
+  `show_frontmatter = false`.
+
+## Installation
+
+**Prerequisites**
+
+- Install a Rust toolchain with `rustup` (https://rustup.rs). The repo pins
+  `1.98.1` in `rust-toolchain.toml`, which `rustup` honors automatically.
+
+**Install**
+
+```sh
+scripts/install.sh
+```
+
+This runs `cargo install --path . --locked` and installs the `orksorksorks`
+binary into `~/.cargo/bin` (ensure that directory is on your `PATH`).
+
+**First run**
+
+```sh
+orksorksorks init
+```
+
+writes a fully commented `orksorksorks.toml` (from
+`templates/default.toml`) to your config directory and refuses if the file
+already exists. Point it elsewhere with `-c/--config PATH`.
+
+### Where the config lives
+
+`--config PATH` wins when given. Otherwise the path is resolved from
+environment variables (in order):
+
+1. `$XDG_CONFIG_HOME/orksorksorks.toml` — only when `XDG_CONFIG_HOME` is set
+   to an *absolute* path;
+2. `%APPDATA%\orksorksorks.toml` — Windows;
+3. `$HOME/.config/orksorksorks.toml` — otherwise;
+4. If none of the above resolves, orksorksorks errors with a
+   `config-dir` message saying to set `XDG_CONFIG_HOME` or `HOME`.
+
+## A basic `orksorksorks.toml`
+
+```toml
+version = "0.1.0"
+show_frontmatter = true
+[[steps]]
+name = "example"
+trigger_artifact = "example.md"
+model = "small"
+script = "my_script"
+[[models]]
+name = "small"
+model = "openrouter/example/model"
+thinking = "high"
+[[scripts]]
+name = "my_script"
+content = """
+echo "hello"
+"""
+[[prompts]]
+name = "example"
+content = """
+Your prompt body goes here.
+"""
+```
+
+The `version` field must equal the supported config version, `"0.1.0"`
+(mismatches fail with `config:version`). `show_frontmatter` defaults to
+`true` and controls whether `prompt` prefixes the `## Important variables`
+block. `[[steps]]` are the workflow's phases: `name` must match a
+`[[prompts]]` entry (else `config:missing-prompt`) and `model` must name a
+`[[models]]` entry (else `config:missing-model`). `script` is optional and
+references a `[[scripts]]` entry. Names must be unique
+(`config:duplicate-name`) and non-blank (`config:empty-name`) in the `steps`,
+`models`, and `prompts` sections — script names are not validated — and each
+step needs a non-empty model reference (`config:empty-model`), trigger
+artifacts must be unique across steps (`config:duplicate-trigger`), and at
+most one step may use an empty trigger as the default
+(`config:multiple-default`).
+
+## JSON output
+
+With `-j/--json`, successful commands print `{"data": ...}` and failures
+print `{"error": {"message": ..., "source": ...}}` with exit status 1. The
+`source` is a lowercase tag (`io`, `toml::de`, `config:*`, `git`, …) and the
+`message` is human-readable.
+
+## License
+
+MIT — see `Cargo.toml`. Homepage and repository:
+<https://github.com/alanvardy/orksorksorks>.