ctask/mvp-contract.md

ctask — MVP Contract (v0.1)

1. Purpose

ctask is a local CLI that creates and manages named AI-agent task workspaces so developers can start, resume, and organize work more safely and predictably. It provides dedicated task directories with consistent structure, visible session identity, environment context injection, and optional container isolation. It is agent-agnostic — the default agent is Claude Code, but any command-line agent or shell can be launched.

2. Must-Have Commands

Command	Description
ctask new [title]	Create a new task workspace and launch the agent in it
ctask list	Show recent workspaces, reverse-chronological
ctask resume <query>	Reopen an existing workspace by name/slug match
ctask open <query>	Open a workspace directory without launching the agent
ctask info <query>	Display metadata and path for a workspace
ctask archive <query>	Mark a workspace as archived (status flag, workspace stays in place)

Flags (apply across commands where relevant)

Flag	Description
-c, --category <name>	Workspace category (default: general)
--container	Request container mode (deferred to v0.2 — prints notice in v0.1)
--shell	Open an interactive shell instead of the agent
--agent <command>	Override the default agent command
-h, --help	Show help

Resolution rules for <query>

1. Exact directory name match under <root>/*/* → use it
2. Exact slug match (portion after date prefix) → use it
3. Case-insensitive substring match against slug → use if unique
4. Multiple matches → print all and exit non-zero
5. No matches → error

Archived workspaces are excluded from matching unless --all is passed (where supported).

3. Workspace Layout

Every task workspace contains:

~/ai-workspaces/<category>/<YYYY-MM-DD>_<slug>/
├── task.yaml          # Task metadata (machine-managed)
├── CLAUDE.md          # Advisory workspace scope guidelines (not security enforcement)
├── notes.md           # Freeform task log (human/agent-managed)
├── context/           # Additional reference docs (user-managed, not seeded)
├── output/            # Task deliverables and artifacts
└── logs/              # Session logs (future use, empty in v0.1)

Seed files

On ctask new:

• task.yaml — populated with initial metadata (see §4)
• notes.md — skeleton with Purpose / Constraints / Actions / Results headings
• CLAUDE.md — advisory workspace scope guidelines (placed in root so Claude Code finds it automatically)

Seed files are only created if they do not already exist (safe for resume/reopen).

Workspace root

Default: ~/ai-workspaces

Override via: CTASK_ROOT environment variable

Categories

Predefined suggestions: general, scripts, research, risky

Any string is accepted. Categories are just subdirectories — no registry.

4. Task Metadata

task.yaml contains only:

id: "20260405-143022"           # YYYYMMDD-HHMMSS, unique enough
slug: "arch-notes"
title: "arch notes"
created_at: "2026-04-05T14:30:22Z"
updated_at: "2026-04-05T15:12:00Z"
status: "active"                # active | archived
category: "general"
mode: "local"                   # local | container
agent: "claude"                 # command used to launch
workspace_path: "/home/warren/ai-workspaces/general/20260405_arch-notes"
archived_at: null               # set by ctask archive, null while active

updated_at is refreshed on every resume or open.

No additional fields in v0.1. Schema grows only when a real need appears.

5. Launch Behavior

On ctask new

1. Compute slug from title (lowercase, alphanumeric + hyphens)
2. If workspace with same date+slug already exists, append -2, -3, etc.
3. Create workspace directory under <root>/<category>/<date>_<slug>
4. Write seed files (task.yaml, notes.md, CLAUDE.md)
5. Export environment variables (see below)
6. Print launch banner
7. cd into workspace and exec the agent (or shell if --shell)

On ctask resume

1. Resolve workspace by query (see §2 resolution rules)
2. Update updated_at in task.yaml
3. Export environment variables
4. Print launch banner
5. cd into workspace and exec the agent (or shell)

Environment variables (set for every session)

Variable	Value
CTASK_TASK	Slug (e.g., arch-notes)
CTASK_MODE	local or container
CTASK_ROOT	Workspace root path
CTASK_WORKSPACE	Full path to current workspace
CTASK_CATEGORY	Category name

These are available to the agent, status line scripts, and shell prompts.

Launch banner (printed before exec)

[ctask] local :: arch-notes
[ctask] ~/ai-workspaces/general/2026-04-05_arch-notes

Shell prompt prefix (for --shell mode only)

(ctask:arch-notes|local) warren@host:~$

Set via ephemeral PS1 override. No permanent shell config changes.

Container mode (v0.2 — deferred from initial release)

Container mode uses a persistent named container (ctask-sandbox). It is deferred from the initial v0.1 release to keep scope focused on the workspace lifecycle, which is the core value. The --container flag will be accepted but will print a message that container mode is not yet available.

Design intent for v0.2: Linux-only, Podman-first (Docker fallback), Claude Code only inside the container. Mount $CTASK_ROOT at /workspaces. No other host directories mounted. Agent auth done once manually after first container creation.

6. Explicit Non-Goals for v0.1

• No plugin system. Agent is a command string, not an interface.
• No elevated helper / privilege adapter. Sudo policy is separate from ctask.
• No task templates. Every workspace gets the same seed files.
• No built-in session logging. logs/ directory exists but ctask does not populate it.
• No agent abstraction layer. Swap agents via --agent <cmd> flag, not adapters.
• No container orchestration. Container mode is one persistent sandbox, not per-task containers.
• No GUI, no TUI beyond the CLI.
• No cloud sync, no remote sharing.

7. Platform Target

Cross-platform from the start: Windows, Linux, macOS. Primary development and testing on Windows.

Go's standard library handles the main platform differences (path separators via filepath, environment via os). The only platform-specific concerns are:

• Shell spawning: Use cmd.exe or PowerShell on Windows, user's $SHELL or bash on Unix
• Default workspace root: %USERPROFILE%\ai-workspaces on Windows, ~/ai-workspaces on Unix
• Status line helper: Provide both a bash script and a PowerShell script

Keep platform-specific code isolated behind small helper functions. Do not introduce build tags or platform abstraction layers unless a concrete need appears.

8. Status Line Support

The status line is an MVP deliverable, not a future enhancement. It provides persistent visible session context inside Claude Code's UI.

Deliverables

• A small status line helper script (bash + PowerShell variants) that reads ctask environment variables and prints a formatted context string
• Brief setup instructions for wiring it into Claude Code's statusLine configuration in ~/.claude/settings.json
• A note explaining the fallback approach for non-Claude agents (ephemeral shell prompt prefix)

Output format

(ctask:arch-notes|local) ~/ai-workspaces/general/2026-04-05_arch-notes

When CTASK_TASK is not set (normal non-ctask Claude session), the script should output nothing or fall through to other status line content.

Source of truth

The script reads only from environment variables — no file parsing, no subprocess calls:

• CTASK_TASK — task slug
• CTASK_MODE — execution mode
• CTASK_WORKSPACE — full workspace path
• CTASK_CATEGORY — category (optional, include if concise)

Fallback for non-Claude agents

For open and resume --shell, the ephemeral PS1 / PROMPT prefix remains the generic fallback for tools that do not support a dedicated status line hook.