Skip to content

Commit 8ed25f9

Browse files
authored
refactor: rename stax plans to stax work-items (#40)
* refactor: rename `stax plans` subcommand to `stax work-items` Rename the artifact noun and CLI surface concept-wide: the `.stax/*.md` files the binary tracks are now called "work items" everywhere. Hard cut; no `stax plans` alias. - CLI: `stax plans <verb>` → `stax work-items <verb>`; usage table, error messages ("unknown work-items subcommand"), and `-h` output all updated. - Go: scope.go → work_items.go (the file was a misnomer — it held the work-item tooling, not anything scope-related). Symbol renames: runPlans, printPlansUsage, planList, lintPlanFile, planRow, planDetail, plansListOverflowThreshold, defaultMaxPlanLines, reviewPerPlan, planFileExt, parsePlan, listPlans, writePlansScaffold, promptMaxPlanLines, et al. → workItem/workItems/WorkItem variants. - On-disk schema: `_config.lock` `max_plan_lines` → `max_work_item_lines`; `review_per` value "plan" → "work-item". Existing files with the old key/value silently fall back to defaults (hard cut, no migration). - HTTP API: `/api/systems?id=` response field `plans` → `workItems`; Go struct `planDetail` → `workItemDetail`. Frontend updated to consume the new key. `/api/scopes` keeps its existing naming. - Frontend: type `Plan` → `WorkItem`; DOM ids `#system-plans`/`tpl-plan` → `#system-work-items`/`tpl-work-item`; user-visible strings ("Loading plans…", "No plans for this system yet.") updated. - Bundled skills: scope/SKILL.md + ship/SKILL.md rewritten to use "work item" for the artifact; hook commands (`stax plans lint` → `stax work-items lint`) in agents/claude/settings.json and agents/codex/hooks.json. The proposal-pattern wording ("plan-first protocol", "sub-plan", "## Plan" approval-prompt heading, "Build the plan", "Present the plan") is preserved as English usage, distinct from the renamed artifact. - Docs: AGENTS.md, CLAUDE.md, README.md, docs/public/reference.md, docs/internal/*.md — artifact noun renamed; reference.md gains a new `.stax/_config.lock` schema subsection covering all three keys + the post-rename migration note. - Scripts: scripts/e2e_test.sh + scripts/e2e_test.ps1 — every `plans` invocation routed through `work-items`; shell constant `PLANS_LIST_OVERFLOW_THRESHOLD` → `WORK_ITEMS_LIST_OVERFLOW_THRESHOLD` with matching update in constants_e2e_test.go's drift check; PS1 helpers `Add-ManyPlans`/`Write-PlanWithBody` → `Add-ManyWorkItems`/ `Write-WorkItemWithBody`; fixture slug stems `-plan{NNN}` → `-work-item{NNN}` with all assertions following. - Skills-evals: `test_*_plan_extends.py` → `test_*_work_item_extends.py`; `plan_judge.py` → `work_item_judge.py`; fixture loaders/judgments updated to match. - Sample data: `.stax.example/_config.lock` schema key updated. Sample work-item bodies that use "plan" in a billing/subscription sense (e.g. "subscription plan changes") left untouched — domain English, not the renamed artifact. Verified locally: go vet + go test clean, npm run check + frontend build clean, scripts/e2e_test.sh 624/624 cases pass. Signed-off-by: Tanzim Saqib <[email protected]> * fix(frontend): include @emnapi/* in lock for cross-platform npm ci The committed lock file was missing node_modules/@emnapi/core and node_modules/@emnapi/runtime — peer deps that oxc-parser bindings pull in on Linux x64. Locally npm install on macOS ARM64 doesn't notice because the local platform binding doesn't need them, but GitHub Actions runs npm ci on linux/amd64 and rejects the lock as out-of-sync. Regenerated the lock file with `npm install --include=optional` from a clean state so all platform-specific bindings + their transitive peer deps are recorded. No package.json changes. Signed-off-by: Tanzim Saqib <[email protected]> --------- Signed-off-by: Tanzim Saqib <[email protected]>
1 parent 94496db commit 8ed25f9

77 files changed

Lines changed: 2930 additions & 2905 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/skills-eval-claude-user-scope.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ name: skills eval / claude code (user scope)
1212
# (skills-evals/src/skills_evals/claude_driver.py) because
1313
# `claude -p` is otherwise one-shot and the skills prompt for
1414
# confirmation mid-run.
15-
# c. Score the plan and the produced artifacts with two DeepEval
15+
# c. Score the work item and the produced artifacts with two DeepEval
1616
# `GEval` metrics backed by DeepSeek.
1717
# 4. Upload the pytest tmp directory (transcripts + workspace) on
1818
# failure so the run can be inspected offline.

‎.github/workflows/skills-eval-claude.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ name: skills eval / claude code
1212
# (skills-evals/src/skills_evals/claude_driver.py) because
1313
# `claude -p` is otherwise one-shot and the skills prompt for
1414
# confirmation mid-run.
15-
# c. Score the plan and the produced artifacts with two DeepEval
15+
# c. Score the work item and the produced artifacts with two DeepEval
1616
# `GEval` metrics backed by DeepSeek.
1717
# 4. Upload the pytest tmp directory (transcripts + workspace) on
1818
# failure so the run can be inspected offline.

‎.github/workflows/skills-eval-cline.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ name: skills eval / cline
2020
# (`cline auth --provider deepseek --apikey <key> --modelid
2121
# deepseek-v4-pro` in the workspace fixture; sandboxed $HOME
2222
# means the auth state is per-test).
23-
# c. Score the plan and produced artifacts with the same DeepEval
23+
# c. Score the work item and produced artifacts with the same DeepEval
2424
# `GEval` metrics used by the Claude eval.
2525
# 4. Upload the pytest tmp directory (transcripts + workspace) on
2626
# failure so the run can be inspected offline.

‎.github/workflows/skills-eval-copilot.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ name: skills eval / github copilot cli
1818
# "Reply yes" gate, the next turn invokes
1919
# `copilot --continue -C <workspace> -p yes ...` to resume the
2020
# same session.
21-
# c. Score the plan and produced artifacts with the same DeepEval
21+
# c. Score the work item and produced artifacts with the same DeepEval
2222
# `GEval` metrics used by the Claude eval.
2323
# 4. Upload the pytest tmp directory (transcripts + workspace) on
2424
# failure so the run can be inspected offline.

‎.github/workflows/skills-eval-opencode.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ name: skills eval / opencode
1515
# string would be passed to the LLM and hallucinated as a
1616
# missing command. The driver reads the SKILL.md off disk and
1717
# concatenates it with the task.
18-
# c. Score the plan and the produced artifacts with two DeepEval
18+
# c. Score the work item and the produced artifacts with two DeepEval
1919
# `GEval` metrics backed by DeepSeek.
2020
# 4. Upload the pytest tmp directory (transcripts + workspace) on
2121
# failure so the run can be inspected offline.

‎.github/workflows/skills-eval-pi.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ name: skills eval / pi
1818
# form in skills_evals.pi_driver. Confirmation gates show up as
1919
# text events the driver matches against the "Reply yes" pattern
2020
# and replies to with `pi -c -p yes` on the next turn.
21-
# c. Score the plan and the produced artifacts with two DeepEval
21+
# c. Score the work item and the produced artifacts with two DeepEval
2222
# `GEval` metrics backed by DeepSeek.
2323
# 4. Upload the pytest tmp directory (transcripts + workspace) on
2424
# failure so the run can be inspected offline.

‎.stax.example/_config.lock‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"prefix_width": 4,
3-
"max_plan_lines": 30,
3+
"max_work_item_lines": 30,
44
"review_per": "task"
55
}

‎AGENTS.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
## What this project is
22

3-
`stax` (Stackific Inc.) is a Go CLI that ships a two-skill agent vocabulary — `/scope` (planner) and `/ship` (executor) — to Claude Code, Codex CLI, and any other agent that follows the SKILL.md open standard. The binary's job is to install those skills into each agent's expected locations and seed a project scaffold (`.stax/`) that the skills write plan files into.
3+
`stax` (Stackific Inc.) is a Go CLI that ships a two-skill agent vocabulary — `/scope` (planner) and `/ship` (executor) — to Claude Code, Codex CLI, and any other agent that follows the SKILL.md open standard. The binary's job is to install those skills into each agent's expected locations and seed a project scaffold (`.stax/`) that the skills write work-item files into.
44

55
Two persistent on-disk surfaces matter:
66

77
- **`~/.stax/agents/`** — the bundled embed, materialized on first run, refreshed wholesale every hourly. The binary owns it; users MUST NOT hand-edit.
8-
- **`<project>/.stax/`** — the per-project scaffold (`_config.lock` pins, `_data_systems.yaml` registry, `*.md` plan files). `stax init` seeds it; everything after that is the user's, including the plan files which are first-class repo content.
8+
- **`<project>/.stax/`** — the per-project scaffold (`_config.lock` pins, `_data_systems.yaml` registry, `*.md` work-item files). `stax init` seeds it; everything after that is the user's, including the work-item files which are first-class repo content.
99

10-
The single on-disk marker that distinguishes "a stax project" from "any other directory" is `<cwd>/.stax/_config.lock`. Every project-scope CLI subcommand (`stax plans *`, `stax skills remove --project`) and every Claude/Codex invocation of `/scope` or `/ship` keys off that file. If it is missing, the directory is unusable as a stax project regardless of whether skills are installed.
10+
The single on-disk marker that distinguishes "a stax project" from "any other directory" is `<cwd>/.stax/_config.lock`. Every project-scope CLI subcommand (`stax work-items *`, `stax skills remove --project`) and every Claude/Codex invocation of `/scope` or `/ship` keys off that file. If it is missing, the directory is unusable as a stax project regardless of whether skills are installed.
1111

1212
`--scope` on `stax init` decides ONLY where the bundled SKILLS land:
1313

1414
- `--scope project` → skills under `<cwd>/.claude/skills/`, `<cwd>/.agents/skills/`, …
1515
- `--scope user` → skills under `~/.claude/skills/`, `~/.agents/skills/`, …
1616

17-
`.stax/_config.lock` is seeded in cwd under **both** scopes. A user-scope install that did not seed cwd would produce skills with nowhere to anchor plans — the project marker check would fail on the very next command. The two responsibilities (skill placement and project-marker scaffold) are orthogonal; treat them that way in every code path and every test assertion.
17+
`.stax/_config.lock` is seeded in cwd under **both** scopes. A user-scope install that did not seed cwd would produce skills with nowhere to anchor work items — the project marker check would fail on the very next command. The two responsibilities (skill placement and project-marker scaffold) are orthogonal; treat them that way in every code path and every test assertion.
1818

1919
## Hard rules
2020
- 2 spaces for indentation
@@ -28,7 +28,7 @@ The single on-disk marker that distinguishes "a stax project" from "any other di
2828
- Every interactive prompt MUST have a fully non-interactive equivalent that drives the same code path via flags (any number of them — one per choice the prompt would collect). The non-interactive form must take a single shot of arguments and exit without ever reading from stdin. Both forms must be covered in `scripts/e2e_test.sh`: at minimum one case piping input into the prompt and one case passing the equivalent flags. Rationale: CI, scripted installs, and headless agents cannot answer prompts, so every interactive scenario that ships without a flag-driven twin is a blocker for automation. Example: `stax init` prompts for scope AND accepts `--scope project|user` — when a new prompt question is added, a matching flag must be added in the same change.
2929
- `~/.stax/agents/` is owned exclusively by the `stax` binary's embedded FS. It is materialized on first run (`ensureBundledAgents`) and overwritten wholesale every hourly by `maybeNotifyUpdate` → `writeBundledAgents(true)`. Users MUST NOT hand-edit anything under this tree — local changes are destroyed on the next refresh. Conversely, no code path other than `writeBundledAgents` (and its callers `ensureBundledAgents` / `maybeNotifyUpdate`) may write into `~/.stax/agents/`.
3030
- Project-level skill trees (`.claude/`, `.agents/`, `.codex/` inside a user's project) are written by `stax init` and are off-limits to `stax` thereafter. No subcommand, update check, or background path may mutate, refresh, or delete files under these directories after init — they are the user's to edit, version-control, and diverge from the embed. The hourly refresh in `maybeNotifyUpdate` is scoped strictly to `~/.stax/agents/` and MUST NOT extend to project trees. Any future feature that re-touches project skills must be an explicit, user-invoked command, never an opportunistic background write.
31-
- `stax init` MUST seed `<cwd>/.stax/` (`_config.lock` + `_data_systems.yaml`) under **every** scope, including `--scope user`. `--scope` controls only where the bundled SKILLS land (project tree vs `$HOME`); the `.stax/_config.lock` marker is what makes cwd usable with `/scope`, `/ship`, and every `stax plans *` subcommand, and it has nothing to do with where skills live. Do NOT condition `writePlansScaffold` on scope — that produced skills with nowhere to anchor plans and failed the "not a stax project" check on every subsequent command. Tests that assert the *absence* of `.stax/` after `--scope user` are wrong and lock in this bug; tests MUST assert presence of `_config.lock` and `_data_systems.yaml` in cwd under both scopes.
31+
- `stax init` MUST seed `<cwd>/.stax/` (`_config.lock` + `_data_systems.yaml`) under **every** scope, including `--scope user`. `--scope` controls only where the bundled SKILLS land (project tree vs `$HOME`); the `.stax/_config.lock` marker is what makes cwd usable with `/scope`, `/ship`, and every `stax work-items *` subcommand, and it has nothing to do with where skills live. Do NOT condition `writeWorkItemsScaffold` on scope — that produced skills with nowhere to anchor work items and failed the "not a stax project" check on every subsequent command. Tests that assert the *absence* of `.stax/` after `--scope user` are wrong and lock in this bug; tests MUST assert presence of `_config.lock` and `_data_systems.yaml` in cwd under both scopes.
3232
- Every commit MUST be both DCO-signed-off AND cryptographically signed before being pushed. DCO sign-off is the `Signed-off-by: <Name> <email>` trailer matching the commit's author email — pass `-s` to every `git commit` (or set `git config --local format.signoff true` once per clone). Cryptographic signing produces the green "Verified" badge on GitHub — requires `git config --local commit.gpgsign true`, `git config --local gpg.format ssh` (or `gpg`), and `git config --local user.signingkey <path-or-id>` pointing at an SSH/GPG key registered to the author's GitHub account under **Signing Key** type at https://github.com/settings/keys. Checking `git config --get commit.gpgsign` is NOT sufficient — config can say `true` while signing silently no-ops if the key file is missing, the agent isn't loaded, or the format is misconfigured. Verify the previous commit actually signed: `git log -1 --format='%G?'` MUST return `G`, `U`, or `B` (signed); `N` means no signature was attached and the push will land unverified. If `%G?` returns `N`, STOP and ask the user to complete signing setup per `docs/internal/commit-signing.md` rather than pushing an unverified commit. Both DCO and signature checks are branch-protection enforced on `main`; pushing an unverified commit forces a force-push to fix and burns DCO/signature history.
3333

3434
## Frontend stack and conventions
@@ -39,13 +39,13 @@ The web UI under `frontend/` is a Vite multi-page app (MPA), not an SPA. Routing
3939
- **Vite** with `vite-plugin-handlebars` for build-time block partials. `frontend/partials/layout.html` is the shell; `header`, `mobile-nav`, `footer` are nested partials. Each page calls `{{#> layout title="..." page="..." active="..."}}...{{/layout}}`.
4040
- **TypeScript** + **BeerCSS** (Material Design 3 utility classes + Material Symbols icons) + **material-dynamic-colors** for the M3 palette. **Geist Variable** is loaded by a single `@font-face` rule in `src/styles/app.scss` pointing at jsdelivr's fontsource CDN — no woff2 embedded in the build output.
4141
- **Biome** for lint + format, **Knip** for deadcode, **Terser** for minification. `npm run check` runs typecheck + Biome + Knip; the lefthook `frontend-check` pre-push hook runs the same.
42-
- **goldmark** (server side, scope.go via `markdownRenderer`) renders plan markdown to HTML before crossing the wire — GFM extension, headings forced to `<h6>` by the `forceH6Headings` AST transformer, raw HTML escaped (no `WithUnsafe`). The frontend `innerHTML`s only that sanitized output; user-typed markdown never reaches the page directly.
42+
- **goldmark** (server side, server.go via `markdownRenderer`) renders work-item markdown to HTML before crossing the wire — GFM extension, headings forced to `<h6>` by the `forceH6Headings` AST transformer, raw HTML escaped (no `WithUnsafe`). The frontend `innerHTML`s only that sanitized output; user-typed markdown never reaches the page directly.
4343

4444
### Frontend hard rules
4545
- **No HTML-in-JS.** Page markup lives in `.html` files. Dynamic content is rendered by cloning a `<template>` element and writing `textContent` / `href` into `data-slot="..."` placeholders (see `src/shared/dom.ts` for `$` and `tpl`). Building DOM via template-literal HTML strings or `innerHTML = "<div>..."` is forbidden — it defeats the no-XSS contract and pulls layout into TS. The single exception is `#scope-body` on `/scope?id=`, where the server returns goldmark-rendered, raw-HTML-escaped output.
4646
- **One JS entry, one CSS file.** `src/bundle.ts` is the only JS entry across every page; `dist/` ships `bundle.js` + `bundle.css`. A post-build `renameBundle` Vite plugin restores the names after Rollup's auto-suffixed `bundleN.js` dedup. Adding a page means four coordinated edits in the same change: (a) new `<page>.html` calling the layout partial, (b) entry in the `pages` array in `vite.config.ts`, (c) per-page init function in `src/pages/<page>.ts`, (d) wiring in the dispatcher in `src/bundle.ts`.
4747
- **Dispatch by `data-page` and `data-active`.** `<body data-page="<name>">` (set per page via the layout's block-helper context) drives the per-page init dispatcher in `bundle.ts`. Nav highlight uses `<body data-active="<key>">` for parity (a `/scope?id=…` page sets `active="scopes"` so the sidebar still highlights the list). Both attributes are written by the HTML — never inferred from `location.pathname` in TS.
48-
- **Color cues go through `src/shared/status.ts`.** `applyStatusClass(el, status)` tints status nodes per lifecycle (`superseded` → tertiary, `deprecated` → error) and rows whose plan has at least one `- [ ]` task get `primary-text` on the flag icon. Adding a new semantic cue means extending the helper, not inlining a color class per call site. Use BeerCSS color tokens (`primary` / `secondary` / `tertiary` / `error`, with `-text` / `-container` variants) rather than custom CSS variables — the M3 dynamic palette already covers the conventional roles.
48+
- **Color cues go through `src/shared/status.ts`.** `applyStatusClass(el, status)` tints status nodes per lifecycle (`superseded` → tertiary, `deprecated` → error) and rows whose work item has at least one `- [ ]` task get `primary-text` on the flag icon. Adding a new semantic cue means extending the helper, not inlining a color class per call site. Use BeerCSS color tokens (`primary` / `secondary` / `tertiary` / `error`, with `-text` / `-container` variants) rather than custom CSS variables — the M3 dynamic palette already covers the conventional roles.
4949
- **Relative time goes through `src/shared/relative-time.ts`** (`relativeTime(iso)`). Don't reach for `toLocaleDateString` per page; the helper handles "just now" / "N minutes ago" / "N months M days ago" uniformly.
5050
- **Shared modules under `src/shared/`** — `api` (typed fetch wrapper), `dom` (`$` / `tpl` helpers), `qs` (URL query string getter), `theme`, `sidebar`, `nav`, `relative-time`, `status`. New cross-page utilities go here, not duplicated per page. Importing across `src/pages/*.ts` is forbidden — pages are dispatcher leaves and stay independent.
5151
- **API shape conventions (must mirror `server.go`):** list responses wrap the array as `{things: [...]}` (`{systems: [...]}`, `{scopes: [...]}`) for forward compat with pagination cursors; empty results are serialized as `[]`, never `null`; cross-references between entities (e.g. `supersededBy`, `supersedes`) use `{slug, title}` (or `{id, name}`) pairs so the UI can render human text without a per-row round-trip. Adding a field is a breaking change on the wire only if it's required — optional fields land as `omitempty` in Go and `field?: T` in TS.

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ stax init
2121
# Launch your AI coding agent and invoke the `/scope` skill
2222
/scope <specify-your-need>
2323

24-
# Execute the next plan in line
24+
# Execute the next work item in line
2525
/ship
2626
```
2727

@@ -47,7 +47,7 @@ See [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md) for the contribution wo
4747

4848
## What does `stax` mean?
4949

50-
Stacks of plans. The binary writes plans into `.stax/`, and the two skills move them along the line: `/scope` files a new plan, `/ship` works the stack.
50+
Stacks of work items. The binary writes work items into `.stax/`, and the two skills move them along the line: `/scope` files a new work item, `/ship` works the stack.
5151

5252
## License
5353

‎agents/claude/settings.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
"hooks": [
88
{
99
"type": "command",
10-
"command": "stax plans lint"
10+
"command": "stax work-items lint"
1111
}
1212
]
1313
}
@@ -18,7 +18,7 @@
1818
"hooks": [
1919
{
2020
"type": "command",
21-
"command": "stax plans lint"
21+
"command": "stax work-items lint"
2222
}
2323
]
2424
}

0 commit comments

Comments
 (0)