Skip to content

Commit 78fbdf7

Browse files
josealekhinejosealekhine
committed
refactor: CLI namespace cleanup — bootstrap, stats, resource, dep, hook
Five command surface changes: - Move `ctx bootstrap` back to `ctx system bootstrap` (hidden, agent-only plumbing that was incorrectly promoted to top-level) - Rename `ctx stats` to `ctx usage` (clearer intent) - Rename `ctx resource` to `ctx sysinfo` (matches internal package, unambiguous) - Remove `ctx dep` entirely (marginal utility, go list/npm ls suffice) - Introduce `ctx hook` parent — consolidates message, notify, pause, resume, and event under a single namespace Includes full propagation: constants, YAML assets, flag/text DescKeys, group.go registration, docs, recipes, skills, CLI index, zensical.toml nav, and dead export cleanup of orphaned dep support packages. Also adds: - _ctx-command-audit skill for post-rename quality gates - Package taxonomy section in docs/home/contributing.md - hack/agents/ directory for autonomous agent prompts - Follow-up task for ctx explore command Signed-off-by: Jose Alekhinne <jose@ctx.ist>
1 parent 2ff53c5 commit 78fbdf7

179 files changed

Lines changed: 10331 additions & 7046 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.

‎.claude/skills/_ctx-command-audit/SKILL.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
---
2+
name: _ctx-command-audit
3+
description: "Audit CLI command surface after renames, moves, or deletions. Use after any namespace change to catch stale references."
4+
---
5+
6+
Verify that a CLI command change (rename, move, deletion, new parent
7+
grouping) is fully propagated across code, assets, docs, and tests.
8+
9+
## Before Running
10+
11+
1. **Build passes**: `go build ./...` must succeed
12+
2. **Know what changed**: list the command changes (old name -> new
13+
name, or deleted, or moved under a parent)
14+
15+
## When to Use
16+
17+
- After renaming a CLI command (e.g. `ctx stats` -> `ctx usage`)
18+
- After moving a command under a parent (e.g. `ctx pause` -> `ctx hook pause`)
19+
- After deleting a command entirely (e.g. `ctx dep`)
20+
- After promoting or demoting a command (top-level <-> system subcommand)
21+
22+
## When NOT to Use
23+
24+
- For flag-only changes (no command surface change)
25+
- For internal refactors that don't change the user-facing command name
26+
- When only adding a brand-new command (use `_ctx-qa` instead)
27+
28+
## Usage Examples
29+
30+
```text
31+
/_ctx-command-audit
32+
/_ctx-command-audit (after renaming ctx stats to ctx usage)
33+
```
34+
35+
## Checks
36+
37+
For each renamed/moved/deleted command, run these checks in order.
38+
39+
### 1. Cobra --help examples
40+
41+
Verify the examples shown in `--help` output use the correct
42+
command path.
43+
44+
```bash
45+
grep -r "ctx <old-name>" internal/assets/commands/examples.yaml
46+
grep -r "ctx <old-name>" internal/assets/commands/commands.yaml
47+
```
48+
49+
Fix: Update YAML values to use the new command path. For
50+
subcommands under a parent, examples must show the full path
51+
(e.g. `ctx hook event`, not `ctx event`).
52+
53+
### 2. Use/DescKey constants
54+
55+
Verify the cobra Use string and DescKey constant match the new
56+
command name.
57+
58+
```bash
59+
grep -r "Use<OldName>\|DescKey<OldName>" internal/config/embed/cmd/
60+
```
61+
62+
Fix: Rename constants, rename the file if needed (e.g.
63+
`stats.go` -> `usage.go`), update all callers.
64+
65+
### 3. Flag DescKey constants
66+
67+
Verify flag description keys use the new command prefix.
68+
69+
```bash
70+
grep -r "<old-name>\." internal/config/embed/flag/
71+
```
72+
73+
Fix: Rename constants and their string values (e.g.
74+
`stats.follow` -> `usage.follow`), rename the file, update
75+
the corresponding `flags.yaml` keys.
76+
77+
### 4. Text DescKey constants
78+
79+
Verify text/write/error description keys use the new prefix.
80+
81+
```bash
82+
grep -r "<old-name>\." internal/config/embed/text/
83+
```
84+
85+
Fix: Rename constants and YAML keys in
86+
`internal/assets/commands/text/*.yaml`.
87+
88+
### 5. group.go registration
89+
90+
Verify the command is registered in the correct group (or
91+
removed if deleted).
92+
93+
```bash
94+
grep "<old-package>" internal/bootstrap/group.go
95+
```
96+
97+
Fix: Update import path and registration entry. Update the
98+
function's doc comment to list the current commands.
99+
100+
### 6. Doc pages
101+
102+
Verify `docs/cli/<name>.md` exists with correct content, or
103+
is removed for deleted commands.
104+
105+
```bash
106+
ls docs/cli/<old-name>.md # should not exist
107+
ls docs/cli/<new-name>.md # should exist
108+
```
109+
110+
Fix: `git mv` for renames, `git rm` for deletions, create new
111+
files for new parent commands.
112+
113+
### 7. CLI index
114+
115+
Verify `docs/cli/index.md` references the correct command names
116+
and links.
117+
118+
```bash
119+
grep "<old-name>" docs/cli/index.md
120+
```
121+
122+
Fix: Update table entries, links, and anchors.
123+
124+
### 8. zensical.toml nav
125+
126+
Verify the site navigation references correct filenames.
127+
128+
```bash
129+
grep "<old-name>" zensical.toml
130+
```
131+
132+
Fix: Update nav entries to match renamed/new doc files.
133+
134+
### 9. Recipes and docs sweep
135+
136+
Broad sweep for any remaining stale references in user-facing
137+
documentation.
138+
139+
```bash
140+
grep -r "ctx <old-name>" docs/ --include="*.md"
141+
grep -r "ctx <old-name>" internal/assets/claude/ --include="*.md"
142+
```
143+
144+
Fix: Update all references. For commands moved under a parent,
145+
every `ctx <name>` becomes `ctx <parent> <name>`.
146+
147+
### 10. Dead export cascade
148+
149+
After deleting a command, its support packages may become
150+
orphaned (config constants, error constructors, write functions,
151+
exec helpers, format constants, regex patterns).
152+
153+
```bash
154+
make test # TestNoDeadExports will catch these
155+
```
156+
157+
Fix: Delete orphaned packages and constants. Do NOT add
158+
allowlist exceptions — trace the dead export to its root cause
159+
and remove it properly.
160+
161+
### 11. YAML orphan check
162+
163+
After deleting constants, their YAML counterparts may remain
164+
as orphans.
165+
166+
```bash
167+
make test # TestDescKeyYAMLLinkage will catch these
168+
```
169+
170+
Fix: Remove the orphaned YAML entries from `commands.yaml`,
171+
`examples.yaml`, `flags.yaml`, and `text/*.yaml`.
172+
173+
### 12. Magic string check
174+
175+
If you inlined data that previously lived in a config package,
176+
the magic strings test will catch it.
177+
178+
```bash
179+
make test # TestNoMagicStrings will catch these
180+
```
181+
182+
Fix: Move the data to an appropriate `internal/config/`
183+
package. Never inline string literals in source files.
184+
185+
### 13. AST test exceptions
186+
187+
Verify no allowlist entries were added to pass tests.
188+
189+
```bash
190+
grep -r "allowlist\|whitelist\|skip\|except" internal/audit/ internal/compliance/ | grep -i "<command-name>"
191+
```
192+
193+
Fix: If you added an exception, remove it and fix the
194+
underlying issue instead.
195+
196+
### 14. Docstring review
197+
198+
Verify doc comments on touched packages are accurate, not
199+
just minimally gate-passing.
200+
201+
Check these files for each renamed/moved command:
202+
- `doc.go` — package description matches new command path
203+
- `cmd.go` — `Cmd()` godoc names the correct command
204+
- `system.go` or parent — subcommand list in comments is current
205+
- `group.go` — function doc comments list current commands
206+
207+
## Output Format
208+
209+
Report as a checklist:
210+
211+
```
212+
## Command Audit: <change description>
213+
214+
- [x] Cobra --help examples updated
215+
- [x] Use/DescKey constants renamed
216+
- [x] Flag DescKeys renamed
217+
- [x] Text DescKeys renamed
218+
- [x] group.go registration updated
219+
- [x] Doc pages renamed/created/deleted
220+
- [x] CLI index updated
221+
- [x] zensical.toml nav updated
222+
- [x] Recipes and docs swept
223+
- [x] No dead exports
224+
- [x] No orphan YAML keys
225+
- [x] No magic strings
226+
- [x] No AST test exceptions added
227+
- [x] Docstrings reviewed
228+
229+
**Result**: PASS / FAIL (N issues)
230+
```
231+
232+
## Relationship to Other Skills
233+
234+
| Skill | Scope |
235+
|------------------------|------------------------------------|
236+
| `_ctx-qa` | General build/lint/test gate |
237+
| `_ctx-audit` | Codebase convention sweep |
238+
| `_ctx-command-audit` | CLI surface change completeness |
239+
| `_ctx-update-docs` | Docs-code consistency after edits |
240+
| `_ctx-alignment-audit` | Agent playbook vs docs alignment |
241+
242+
## Quality Checklist
243+
244+
Before reporting results, verify:
245+
- [ ] Every check was run for every changed command
246+
- [ ] No stale references remain in docs, recipes, or assets
247+
- [ ] Tests pass with zero exceptions added
248+
- [ ] Docstrings read as if written by someone who understands
249+
the domain, not as minimal gate-passers

