docs: add v0.2 spec
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
+201
@@ -0,0 +1,201 @@
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
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.
|
||||
Reference in New Issue
Block a user