From c9c45fc704c94006e20507d56e8ceec015bfeede Mon Sep 17 00:00:00 2001 From: owkwo-bot Date: Sat, 1 Aug 2026 04:35:38 +0200 Subject: [PATCH 1/3] docs: add task breakdown for issue #39 Written during map-issue-to-tasks but not yet committed. Co-Authored-By: WOZCODE --- ...e-adopt-repo-standard-stage-in-progress.md | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md diff --git a/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md b/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md new file mode 100644 index 0000000..0921ac3 --- /dev/null +++ b/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md @@ -0,0 +1,118 @@ +# Tasks: Issue #39 — chore: adopt repo-standard (stage=in-progress) + +Source: https://github.com/rsenna/guiltty/issues/39 +Enrichment: issue comment on #39. + +Quality gate: none of these tasks touch Rust source, so the usual `cargo fmt`/`clippy`/`llvm-cov` gate doesn't apply. "Verify" below is doc/structure inspection instead. + +This issue brings `guiltty` up to the `in-progress` tier of the cross-repo +doc/folder standard ([`2026-08-01-repo-standard-design.md`](https://github.com/rsenna/rs-claude-plugins/blob/main/docs/superpowers/specs/2026-08-01-repo-standard-design.md)). +It is pure scaffolding: no existing `docs/*.md` content moves, no Rust code +changes, no CI changes. + +Sequencing: **T1 and T3 are independent** and can happen in any order or in +parallel. **T2 benefits from T1** (an `AGENTS.md` written after `repo.toml` +already declares the stage can reference it) but doesn't hard-depend on it. +**T4 is the largest task and independent of T1–T3** at the file level, but +do it last since it's the one most likely to surface an open question (tool +dependencies in `.specify/scripts/`) worth resolving with the smaller tasks +already landed. + +--- + +- [ ] **T1 — Declare `stage = "in-progress"` in `repo.toml`** + +Acceptance: +- `repo.toml` gains a `stage = "in-progress"` line, matching the design + doc's four valid values (`prototype | in-progress | released | archived`). +- No other `repo.toml` fields change. + +Verify: +- `cat repo.toml` shows the new line; the file otherwise diffs to nothing + else. + +Files: `repo.toml` + +Dependencies: none. + +--- + +- [ ] **T2 — Create `AGENTS.md`** + +Acceptance: +- `AGENTS.md` exists at repo root, in the design doc's "in-progress" style: + what's actually implemented today (reality-check, not aspirational — + mirror `README.md`'s existing DONE/IN PROGRESS/NOT STARTED status list, + don't restate `docs/spec.md`'s forward-looking Success Criteria as if + already done), decided rules/conventions (the Always/Ask first/Never list + already in `docs/spec.md`'s Code Style section, restated or linked), dev + commands (`docs/spec.md`'s Commands block: build/test/lint/format/run + example), and a "where things live" map (workspace crate layout — mirror + `docs/spec.md`'s Project Structure section). +- Links out to `docs/spec.md`, `docs/spec-ci.md`, `docs/spec-kitty-e2e.md`, + and `docs/design/*.md` rather than duplicating their content — follow + iklo's `AGENTS.md` pattern (a short hub page pointing at the real sources) + rather than inlining everything. + +Verify: +- Read `AGENTS.md` against `docs/spec.md` and the current crate tree; every + "implemented" claim must match what's actually in `crates/*/src/lib.rs` + today (same discipline as issue #16/T1's README fix). + +Files: `AGENTS.md` (new) + +Dependencies: none (T1 is a soft dependency only — natural to land first +since `AGENTS.md` can reference the now-declared stage, not a hard block). + +--- + +- [ ] **T3 — Create `specs/` and `specs/decisions/`** + +Acceptance: +- `specs/` and `specs/decisions/` both exist, empty except for a `.gitkeep` + each (git doesn't track empty directories). +- No existing `docs/spec*.md` or `docs/design/*.md` content is moved into + either directory — see this issue's Non-goals. + +Verify: +- `git status` after `git add` shows both new, empty (`.gitkeep`-only) + directories tracked. + +Files: `specs/.gitkeep` (new), `specs/decisions/.gitkeep` (new) + +Dependencies: none. + +--- + +- [ ] **T4 — Bootstrap `.specify/` from the iklo reference implementation** + +Acceptance: +- `.specify/` exists with the same directory shape as + `~/REPO/ME/iklo/.specify/`: `memory/`, `templates/`, `scripts/bash/`, + `workflows/`, `integrations/`. +- `templates/`, `scripts/bash/`, `workflows/`, `integrations/` copy over + verbatim (project-agnostic spec-kit tooling — no guiltty-specific content + to adapt there). +- `.specify/memory/constitution.md` is **authored for guiltty**, not a + copy-with-title-changed: restate `docs/spec.md`'s Code Style + Always/Ask-first/Never rules as constitution articles (e.g. "backend + concerns never leak into `guiltty-core`", "ask first before a new external + dependency or backend crate", "never panic on a recoverable error path in + public API"), in the same spirit as iklo's constitution (principles that + govern every spec/plan/task, amendments via an ADR under + `specs/decisions/`) but with guiltty's own content, not iklo's. +- Before treating this done, skim `.specify/scripts/bash/*.sh` for any tool + dependency (e.g. `jq`) not already covered by `mise.toml`; if one exists, + either add it to `mise.toml` as part of this task or note it explicitly as + a follow-up (see this issue's Open questions) — don't silently ship + scripts that fail on a clean checkout. + +Verify: +- `diff -rq ~/REPO/ME/iklo/.specify/{templates,scripts,workflows,integrations} .specify/` shows no content differences for the copied, project-agnostic parts. +- Read `.specify/memory/constitution.md` end to end and confirm every + article is genuinely about guiltty (no leftover "Iklo", "kebab-case + identifiers", substrate/REPL language, or other iklo-specific content). + +Files: `.specify/` (new tree — `memory/constitution.md`, `templates/*`, `scripts/bash/*`, `workflows/*`, `integrations/*`) + +Dependencies: none at the file level; do last per the sequencing note above. From 90e48371698f7aaef22f0e38a75c40124243005a Mon Sep 17 00:00:00 2001 From: owkwo-bot Date: Sat, 1 Aug 2026 04:40:41 +0200 Subject: [PATCH 2/3] docs: fix section reference in issue #39 task breakdown The Always/Ask first/Never list is docs/spec.md's Boundaries section, not Code Style -- caught by pr-review-toolkit:review-pr. Co-Authored-By: WOZCODE --- tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md b/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md index 0921ac3..73c450f 100644 --- a/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md +++ b/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md @@ -45,7 +45,7 @@ Acceptance: mirror `README.md`'s existing DONE/IN PROGRESS/NOT STARTED status list, don't restate `docs/spec.md`'s forward-looking Success Criteria as if already done), decided rules/conventions (the Always/Ask first/Never list - already in `docs/spec.md`'s Code Style section, restated or linked), dev + already in `docs/spec.md`'s Boundaries section, restated or linked), dev commands (`docs/spec.md`'s Commands block: build/test/lint/format/run example), and a "where things live" map (workspace crate layout — mirror `docs/spec.md`'s Project Structure section). @@ -94,7 +94,7 @@ Acceptance: verbatim (project-agnostic spec-kit tooling — no guiltty-specific content to adapt there). - `.specify/memory/constitution.md` is **authored for guiltty**, not a - copy-with-title-changed: restate `docs/spec.md`'s Code Style + copy-with-title-changed: restate `docs/spec.md`'s Boundaries Always/Ask-first/Never rules as constitution articles (e.g. "backend concerns never leak into `guiltty-core`", "ask first before a new external dependency or backend crate", "never panic on a recoverable error path in From 1686a6b2daf004b1b5eef5df9d1309d611262ee6 Mon Sep 17 00:00:00 2001 From: owkwo-bot Date: Sat, 1 Aug 2026 16:03:54 +0200 Subject: [PATCH 3/3] docs: fix bot-flagged issues in issue #39 task breakdown - T1 Verify: cat repo.toml didn't prove nothing else changed; use git diff repo.toml instead. - T2: docs/design/*.md doesn't resolve as a real Markdown link; list the three actual files. Broaden T2's Verify beyond crates/*/src/lib.rs since AGENTS.md will also claim things about dev commands, workspace layout, and doc links that lib.rs alone can't confirm. - T3 Verify: git tracks files, not empty directories; reworded to what git status actually shows (the two .gitkeep files). - T4: the diff -rq command with brace expansion passes four source operands plus one dest operand, which diff can't accept -- replaced with a per-directory loop. Softened the hardcoded ~/REPO/ME/iklo path reference (maintainer's own layout; clone rsenna/iklo temporarily otherwise). Declared T3 as T4's soft dependency (constitution content references specs/decisions/, which T3 creates) and added mise.toml as a conditional Files entry. Fixed a small typo. Independently re-verified via pr-review-toolkit:review-pr before pushing -- all fixes confirmed correct, one dash-style nit also fixed. Co-Authored-By: WOZCODE --- ...e-adopt-repo-standard-stage-in-progress.md | 73 +++++++++++++------ 1 file changed, 50 insertions(+), 23 deletions(-) diff --git a/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md b/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md index 73c450f..774a3e8 100644 --- a/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md +++ b/tasks/issue-39-chore-adopt-repo-standard-stage-in-progress.md @@ -13,10 +13,11 @@ changes, no CI changes. Sequencing: **T1 and T3 are independent** and can happen in any order or in parallel. **T2 benefits from T1** (an `AGENTS.md` written after `repo.toml` already declares the stage can reference it) but doesn't hard-depend on it. -**T4 is the largest task and independent of T1–T3** at the file level, but -do it last since it's the one most likely to surface an open question (tool -dependencies in `.specify/scripts/`) worth resolving with the smaller tasks -already landed. +**T4 is the largest task**; it has no hard dependency on T1–T3 at the file +level, but soft-depends on T3 (its constitution content references +`specs/decisions/`) and should come last anyway since it's the one most +likely to surface an open question (tool dependencies in +`.specify/scripts/`) worth resolving with the smaller tasks already landed. --- @@ -28,8 +29,8 @@ Acceptance: - No other `repo.toml` fields change. Verify: -- `cat repo.toml` shows the new line; the file otherwise diffs to nothing - else. +- `git diff repo.toml` shows only the added `stage = "in-progress"` line — + proves nothing else in the file changed, which `cat` alone can't. Files: `repo.toml` @@ -50,14 +51,21 @@ Acceptance: example), and a "where things live" map (workspace crate layout — mirror `docs/spec.md`'s Project Structure section). - Links out to `docs/spec.md`, `docs/spec-ci.md`, `docs/spec-kitty-e2e.md`, - and `docs/design/*.md` rather than duplicating their content — follow + and each current `docs/design/` doc individually -- + `docs/design/sprite-crate-extraction.md`, `docs/design/turtle-geometry.md`, + `docs/design/viewport-regions-zoom-scroll.md` (not a `docs/design/*.md` + glob, which doesn't resolve as an actual Markdown link) — rather than + duplicating their content — follow iklo's `AGENTS.md` pattern (a short hub page pointing at the real sources) rather than inlining everything. Verify: -- Read `AGENTS.md` against `docs/spec.md` and the current crate tree; every - "implemented" claim must match what's actually in `crates/*/src/lib.rs` - today (same discipline as issue #16/T1's README fix). +- Read `AGENTS.md` against `docs/spec.md`, the workspace manifests + (`Cargo.toml` files), and the current crate/example/test tree; every + "implemented" claim must match what's actually there today — checking + only `crates/*/src/lib.rs` isn't enough to verify dev-command, workspace- + layout, or doc-link claims too (same discipline as issue #16/T1's README + fix). Files: `AGENTS.md` (new) @@ -75,8 +83,10 @@ Acceptance: either directory — see this issue's Non-goals. Verify: -- `git status` after `git add` shows both new, empty (`.gitkeep`-only) - directories tracked. +- `git status` after `git add` lists `specs/.gitkeep` and + `specs/decisions/.gitkeep` as new files (git tracks files, not empty + directories, so this is what actually confirms both directories exist and + are tracked). Files: `specs/.gitkeep` (new), `specs/decisions/.gitkeep` (new) @@ -87,9 +97,13 @@ Dependencies: none. - [ ] **T4 — Bootstrap `.specify/` from the iklo reference implementation** Acceptance: -- `.specify/` exists with the same directory shape as - `~/REPO/ME/iklo/.specify/`: `memory/`, `templates/`, `scripts/bash/`, - `workflows/`, `integrations/`. +- `.specify/` exists with the same directory shape as the design doc's named + reference implementation, `rsenna/iklo`'s own `.specify/` tree: `memory/`, + `templates/`, `scripts/bash/`, `workflows/`, `integrations/`. (Written + assuming a local `~/REPO/ME/iklo` checkout, since that's this issue's own + wording and the maintainer's actual dev-machine layout; whoever implements + this without that checkout should clone `rsenna/iklo` temporarily instead — + there's no portable fetch mechanism for it beyond that.) - `templates/`, `scripts/bash/`, `workflows/`, `integrations/` copy over verbatim (project-agnostic spec-kit tooling — no guiltty-specific content to adapt there). @@ -101,18 +115,31 @@ Acceptance: public API"), in the same spirit as iklo's constitution (principles that govern every spec/plan/task, amendments via an ADR under `specs/decisions/`) but with guiltty's own content, not iklo's. -- Before treating this done, skim `.specify/scripts/bash/*.sh` for any tool - dependency (e.g. `jq`) not already covered by `mise.toml`; if one exists, - either add it to `mise.toml` as part of this task or note it explicitly as - a follow-up (see this issue's Open questions) — don't silently ship - scripts that fail on a clean checkout. +- Before treating this as done, skim `.specify/scripts/bash/*.sh` for any + tool dependency (e.g. `jq`) not already covered by `mise.toml`; if one + exists, either add it to `mise.toml` as part of this task or note it + explicitly as a follow-up (see this issue's Open questions) — don't + silently ship scripts that fail on a clean checkout. Verify: -- `diff -rq ~/REPO/ME/iklo/.specify/{templates,scripts,workflows,integrations} .specify/` shows no content differences for the copied, project-agnostic parts. +- Per-directory diffs, not one combined `diff -rq` call (brace expansion + turns `{templates,scripts,workflows,integrations}` into four separate + path arguments, which `diff` can't take alongside a fifth `.specify/` + operand): + ```bash + for d in templates scripts workflows integrations; do + diff -rq ~/REPO/ME/iklo/.specify/"$d" .specify/"$d" + done + ``` + Each call should show no content differences for that copied, + project-agnostic directory. - Read `.specify/memory/constitution.md` end to end and confirm every article is genuinely about guiltty (no leftover "Iklo", "kebab-case identifiers", substrate/REPL language, or other iklo-specific content). -Files: `.specify/` (new tree — `memory/constitution.md`, `templates/*`, `scripts/bash/*`, `workflows/*`, `integrations/*`) +Files: `.specify/` (new tree — `memory/constitution.md`, `templates/*`, `scripts/bash/*`, `workflows/*`, `integrations/*`); `mise.toml` (conditional — only if the tool-dependency skim above finds something missing) -Dependencies: none at the file level; do last per the sequencing note above. +Dependencies: none at the file level; T3 is a soft dependency (the +constitution's own text points ADR amendments at `specs/decisions/`, which +T3 creates, so land T3 first even though nothing here hard-requires it). +Do last per the sequencing note above regardless.