diff --git a/.pi/orksorksorks/alanvardy-var-1037-add-a-readme/done.md b/.pi/orksorksorks/alanvardy-var-1037-add-a-readme/done.md new file mode 100644 index 0000000..85f85f1 --- /dev/null +++ b/.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. \ No newline at end of file diff --git a/.pi/orksorksorks/alanvardy-var-1037-add-a-readme/small.md b/.pi/orksorksorks/alanvardy-var-1037-add-a-readme/small.md new file mode 100644 index 0000000..d80c5d5 --- /dev/null +++ b/.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//`. +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 \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..de768d9 --- /dev/null +++ b/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 `; `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//` (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//`) | +| `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: +.