typebasedio
0b21b8d3da
Adds the two new metadata fields specified for Phase 1 of v0.6 plus
the validation and defaulting helpers around them.
internal/workspace/metadata.go:
- CurrentMetaSchemaVersion = 1 constant.
- WorkspaceSection struct {Mode string} with omitempty.
- SchemaVersion int and Workspace WorkspaceSection fields added to
TaskMeta at the top of the struct. Both are omitempty so legacy
task.yaml files (no schema_version, no workspace block) round-trip
without acquiring these keys when an unrelated field is updated.
- EffectiveSchemaVersion(meta) — returns 1 for stored-value-0 legacy
workspaces; non-zero stored values are returned verbatim.
- ValidateSchemaVersion(slug, meta) — rejects stored values higher
than CurrentMetaSchemaVersion with the spec-mandated upgrade
message. Accepts 0 (legacy missing).
- ValidateWorkspaceMode(slug, meta) — rejects modes other than ""
and "native". "adopted" is reserved for v0.7.
- ReadMeta now runs both validators after unmarshal. The validation
error includes the workspace slug (derived from task.yaml's slug
field, falling back to the directory basename when the file itself
is corrupt).
internal/workspace/create.go:
- workspace.Create stamps every new meta with
SchemaVersion: CurrentMetaSchemaVersion and Workspace.Mode: "native".
This is the ONLY write site for these fields in v0.6; resume,
archive, restore, and any other path that rewrites task.yaml MUST
NOT backfill them (the "no opportunistic schema writes" invariant).
internal/workspace/schema_test.go:
- 10 tests:
* new meta written by Create contains schema_version: 1 +
workspace.mode: native (both serialization and round-trip)
* legacy meta without these fields loads with stored value 0 / ""
and EffectiveSchemaVersion returns 1
* task.yaml with schema_version: 2 is rejected with upgrade message
* task.yaml with workspace.mode: adopted is rejected
* the no-opportunistic-writes invariant is pinned for both WriteMeta
and WriteMetaLocked: a legacy file rewritten with an updated
UpdatedAt does NOT acquire schema_version or workspace: keys
* ValidateSchemaVersion accepts {0, 1}; ValidateWorkspaceMode
accepts {"", "native"}
ctask
A local CLI that creates and manages named AI-agent task workspaces.
ctask gives developers dedicated directories with consistent structure, visible session identity, environment context injection, and automatic session logging -- so you can start, resume, and organize AI-assisted work more safely and predictably.
Status
v0.2.0 -- local use, not published to any package registry. Windows-primary, cross-platform design.
Key Features
- Named workspaces with consistent layout (task metadata, notes, context, output, logs)
- Session traceability -- automatic file-change snapshot logging on every session
- Agent-agnostic -- default agent is Claude Code, but any CLI agent or shell works
- Query resolution -- find workspaces by name, slug, or substring
- Status line -- persistent session context inside Claude Code's UI
- Doctor -- verify setup and diagnose configuration problems
- Safe delete -- active workspace protection prevents accidental data loss
Install (Windows)
cd C:\Users\Warren\claude_tasks\ctask_v0.1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1
Installs to %LOCALAPPDATA%\ctask\bin. Open a new terminal after install.
See docs/install.md for full details.
Quick Start
# Verify setup
ctask doctor
# Create a new task workspace and launch Claude Code
ctask new "fix auth bug"
# List recent workspaces
ctask list
# Resume where you left off
ctask last
# Or resume a specific workspace
ctask resume auth-bug
Commands
| Command | Description |
|---|---|
ctask new [title] |
Create a new workspace and launch the agent |
ctask list |
Show recent workspaces |
ctask resume <query> |
Reopen a workspace and launch the agent |
ctask open <query> |
Open a workspace in a shell (no agent) |
ctask info <query> |
Display workspace metadata |
ctask archive <query> |
Mark a workspace as archived |
ctask last |
Resume the most recently updated workspace |
ctask doctor |
Verify ctask setup |
ctask delete <query> |
Permanently remove a workspace |
See docs/commands.md for full usage.
Status Line
ctask includes a status-line helper for Claude Code that shows session context at the bottom of the UI:
(ctask:fix-auth-bug|local) C:\Users\Warren\ai-workspaces\general\2026-04-06_fix-auth-bug
Run ctask doctor to check if the status line is configured. See docs/install.md for setup.
Uninstall
cd C:\Users\Warren\claude_tasks\ctask_v0.1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/uninstall.ps1
Removes ctask files only. Your workspaces and task data are never touched.