Bring docs/commands.md up to current state. The document was last
substantively updated in v0.5; v0.5.2 (restore/notes/path/list --names/
completion + archived-inclusive lookup), v0.5.3 (attach + --direct +
persistent session mode + doctor tmux check), and v0.5.4 (info Session
block + list SESSION column) were all undocumented.
Format follows the spec section §3: each command has Purpose, Usage,
Scenarios, Examples, Flags, Notes, Related. Sections are kept short
(roughly one screen each) — if a command needed more, the command is
doing too much, not the docs.
New non-command sections: workspace layout (task and project), a
consolidated environment-variables table (previously scattered),
explicit query-resolution rules including archive-inclusive lookup
behavior, session modes (direct vs persistent), and a shell-completion
how-to.
Examples use the canonical "ctask" command name per spec §3 — docs
describe the product, not the user's local binary path.
Three independent v0.5.3 polish items surfaced during manual WSL smoke testing,
bundled into one commit since they're all string/UX touches with no behavior change.
1. v0.4 lease-prompt tightening (`internal/session/{lease,run,run_preflight}.go`,
`cmd/entry.go`): when ctask is about to enter direct mode on a workspace that
already has a live tmux session, the "Continue anyway?" prompt now suggests
`ctask attach <slug>` as the reattach path. Threaded via
`PreflightOpts.ActiveLeaseHint` / `LaunchOpts.ActiveLeaseHint`; computed in
`cmd/entry.go::directModeTmuxHint` (best-effort: silent when no tmux on PATH
or no session for the workspace). Closes the footgun where a user forgot to
`export CTASK_SESSION_MODE=persistent` in a second terminal and hit the v0.4
coexistence prompt without realizing tmux passive-reattach was the intended
path.
2. Invocation-name in user-facing command hints (`cmd/invocation.go` new,
`cmd/{persistent,entry,resume,doctor}.go`): the binary name printed in
bypass / restore / "create one with" suggestions now reflects
`filepath.Base(os.Args[0])` instead of a hard-coded "ctask". Local-build
PowerShell users running `.\ctask.exe` see `ctask.exe new <ws> --direct`,
matching what they need to type. Installed contexts continue to see `ctask`.
Test seam (`invocationNameOverride`) pins the name to "ctask" in unit tests
so substring assertions stay stable across Go test binary names. Descriptive
prose ("ctask persistent mode requires...") and the ssh-remote hint
(`ssh -t <host> ctask <subcmd>`) intentionally keep the literal "ctask" —
they refer to the program identity / remote invocation, not the local
command form. Affected tests: `cmd/{persistent,resume}_test.go` tightened to
check the full `"<binary> <subcmd> <workspace> --direct"` form.
3. Smoke-checklist fixes (`docs/.../2026-05-08-v0.5.3-smoke-test-checklist.md`):
six issues caught during the run -- S2 now exports CTASK_SESSION_MODE in
both terminals (previously only WSL-A had it, which routed WSL-B's
secondary resume through direct mode instead of passive reattach); O3/A2
tmux-ls expectations corrected (tmux doesn't emit a literal "(detached)"
token); P2 expected behavior rewritten (passive reattach detach returns to
prompt immediately -- AttachExisting calls only shell.AttachSession with
no PollSessionEnd, the owner is responsible for finalize); A1 no longer
asks for Ctrl-C in WSL-B; A6 path now uses a glob (was hardcoded to the
checklist's authoring date, broke on v0.5.1 local-time directory naming);
M1 PATH-hide rewritten to `$HOME/.local/bin` only (was `:/bin` which is a
symlink to /usr/bin on usrmerge systems, did not hide tmux) and uses
`command -v` instead of `which` (which is itself in /usr/bin, unreachable
under the minimal PATH); M3/M4 reordered so the no-workspace verification
runs after PATH is restored (was silently failing under minimal PATH);
T1 wording made "substring match" explicit; T2 wording made N/A
unambiguous; section 10 split into 10a-10f, each a separate input, to
work around PSReadLine multi-line paste parsing.
Adds the workspace-layout diagram to the --project section, describes
how launch_dir is set and overridden, and documents the v0.5 rules for
fallback (missing/not-a-dir) and error (absolute/escape). Adds
CTASK_LAUNCH_DIR to the env-vars table and CTASK_PROJECT_ROOT INFO line
to the doctor example. Query Resolution note explains that both
CTASK_ROOT and the default projects/ subdirectory are searched so
default-location projects are findable from any shell.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the always-informational seed-dir block with three-state checks:
INFO when the env var is unset (defaults will be used), PASS when set and
the path exists, FAIL when set but the directory is missing. Only the
configured-but-missing state counts as a failed check and raises the
doctor exit code.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Project CLAUDE.md template now includes a Git section stating that the
workspace uses a single git repo at the root and subdirectory git init
is not permitted. docs/commands.md picks up the same guidance under the
--project flag section.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reflects the v0.3 polish-pass changes:
- default 'ctask list' shows active tasks AND projects
- --task flag added; --task and --projects are exclusive
- output now includes a "type" column
- 'ctask last' explicitly notes it considers both types
Adds the v0.3 feature spec (source of truth for this release) and
the inline-execution implementation plan that was followed to land
the v0.3 work in the preceding commits.
Scope of v0.3:
- User seed directories (general + project)
- Improved built-in CLAUDE.md defaults (task + project)
- --project mode (type metadata, project root, git init)
- --projects filter for ctask list
- CTASK_TYPE env export
- Status-line and doctor updates
The 2026-04-06-install-workflow plan (also untracked) is left
alone -- it predates this session and is not part of v0.3.
Updates docs/commands.md to cover the v0.3 surface:
- ctask new --project flag, project mode, project root
semantics, seed order, git init behavior
- ctask list --projects flag and --all/--projects matrix
- Seed directory locations (general + project) and skip rules
- CTASK_TYPE child env var, CTASK_PROJECT_ROOT,
CTASK_SEED_DIR, CTASK_SEED_PROJECT_DIR config vars
- Doctor [INFO] seed directory reporting
No remote install or publish commands are added; the project
remains local-only.
justfile with build/install/uninstall/test targets. CLAUDE.md updated with
new install path and commands. status-line-setup.md updated for
%LOCALAPPDATA%\ctask\bin location.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Bash and PowerShell helpers for Claude Code statusLine. Setup docs with fallback note for non-Claude agents.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
typebasedio