From dacd8018cf5a0454147f946dbcd8cc2454f7b8a2 Mon Sep 17 00:00:00 2001 From: typebasedio Date: Fri, 10 Apr 2026 14:57:00 -0400 Subject: [PATCH] docs(v0.3): document --project, --projects, seed dirs, CTASK_TYPE 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. --- docs/commands.md | 56 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 53 insertions(+), 3 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 049171f..3e37346 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -2,7 +2,7 @@ ## ctask new -Create a new task workspace and launch the agent. +Create a new task or project workspace and launch the agent. ``` ctask new [title] [flags] @@ -14,7 +14,8 @@ If title is omitted, generates `task-HHMMSS`. | Flag | Short | Default | Description | |------|-------|---------|-------------| -| `--category` | `-c` | `general` | Workspace category subdirectory | +| `--category` | `-c` | `general` (task) / `projects` (project) | Workspace category subdirectory | +| `--project` | | off | Create a long-lived project workspace (uses `CTASK_PROJECT_ROOT` if set, runs `git init`, project CLAUDE.md) | | `--shell` | | off | Open interactive shell instead of agent | | `--agent` | `-a` | `claude` | Command to exec as the agent | | `--no-launch` | | off | Create workspace only, do not launch | @@ -29,10 +30,41 @@ ctask new --no-launch "json cleanup" ctask new --shell "test env" ctask new --agent aider "refactor api" ctask new +ctask new --project "billing service" +ctask new --project -c backend "billing service" ``` When `--no-launch` is used, no session is started and no session log is written. +### Project mode (`--project`) + +`--project` is a thin variation on the normal task workflow for longer-lived work. It changes: + +- `task.yaml` records `type: project` +- 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 + +**Project root semantics:** + +- `CTASK_PROJECT_ROOT` not set: workspace goes under `$CTASK_ROOT/projects/_` (default category `projects` is appended) +- `CTASK_PROJECT_ROOT` set, no `-c`: workspace goes directly under `$CTASK_PROJECT_ROOT/_` (no `projects/` subdirectory is appended) +- `CTASK_PROJECT_ROOT` set, explicit `-c `: workspace goes under `$CTASK_PROJECT_ROOT//_` + +### Seed directories + +On `ctask new`, after writing the built-in defaults, ctask copies the contents of an optional user seed directory into the workspace. Files in the seed directory overwrite the built-in defaults; subdirectories are preserved recursively. `task.yaml` and `.ctask/` at the seed root are always skipped. + +| Variable | Default (Unix) | Default (Windows) | +|----------|---------------|-------------------| +| `CTASK_SEED_DIR` | `~/.config/ctask/seed/` | `%APPDATA%\ctask\seed\` | +| `CTASK_SEED_PROJECT_DIR` | `~/.config/ctask/seed-project/` | `%APPDATA%\ctask\seed-project\` | + +The general seed is applied to every workspace. The project seed is applied **only** when `--project` is set, on top of the general seed (project seed wins). Both directories are optional; missing directories are silently ignored. + --- ## ctask list @@ -48,6 +80,7 @@ ctask list [flags] | Flag | Short | Default | Description | |------|-------|---------|-------------| | `--all` | `-a` | off | Include archived workspaces | +| `--projects` | | off | Show project workspaces instead of task workspaces | | `--category` | `-c` | all | Filter by category | | `--limit` | `-n` | 20 | Maximum entries to show | @@ -56,11 +89,22 @@ ctask list [flags] ```powershell ctask list ctask list --all +ctask list --projects +ctask list --projects --all ctask list -c scripts -n 5 ``` Output columns: status, mode, category, date, slug. +The `--all` flag controls archived visibility only. The `--projects` flag controls type filtering only. They combine independently: + +- `ctask list` -- active tasks only +- `ctask list --all` -- active + archived tasks +- `ctask list --projects` -- active projects only +- `ctask list --projects --all` -- active + archived projects + +Workspaces created before v0.3 (which have no `type` field in `task.yaml`) are treated as tasks. + --- ## ctask resume @@ -206,6 +250,8 @@ Checks: Exits 0 if all checks pass, 1 if any fail. Each failure includes a concrete fix instruction. +v0.3 also reports the resolved general and project seed directory paths as informational `[INFO]` lines. These do not contribute to the pass/fail count -- absent seed directories are normal and supported. + **Example output:** ``` @@ -275,13 +321,17 @@ ctask exports these into every child session: | `CTASK_ROOT` | Resolved workspace root path | | `CTASK_WORKSPACE` | Full workspace path | | `CTASK_CATEGORY` | Category name | +| `CTASK_TYPE` | `task` or `project` | Configure ctask behavior with: | Variable | Default | Description | |----------|---------|-------------| -| `CTASK_ROOT` | `%USERPROFILE%\ai-workspaces` | Workspace root directory | +| `CTASK_ROOT` | `%USERPROFILE%\ai-workspaces` (Windows) / `~/ai-workspaces` (Unix) | Workspace root directory | | `CTASK_AGENT` | `claude` | Default agent command | +| `CTASK_PROJECT_ROOT` | (none) | Workspace root for projects. When set, project workspaces are created directly under this path (no doubled `projects/` segment unless `-c` is passed). | +| `CTASK_SEED_DIR` | `%APPDATA%\ctask\seed\` (Windows) / `~/.config/ctask/seed/` (Unix) | General user seed directory copied into every new workspace. | +| `CTASK_SEED_PROJECT_DIR` | `%APPDATA%\ctask\seed-project\` (Windows) / `~/.config/ctask/seed-project/` (Unix) | Project seed directory copied only for `--project` workspaces (overlay on top of the general seed). | ---