ctask/v0.3-spec.md

ctask v0.3 Feature Spec — Seed Templates & Project Mode

Theme

v0.1 = create and resume workspaces v0.2 = understand and continue workspaces later v0.3 = personalize workspaces and support longer-lived project work

Scope

Three deliverables:

1. User seed directory
2. Improved default CLAUDE.md with file placement conventions
3. Project mode via --project flag

1. User Seed Directory

Purpose

Users don't reliably customize CLAUDE.md or workspace structure by hand. A seed directory lets users define their preferred starting files once and have them applied to every new workspace automatically.

How it works

On ctask new, after creating the workspace directory:

1. Write ctask's built-in default seed files (CLAUDE.md, notes.md)
2. Check if a user seed directory exists
3. If it exists, copy its contents into the workspace, overwriting any built-in defaults

User seed wins. If the user provides their own CLAUDE.md, it replaces the built-in one entirely. If the user provides files that don't exist in the defaults (e.g., .cursorrules, mcp-config.json, a docs/ directory), those are added.

Seed directory location

Platform	Path
Windows	%APPDATA%\ctask\seed\
Linux	~/.config/ctask/seed/
macOS	~/.config/ctask/seed/

The location can be overridden via CTASK_SEED_DIR environment variable.

What goes in the seed directory

Anything. ctask copies the entire contents recursively. Common examples:

• CLAUDE.md — personalized agent instructions, MCP config notes, coding conventions
• notes.md — custom notes template
• .cursorrules — for Cursor users
• docs/ — pre-created documentation directory
• reference/ — standard reference docs the user wants in every workspace

Rules

• ctask does not validate seed contents. It copies files, nothing more.
• Seed files are only applied on ctask new. Resuming an existing workspace does not re-apply seeds.
• If the seed directory does not exist, ctask uses built-in defaults silently. No warning.
• Subdirectories in the seed directory are preserved (copied recursively).
• task.yaml in the seed directory is ignored if present — ctask always generates its own.
• .ctask/ in the seed directory is ignored if present.

Project-specific seeds

When --project is used (see §3), ctask checks for a second seed directory:

Platform	Path
Windows	%APPDATA%\ctask\seed-project\
Linux	~/.config/ctask/seed-project/
macOS	~/.config/ctask/seed-project/

Override via CTASK_SEED_PROJECT_DIR.

Resolution order for --project:

1. Write built-in project defaults (project-oriented CLAUDE.md and notes.md — not the generic task defaults)
2. Apply general user seed on top (if exists)
3. Apply project seed on top (if exists)

This means the starting point for a project workspace is always the built-in project CLAUDE.md (see §3), not the generic task CLAUDE.md. The general seed can then customize it, and the project seed can further specialize it. If no seed directories exist, the built-in project defaults are used as-is.

Examples

# User has a custom seed
ls ~/.config/ctask/seed/
  CLAUDE.md
  notes.md
  docs/

# Every new workspace gets those files
ctask new "api cleanup"

# User has a project-specific seed too
ls ~/.config/ctask/seed-project/
  CLAUDE.md          # richer, project-oriented version
  src/
  docs/
  .gitignore

# Project workspaces get the project seed
ctask new --project "billing service"

2. Improved Default CLAUDE.md

Purpose

The built-in CLAUDE.md should be useful out of the box, even if the user never creates a seed directory. The current version is too bare — it gives general workspace scope guidance but says nothing about file organization.

New default CLAUDE.md content

# Workspace Guidelines

This is a ctask workspace. Prefer operating inside this directory unless explicitly instructed otherwise.

## File Placement

- Source code and scripts → workspace root or `src/`
- Documentation, summaries, reports → `docs/`
- Deliverables and exports → `output/`
- Reference material and imported files → `context/`
- Do not place non-code outputs (docs, summaries, exports) in the workspace root

## Conventions

- Do not install global packages or modify system files unless asked
- Record important assumptions and actions in notes.md
- Keep the workspace root clean — use subdirectories for organization

## Session Handoff

Before ending a session, append a brief summary to notes.md with:

- What was accomplished
- Key decisions made
- Open follow-ups or unfinished work
- How to continue from here

Keep it concise — a few bullet points is enough.

Rules

• This is the built-in default. Users override it via the seed directory.
• The session handoff section from v0.2 is preserved.
• File placement conventions are advisory. The agent may or may not follow them, but having them is significantly better than not.

3. Project Mode

Purpose

Support longer-lived project work using the same ctask workflow. A project workspace is not fundamentally different from a task workspace — it has the same lifecycle commands, session logging, and metadata. What changes is the default structure, expected longevity, and optionally the workspace root.

How it works

Add a --project flag to ctask new:

ctask new --project "billing service"
ctask new --project -c backend "billing service"

What --project changes

Aspect	Task (default)	Project
task.yaml type field	type: task	type: project
Default category	general	projects
Seed source	general seed	general seed + project seed overlay
Workspace root	$CTASK_ROOT	$CTASK_PROJECT_ROOT (falls back to $CTASK_ROOT)
Git initialization	no	yes, git init if git is available
Default CLAUDE.md	standard	project-oriented (from project seed, or built-in project default)

New metadata field

Add type to task.yaml:

type: "project"    # task | project

Existing workspaces without a type field are treated as task (backward compatible).

Implementation note: every code path that reads type from task.yaml must handle the missing-field case consistently: list, resume, info, last, delete, status line display, and any future filtering. Default to "task" when the field is absent or empty. Do not require a migration step for existing workspaces.

Separate project root (optional)

Users who want projects in a different location can set:

CTASK_PROJECT_ROOT=~/projects

When CTASK_PROJECT_ROOT is set, project workspaces are created directly under it: $CTASK_PROJECT_ROOT/<date>_<slug>. The default projects category is not appended — the user has already chosen a dedicated location. If the user explicitly passes -c <category>, that category subdirectory is used within the project root.

When CTASK_PROJECT_ROOT is not set, projects go under $CTASK_ROOT/projects/<date>_<slug> using the default projects category.

Git initialization

When --project is used and git is on PATH:

1. Run git init in the workspace directory
2. Create a minimal .gitignore (ignore .ctask/, logs/sessions.log)
3. If git is not available, do not error — print an informational note: [ctask] git not found; skipped repository initialization

Filtering

ctask list gains a --projects flag:

ctask list                       # active tasks only (type: task, or no type field)
ctask list --projects            # active projects only (type: project)
ctask list --all                 # active tasks including archived tasks
ctask list --projects --all      # active projects including archived projects

The --all flag controls archived visibility only. The --projects flag controls type filtering only. They combine naturally: --projects --all means "all projects, including archived ones."

ctask resume, ctask open, ctask info search across both tasks and projects by default. No type filtering needed — if the user knows the name, they find it.

Built-in project CLAUDE.md default

If no project seed directory exists, ctask uses a built-in project-oriented CLAUDE.md:

# Project Workspace Guidelines

This is a ctask project workspace — a long-lived working environment, not a disposable task.

## File Placement

- Source code → `src/` or workspace root
- Documentation → `docs/`
- Deliverables and exports → `output/`
- Reference material → `context/`
- Tests → `tests/`
- Configuration files → workspace root
- Do not place non-code outputs in the workspace root

## Conventions

- This project uses git. Commit meaningful changes with clear messages.
- Do not install global packages or modify system files unless asked.
- Record important assumptions and actions in notes.md.
- Keep the workspace root clean.

## Session Handoff

Before ending a session, append a brief summary to notes.md with:

- What was accomplished
- Key decisions made
- Open follow-ups or unfinished work
- How to continue from here

Examples

# Create a project (no CTASK_PROJECT_ROOT set)
ctask new --project "billing service"
# → ~/ai-workspaces/projects/2026-04-10_billing-service/
# → git initialized, project CLAUDE.md seeded

# Create a project in a separate root
CTASK_PROJECT_ROOT=~/projects ctask new --project "billing service"
# → ~/projects/2026-04-10_billing-service/
# (no category subdirectory — CTASK_PROJECT_ROOT is the final root)

# Create a project in a separate root with explicit category
CTASK_PROJECT_ROOT=~/projects ctask new --project -c backend "billing service"
# → ~/projects/backend/2026-04-10_billing-service/

# List only projects
ctask list --projects

# Resume works the same
ctask resume billing-service

Non-Goals for v0.3

• No template inheritance or multi-layer seed precedence beyond general + project
• No ctask init-seed scaffolding command (users create the seed directory manually)
• No subtask / subfolder command
• No automatic seed updates to existing workspaces
• No per-category seed directories (only general and project)
• No container mode (still deferred)

Environment Variables (new in v0.3)

Read by ctask (user-configurable input)

Variable	Default	Description
CTASK_SEED_DIR	~/.config/ctask/seed/ (Unix) or %APPDATA%\ctask\seed\ (Windows)	General seed directory
CTASK_SEED_PROJECT_DIR	~/.config/ctask/seed-project/ (Unix) or %APPDATA%\ctask\seed-project\ (Windows)	Project seed directory
CTASK_PROJECT_ROOT	Falls back to $CTASK_ROOT	Workspace root for projects

Set by ctask (exported into sessions)

Variable	Value
CTASK_TYPE	task or project

Added to the existing set of exported variables (CTASK_TASK, CTASK_MODE, CTASK_ROOT, CTASK_WORKSPACE, CTASK_CATEGORY).

Build Order

1. Improved default CLAUDE.md (smallest change, immediate value)
2. User seed directory support in ctask new
3. Project seed directory support
4. --project flag with type field, default category, and project root
5. Git initialization for project mode
6. --projects filter in ctask list
7. CTASK_TYPE export
8. Update status line helper to show type when in a project
9. Update ctask doctor to check seed directory existence (informational, not a failure)
10. Testing and validation