Workspace description field: prior art and shape

Status: Open — design notes backing Workspace Description Field (Agent Orchestration Program, phase 1)

Why it matters

jackin❯ workspace list and workspace show reveal mounts and agent bindings but not intent — operators end up encoding intent in the workspace name, which is awkward. This is the smallest feature in the Agent Orchestration Program that demonstrably improves day-to-day operator UX, and it plumbs through the same surfaces (workspace config schema, console rendering, future TUI cell rendering) that several later program items will reuse, so getting the shape right once pays forward.

Inspiration in multicode

Sources:

• README — Description
• Source — lib/src/services/workspace_archive.rs (description field is part of PersistentWorkspaceSnapshot)

multicode addresses the same "which workspace was this for again" problem with a free-text description field shown in its overview table and inline-editable from the TUI (e keystroke). The field lives on PersistentWorkspaceSnapshot.description, persisted as a JSON-shaped per-workspace metadata file at ~/.multicode/workspaces/<key>.json. The TUI exposes it through an EditDescription mode: select a row, press e, type, Enter saves, Esc cancels. No markdown rendering — descriptions are plain text, displayed verbatim. There's no length limit enforced beyond what fits the table cell. Operators treat it as a sticky reminder.

Recommended shape

A single optional string field on WorkspaceConfig, surfaced in the same three places jackin❯ already surfaces other workspace metadata.

Config

[workspaces.jackin]
workdir = "/workspace/jackin"
description = "Issue #412 isolated repro branch"

[[workspaces.jackin.mounts]]
src = "~/projects/jackin"
dst = "/workspace/jackin"
isolation = "worktree"

description is optional; absent means no description (not empty string).

CLI

jackin workspace create my-ws --workdir /workspace/x \
  --mount ~/projects/x:/workspace/x \
  --description "Issue #412 isolated repro branch"

jackin workspace edit my-ws --description "..."
jackin workspace edit my-ws --clear-description

jackin workspace show my-ws  # renders description as a top-level field
jackin workspace list        # renders a Description column (truncated)

The --clear-description flag should match the existing --clear-default-role shape in crates/jackin/src/cli/workspace.rs.

Console

workspace show adds a Description row at the top of the panel. The console's workspace picker keeps the existing list shape but appends the description as a second line under each workspace name (truncated to one line; Esc-to-collapse if it ever overflows).

Scope (V1)

• description field on WorkspaceConfig, optional string, no length cap in storage (CLI/console truncate at render time).
• workspace create --description and workspace edit --description / --clear-description.
• workspace show and workspace list render the field.
• Console workspace picker shows the description as a one-line subtitle.
• Roundtrips cleanly through TOML serialization (preserve operator whitespace; do not collapse multi-line descriptions but render only the first line in lists).

Deferred

• Markdown rendering. Descriptions are plain text.
• Per-instance descriptions (the operator might want a different description on agent-smith vs the-architect even when both reference the same workspace). Out of scope; a workspace-level field covers the 95% case.
• A separate description on role manifests (jackin.role.toml [identity].description). Useful and small; deserves its own follow-up so it can be reviewed in isolation.

Open design questions

• Should the field be a single string or an optional [description] block with text + tags? The block form is over-engineered for V1; recommend plain string.
• How does the field interact with worktree isolation's preserved-state notices? When jackin❯ prints "preserved isolated worktree for X", it should include the description if present.

Related work

• Workspace Description Field — roadmap item this backs.
• Agent Orchestration Program