‎.context/TASKS.md‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,21 @@ TASK STATUS LABELS:
2727

2828
### Misc
2929

30-
- [ ] Move `ctx bootstrap` back to `ctx system bootstrap` (hidden). Bootstrap is agent-only plumbing — no human types it interactively. It was incorrectly promoted to top-level in the namespace cleanup. Move the package back to `internal/cli/system/cmd/bootstrap/`, restore `UseSystemBootstrap`/`DescKeySystemBootstrap` constants, re-add `Hidden: true`, update CLAUDE.md templates and skills back to `ctx system bootstrap`, remove from `docs/cli/bootstrap.md` and `docs/cli/index.md` Diagnostics group, remove from `zensical.toml` nav. Spec: specs/cli-namespace-cleanup.md #priority:high #added:2026-04-11
30+
- [ ] If context is not initialized, hooks should not run. Right now they run and give a "context diretory outside project root" (that's a side effect). But the issue is the project does not have a .context folder and we don't detect it.
3131

32-
- [ ] Rename `ctx stats` to `ctx usage`. "Stats for what?" — the current name lost its anchor when promoted from `ctx system stats`. `ctx usage` communicates intent: "show me my token usage." `ctx session stats` was considered but rejected as premature — a parent with one child is worse than a flat command. Revisit when `ctx session` has 2+ children. Spec: specs/cli-namespace-cleanup.md #priority:medium #added:2026-04-11
32+
- [x] Move `ctx bootstrap` back to `ctx system bootstrap` (hidden). Bootstrap is agent-only plumbing — no human types it interactively. It was incorrectly promoted to top-level in the namespace cleanup. Move the package back to `internal/cli/system/cmd/bootstrap/`, restore `UseSystemBootstrap`/`DescKeySystemBootstrap` constants, re-add `Hidden: true`, update CLAUDE.md templates and skills back to `ctx system bootstrap`, remove from `docs/cli/bootstrap.md` and `docs/cli/index.md` Diagnostics group, remove from `zensical.toml` nav. Spec: specs/cli-namespace-cleanup.md #priority:high #added:2026-04-11 #done:2026-04-12
3333

34-
- [ ] Rename `ctx resource` to `ctx sysinfo`. Without the `system` prefix, "resource" sounds like it manages project resources (files, assets, infrastructure). It's actually a system-health snapshot: memory, swap, disk, CPU load. `sysinfo` matches the internal package name (`internal/sysinfo`) and is unambiguous. `health` was considered but rejected — too similar to `ctx doctor` and `ctx doctor health` reads wrong. Same rename pattern. Spec: specs/cli-namespace-cleanup.md #priority:medium #added:2026-04-11
34+
- [x] Rename `ctx stats` to `ctx usage`. "Stats for what?" — the current name lost its anchor when promoted from `ctx system stats`. `ctx usage` communicates intent: "show me my token usage." `ctx session stats` was considered but rejected as premature — a parent with one child is worse than a flat command. Revisit when `ctx session` has 2+ children. Spec: specs/cli-namespace-cleanup.md #priority:medium #added:2026-04-11 #done:2026-04-12
3535

36-
- [ ] Deprecate or remove `ctx dep`. Utility is marginal: agents rarely need a flat dependency inventory to make decisions, and `go list -m all` / `npm ls` already cover the use case. Doesn't clear the "would I miss it if it vanished?" bar. Removal is a one-command delete + doc cleanup. #priority:low #added:2026-04-11
36+
- [x] Rename `ctx resource` to `ctx sysinfo`. Without the `system` prefix, "resource" sounds like it manages project resources (files, assets, infrastructure). It's actually a system-health snapshot: memory, swap, disk, CPU load. `sysinfo` matches the internal package name (`internal/sysinfo`) and is unambiguous. `health` was considered but rejected — too similar to `ctx doctor` and `ctx doctor health` reads wrong. Same rename pattern. Spec: specs/cli-namespace-cleanup.md #priority:medium #added:2026-04-11 #done:2026-04-12
3737

38-
- [ ] Introduce `ctx hook` parent command — consolidate hook-related user-facing commands under a single namespace: `ctx hook message list/show/edit/reset` (currently `ctx message`), `ctx hook notify` (currently `ctx notify`), `ctx hook pause` / `ctx hook resume` (currently top-level `ctx pause` / `ctx resume`). "What are we pausing?" — hooks. The current top-level `pause` loses that context. Clarifies the `ctx trigger` vs `ctx hook` distinction: `trigger` = user-authored scripts, `hook` = plugin-shipped machinery + its user-facing controls. Future children: `ctx hook status` (which hooks fired recently), `ctx hook test` (dry-run), `ctx hook event` (currently `ctx event`). Same rename pattern as previous namespace cleanups. Spec: specs/cli-namespace-cleanup.md #priority:medium #added:2026-04-11
38+
- [x] Remove `ctx dep`. Utility is marginal: agents rarely need a flat dependency inventory to make decisions, and `go list -m all` / `npm ls` already cover the use case. Doesn't clear the "would I miss it if it vanished?" bar. Removed command, all support packages, docs, and recipes. #priority:low #added:2026-04-11 #done:2026-04-12
39+
40+
- [x] Introduce `ctx hook` parent command — consolidate hook-related user-facing commands under a single namespace: `ctx hook message list/show/edit/reset` (currently `ctx message`), `ctx hook notify` (currently `ctx notify`), `ctx hook pause` / `ctx hook resume` (currently top-level `ctx pause` / `ctx resume`). "What are we pausing?" — hooks. The current top-level `pause` loses that context. Clarifies the `ctx trigger` vs `ctx hook` distinction: `trigger` = user-authored scripts, `hook` = plugin-shipped machinery + its user-facing controls. Future children: `ctx hook status` (which hooks fired recently), `ctx hook test` (dry-run), `ctx hook event` (currently `ctx event`). Same rename pattern as previous namespace cleanups. Spec: specs/cli-namespace-cleanup.md #priority:medium #added:2026-04-11 #done:2026-04-12
41+
42+
### Agents
43+
44+
- [ ] Add `ctx explore` command — scaffolds `.arch-explorer/` in a workspace directory with manifest.json, PROMPT.md (from `hack/agents/architecture-explorer.md`), run-log.md, and a README. Similar to `ctx init` but for multi-repo architecture exploration. The prompt template lives in `hack/agents/architecture-explorer.md` and ships embedded. #priority:low #added:2026-04-13
3945

4046
### Runbooks
4147

‎CLAUDE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ This project uses Context (`ctx`) for context persistence across sessions.
1010

1111
## On Session Start
1212

13-
1. **Run `ctx bootstrap`**: CRITICAL, not optional.
13+
1. **Run `ctx system bootstrap`**: CRITICAL, not optional.
1414
This tells you where the context directory is. If it fails or returns
1515
no context_dir, STOP and warn the user.
1616
2. **Read AGENT_PLAYBOOK.md** from the context directory: it explains
@@ -57,7 +57,7 @@ ctx status
5757
| LEARNINGS.md | Gotchas, tips, lessons learned |
5858
| CONVENTIONS.md | Code patterns and standards |
5959

60-
All files live in the context directory reported by `ctx bootstrap`.
60+
All files live in the context directory reported by `ctx system bootstrap`.
6161

6262
## Hook Authority
6363

‎docs/cli/bootstrap.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,25 @@
55
# \ Copyright 2026-present Context contributors.
66
# SPDX-License-Identifier: Apache-2.0
77

8-
title: Bootstrap
8+
title: System Bootstrap
99
icon: lucide/compass
1010
---
1111

1212
![ctx](../images/ctx-banner.png)
1313

14-
### `ctx bootstrap`
14+
### `ctx system bootstrap`
1515

1616
Print the resolved context directory path so AI agents can anchor
1717
their session. The default output lists the context directory, the
1818
tracked context files, and a short health snapshot. `--quiet` prints
1919
just the path; `--json` produces structured output for automation.
2020

21-
This is the command agents are instructed to run first in their
22-
session-start procedure — it is the authoritative answer to "where
23-
does this project's context live?".
21+
This is a hidden, agent-only command that agents are instructed to
22+
run first in their session-start procedure — it is the authoritative
23+
answer to "where does this project's context live?".
2424

2525
```bash
26-
ctx bootstrap [flags]
26+
ctx system bootstrap [flags]
2727
```
2828

2929
**Flags**:
@@ -36,11 +36,11 @@ ctx bootstrap [flags]
3636
**Examples**:
3737

3838
```bash
39-
ctx bootstrap # Text output for agents
40-
ctx bootstrap -q # Just the context directory path
41-
ctx bootstrap --json # Structured output for automation
39+
ctx system bootstrap # Text output for agents
40+
ctx system bootstrap -q # Just the context directory path
41+
ctx system bootstrap --json # Structured output for automation
4242
```
4343

44-
**Scripting tip**: `CTX_DIR=$(ctx bootstrap -q)` is the canonical way
45-
for skills and scripts to find the project's context directory
46-
without hardcoding `.context/`.
44+
**Scripting tip**: `CTX_DIR=$(ctx system bootstrap -q)` is the
45+
canonical way for skills and scripts to find the project's context
46+
directory without hardcoding `.context/`.

0 commit comments

Comments
 (0)