ctask/v0.2-spec.md

ctask v0.2 Feature Spec — Session Traceability & Resumability

Theme

v0.1 = create and resume workspaces v0.2 = understand and continue workspaces later

Scope

Five deliverables:

1. Automatic session snapshot logging
2. Improved seeded CLAUDE.md with handoff instructions
3. ctask doctor
4. ctask last
5. ctask delete

1. Automatic Session Snapshot Logging

Purpose

When a developer returns to a workspace after hours or days, they need to immediately understand what happened last time — without relying on memory or manual note-taking.

How it works

ctask wraps the agent/shell launch so it can run logic before and after the session.

On session start:

1. Create .ctask/ directory in workspace if it doesn't exist
2. Capture a file manifest: relative path, size in bytes, and modification timestamp for every file in the workspace (excluding .ctask/ itself)
3. Write manifest to .ctask/manifest-start.json
4. Append a session-start entry to logs/sessions.log

On session end (agent/shell process exits):

1. Capture a second manifest using the same format
2. Diff against the start manifest to produce: files added, files modified (size or mtime changed), files deleted
3. Append a session-end entry to logs/sessions.log with the diff summary
4. Clean up .ctask/manifest-start.json (or keep for debugging — implementer's choice)
5. Exit with the child process's exit code

Implementation change

v0.1 uses exec to replace the ctask process with the agent. v0.2 must change this to spawn a child process and wait for it, so ctask can run post-session logic. This applies to new, resume, and open.

Session snapshot logging runs for any command that launches an agent or shell session:

• ctask new (when it launches into agent or shell)
• ctask resume
• ctask open
• ctask last (delegates to resume)

Session snapshot logging does not run for:

• ctask new --no-launch (no session to capture)
• ctask list, ctask info, ctask archive, ctask doctor, ctask delete

On Unix: run the agent as a child process with stdin/stdout/stderr inherited, wait for exit. On Windows: same pattern using os/exec with Cmd.Run().

Do not use exec (process replacement) in v0.2.

Session log format

logs/sessions.log is a human-readable, append-only text file.

── Session 2026-04-05 14:30:22 ──
Agent:    claude
Mode:     local
Start:    2026-04-05 14:30:22
End:      2026-04-05 15:45:10
Duration: 1h 14m 48s

Added:
  output/migration-plan.md
  output/schema.sql
  context/reference.md

Modified:
  notes.md
  CLAUDE.md

Deleted:
  (none)

Notes updated: yes
────────────────────────────────

Rules

• The manifest captures only regular files, not directories
• Ignore .ctask/ contents when diffing
• Ignore task.yaml changes (ctask updates this itself, not the agent)
• Ignore logs/sessions.log changes (ctask's own logging would otherwise show as a modification every session)
• "Modified" means: file present in both start and end manifests with a different size or mtime. This is a lightweight heuristic, not content hashing.
• If the session is very short (< 5 seconds) and no files changed, still log it but with a note like "No changes detected"
• If manifest capture fails for any reason, log the error and continue — never block the user from exiting
• "Notes updated" is a simple boolean: did notes.md change between start and end?
• .ctask/manifest-start.json is deleted after successful session-end logging. If post-session logging fails, keep it and log the error.

Manifest format

.ctask/manifest-start.json:

{
  "captured_at": "2026-04-05T14:30:22Z",
  "files": [
    {"path": "notes.md", "size": 245, "mtime": "2026-04-05T14:30:20Z"},
    {"path": "CLAUDE.md", "size": 512, "mtime": "2026-04-05T14:30:20Z"},
    {"path": "task.yaml", "size": 310, "mtime": "2026-04-05T14:30:22Z"}
  ]
}

2. Improved Seeded CLAUDE.md

Purpose

Nudge the agent to leave a human-readable handoff in notes.md so the developer (or a future agent session) can understand what was accomplished and what remains.

Change

Update the seeded CLAUDE.md template to include the following instruction (in addition to existing workspace scope guidance):

## 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. This helps the developer (or a future session) resume without losing context.

Rules

• This is advisory, not enforced. The agent may or may not follow it.
• The automatic session snapshot (§1) provides the structural safety net regardless.
• Do not add complex formatting requirements — the simpler the instruction, the more likely the agent complies.

3. ctask doctor

Purpose

Verify that ctask is correctly set up and help users diagnose common configuration problems.

Command

ctask doctor

No arguments, no flags.

Checks

Check	Pass condition	Fail message
Workspace root exists	CTASK_ROOT directory exists and is writable	Workspace root not found: <path>. Create it with: mkdir <path>
Default agent on PATH	Configured agent command is found	Agent command not found: <cmd>. Install it or set CTASK_AGENT.
Status line helper exists	Status line script file exists at expected location	Status line helper not found. Run ctask setup instructions at <doc link>.
Claude Code status line configured	~/.claude/settings.json exists, contains a statusLine key with type: "command", and the command value references a file that exists on disk	Claude Code status line not configured or misconfigured. Add to ~/.claude/settings.json: <example>
Workspace root has workspaces	At least one workspace directory exists	No workspaces found. Create one with: ctask new "my first task"

Output format

ctask doctor

  ✓ Workspace root exists: ~/ai-workspaces
  ✓ Default agent found: claude
  ✗ Status line helper not found
    → Install it to: ~/.local/bin/ctask-statusline.sh
  ✓ Claude Code status line configured
  ✓ Workspaces found: 12 tasks (3 archived)

3 checks passed, 1 failed

Use ✓ and ✗ (or platform-safe equivalents if Unicode is unreliable on Windows cmd.exe). Provide actionable fix instructions for every failure.

Rules

• doctor never modifies anything — read-only
• doctor should work even if ctask has never been used (no workspaces yet)
• exit 0 if all checks pass, exit 1 if any fail
• check paths using platform-appropriate logic (Windows vs Unix)

4. ctask last

Purpose

Instantly resume the most recently updated workspace without remembering its name.

Command

ctask last [options]

Options

Flag	Short	Default	Description
--shell		off	Open shell instead of agent
--agent	-a	from task.yaml	Override agent command

Behavior

1. Scan all non-archived workspaces
2. Find the one with the most recent updated_at in task.yaml
3. Behave exactly like ctask resume <that-workspace>

If no workspaces exist, print an error and exit 1.

Examples

# Resume most recent workspace
ctask last

# Open most recent workspace in shell
ctask last --shell

Output

Same as resume — launch banner, then agent or shell.

5. ctask delete

Purpose

Permanently remove a workspace directory when it's no longer needed.

Command

ctask delete <query> [options]

Options

Flag	Short	Default	Description
--force	-f	off	Skip confirmation prompt
--all	-a	off	Include archived workspaces in query resolution

Behavior

1. Resolve workspace (same query rules as resume)
2. Print workspace path and contents summary (file count, total size)
3. Prompt for confirmation: Delete <path>? This cannot be undone. [y/N]
4. If confirmed (or --force), remove the entire workspace directory
5. Print confirmation message

Output

ctask delete arch-notes

  Workspace: ~/ai-workspaces/general/2026-04-05_arch-notes
  Files: 8 (24 KB)

  Delete this workspace? This cannot be undone. [y/N] y

[ctask] deleted: general/2026-04-05_arch-notes

Rules

• Confirmation is required by default. --force skips it.
• Delete removes the entire directory tree, not just ctask metadata.
• Archived workspaces are excluded from query resolution unless --all is passed (consistent with other commands).
• If the workspace is the most recently updated one, print a note: "This was your most recent workspace."
• If CTASK_WORKSPACE is set and matches the resolved target (i.e., the user is inside an active ctask session targeting this workspace), refuse to delete and print: "Cannot delete the active workspace. Exit the session first." This check applies even with --force.

Non-Goals for v0.2

• No terminal output recording or command history capture
• No automatic agent-generated summaries (the CLAUDE.md nudge is advisory only)
• No container mode (still deferred)
• No ctask summarize command (the automatic snapshot replaces the need)
• No manifest history / multiple snapshots per workspace (one start manifest is enough)

Build Order

1. Change launch model from exec to child-process-and-wait (touches new, resume, open)
2. Manifest capture (start snapshot)
3. Session log writer (end snapshot + diff + append to logs/sessions.log)
4. Updated CLAUDE.md template
5. ctask doctor
6. ctask last
7. ctask delete
8. Testing and validation