You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8ed25f9
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Copy file name to clipboardExpand all lines: AGENTS.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,20 +1,20 @@
1
1
## What this project is
2
2
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.
4
4
5
5
Two persistent on-disk surfaces matter:
6
6
7
7
-**`~/.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.
9
9
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.
11
11
12
12
`--scope` on `stax init` decides ONLY where the bundled SKILLS land:
13
13
14
14
-`--scope project` → skills under `<cwd>/.claude/skills/`, `<cwd>/.agents/skills/`, …
15
15
-`--scope user` → skills under `~/.claude/skills/`, `~/.agents/skills/`, …
16
16
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.
18
18
19
19
## Hard rules
20
20
- 2 spaces for indentation
@@ -28,7 +28,7 @@ The single on-disk marker that distinguishes "a stax project" from "any other di
28
28
- 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.
29
29
-`~/.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/`.
30
30
- 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.
32
32
- 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.
33
33
34
34
## Frontend stack and conventions
@@ -39,13 +39,13 @@ The web UI under `frontend/` is a Vite multi-page app (MPA), not an SPA. Routing
39
39
-**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}}`.
40
40
-**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.
41
41
-**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.
43
43
44
44
### Frontend hard rules
45
45
-**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.
46
46
-**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`.
47
47
-**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.
49
49
-**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.
50
50
-**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.
51
51
-**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.
Copy file name to clipboardExpand all lines: README.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ stax init
21
21
# Launch your AI coding agent and invoke the `/scope` skill
22
22
/scope <specify-your-need>
23
23
24
-
# Execute the next plan in line
24
+
# Execute the next work item in line
25
25
/ship
26
26
```
27
27
@@ -47,7 +47,7 @@ See [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md) for the contribution wo
47
47
48
48
## What does `stax` mean?
49
49
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.
0 commit comments