From 82c944502d60ac8a9d0b6c5eddc43234bfea36ea Mon Sep 17 00:00:00 2001 From: typebasedio Date: Wed, 22 Apr 2026 19:53:32 -0400 Subject: [PATCH] docs(v0.5): document project subdirectory, launch_dir, CTASK_LAUNCH_DIR, default discovery 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) --- docs/commands.md | 38 ++++++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index c732365..bdad0f0 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -40,13 +40,32 @@ When `--no-launch` is used, no session is started and no session log is written. `--project` is a thin variation on the normal task workflow for longer-lived work. It changes: -- `task.yaml` records `type: project` +- `task.yaml` records `type: project` and `launch_dir: ` (v0.5+) - Default category becomes `projects` - Workspace root falls back to `CTASK_PROJECT_ROOT` if set; otherwise `CTASK_ROOT` - Built-in CLAUDE.md is the project-oriented template (overridable via seed directories) - Seed order: built-in defaults -> general seed (`CTASK_SEED_DIR`) -> project seed (`CTASK_SEED_PROJECT_DIR`) - `git init` runs if `git` is on PATH; a minimal `.gitignore` (`.ctask/` + `logs/sessions.log`) is created **only if no `.gitignore` was already provided by a seed** - If `git` is not available, ctask prints `[ctask] git not found; skipped repository initialization` and continues +- A project subdirectory named after the final suffixed slug is created inside the workspace. ctask does not seed any files inside it -- the user places their own CLAUDE.md, source code, and project structure there. + +**Workspace layout (v0.5):** + +``` +2026-04-22_litlink-v2/ +├── .ctask/ ctask state (lease, manifest, summary, lock) +├── .git/ single git repo at workspace root +├── .gitignore +├── CLAUDE.md ctask workspace rules (managed by ctask + seed) +├── notes.md +├── task.yaml includes launch_dir: "litlink-v2" +├── context/ reference material, imported specs +├── output/ ctask deliverables +├── logs/ session logs +└── litlink-v2/ project subdirectory (user's codebase) +``` + +When `ctask resume litlink-v2` runs, the agent is launched inside `litlink-v2/`. Both the workspace CLAUDE.md (root) and any project CLAUDE.md the user places inside `litlink-v2/` apply to the session -- Claude Code reads CLAUDE.md hierarchically. **Project root semantics:** @@ -57,8 +76,15 @@ When `--no-launch` is used, no session is started and no session log is written. **Single git repo rule:** Project workspaces use a single git repository initialized at the workspace root. -Do not create nested git repositories inside the workspace. If your project code -lives in a subdirectory, it is tracked by the root repo. +Do not create nested git repositories inside the workspace -- including inside +the project subdirectory. If your project code lives in a subdirectory, it is +tracked by the root repo. + +**Changing the launch directory:** + +The `launch_dir` field in `task.yaml` controls which subdirectory the agent is launched into on `ctask resume`, `ctask last`, and `ctask open`. By default it is set to the project slug. To launch from the workspace root instead, edit `task.yaml` and set `launch_dir: ""`. To launch from a deeper path (e.g., `backend/api`), set `launch_dir: "backend/api"`. No CLI command is provided -- manual edit is the only supported way to change it. + +If `launch_dir` points to a directory that does not exist (deleted, renamed) or is not a directory, ctask prints a warning and falls back to the workspace root. Absolute paths and paths that escape the workspace via `..` are errors and abort the session. ### Seed directories @@ -194,7 +220,7 @@ ctask info auth-bug ctask info backup ``` -Shows: slug, title, category, status, mode, agent, created/updated timestamps, path, and directory contents. +Shows: slug, title, category, status, mode, agent, created/updated timestamps, path, and directory contents. For v0.5 project workspaces, also shows `Launch dir`, `Launch path`, and `Dir exists`. --- @@ -272,6 +298,7 @@ Exits 0 if all checks pass, 1 if any fail. Each failure includes a concrete fix [PASS] Workspaces found: 5 tasks (2 archived) [INFO] General seed directory: not configured (using built-in defaults) [INFO] Project seed directory: not configured (using built-in defaults) + [INFO] CTASK_PROJECT_ROOT: not set (projects discovered under C:\Users\Warren\ai-workspaces\projects) 5 checks passed, 0 failed ``` @@ -320,6 +347,8 @@ If multiple workspaces match, all matches are printed and the command exits. If Archived workspaces are excluded from matching by default. Use `--all` where supported to include them. +By default, queries search `$CTASK_ROOT` (including its `projects/` subdirectory) plus `$CTASK_PROJECT_ROOT` when that variable is set. Projects created without `CTASK_PROJECT_ROOT` are therefore discoverable from any shell without additional configuration. Custom `CTASK_PROJECT_ROOT` paths must be set (recommended: at user scope) in any shell where you want those projects findable. + --- ## Environment Variables @@ -334,6 +363,7 @@ ctask exports these into every child session: | `CTASK_WORKSPACE` | Full workspace path | | `CTASK_CATEGORY` | Category name | | `CTASK_TYPE` | `task` or `project` | +| `CTASK_LAUNCH_DIR` | Project subdirectory (v0.5); empty for tasks and pre-v0.5 projects | Configure ctask behavior with: