# Workspace description field: prior art and shape (https://jackin.tailrocks.com/reference/research/agent-orchestration/workspace-description-field/)



**Status**: Open — design notes backing [Workspace Description Field](/roadmap/workspace-description/) (Agent Orchestration Program, phase 1)

## Why it matters [#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](/reference/research/agent-orchestration/program-research/) 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 [#inspiration-in-multicode]

**Sources**:

* README — [Description](https://github.com/graemerocher/multicode#description)
* Source — [`lib/src/services/workspace_archive.rs`](https://github.com/graemerocher/multicode/blob/main/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 [#recommended-shape]

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

### Config [#config]

```toml
[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 [#cli]

```sh
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 <RepoFile path="crates/jackin/src/cli/workspace.rs" />.

### Console [#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) [#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 [#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 [#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](/guides/workspaces/#per-mount-isolation)'s preserved-state notices? When jackin❯ prints "preserved isolated worktree for X", it should include the description if present.

## Related work [#related-work]

* [Workspace Description Field](/roadmap/workspace-description/) — roadmap item this backs.
* [Agent Orchestration Program](/reference/research/agent-orchestration/program-research/)