Witan Workflow

---
name: witan-workflow
description: >
  Interactive workflow session manager. Call at the start of any session to
  link it to a tracked project. Lists active WorkflowProjects for the current
  repo, lets the user pick one (or create a new project), then calls
  workflow_session_start to register the session in the graph. Also supports
  ending a session (/witan-workflow end) or listing all projects
  (/witan-workflow list). Requires the witan MCP server.
license: BSD-3-Clause
metadata:
  category: workflow
---

# Workflow Session Manager

Interactive entry point for the workflow tracking system. Invoke with `/witan-workflow`
at the start of a session, or `/witan-workflow end` before stopping.

## On invocation

**Step 1 — Check args.**

If the user passed `list`: call `workflow_project_list()` with no filters,
print a table of all projects (slug, title, phase, status, repo), and stop.

If the user passed `end`: go to the **End session** section below.

If the user passed `new`: skip to **Create new project** below.

Otherwise (no args or unrecognized): proceed to Step 2.

**Step 2 — List active projects.**

Call `workflow_project_list()` (no args — defaults to active projects in the
current repo). If the MCP call fails, tell the user the witan server
is not connected and stop.

**Step 3 — Ask the user what to link to.**

Build an `AskUserQuestion` with one question:

- Header: "Link session"
- Question: "Which project does this session belong to?"
- If there are 1–3 active projects: offer each as a labelled option
  (label = title, description = "slug: `{slug}` · phase: {phase}"), plus
  "Create new project" and (if >0 projects exist) "None / untracked".
- If there are 0 active projects: offer "Create new project" and
  "None / untracked" only.
- If there are 4+ active projects: list them as text, ask the user to type a
  slug or "new", then use `workflow_project_get(slug)` to confirm the choice.

**Step 4 — Handle the response.**

If **"None / untracked"**: do nothing, stop. The session won't be tracked.

If **"Create new project"**: go to **Create new project** below, then
continue to Step 5.

Otherwise: the user picked an existing project. Note its slug and phase.

**Step 5 — Ask for the session phase.**

Ask: "What phase is this session?" with options matching the project's valid
phases: `discovery`, `spec`, `implementation`, `delivery`. Pre-select the
project's current phase as the default (first option, labelled "(current)").

**Step 6 — Start the session.**

Call:

```
workflow_session_start(
    project_slug="<chosen slug>",
    session_id="<session id — see below>",
    phase="<chosen phase>",
)
```

For the session id: on Claude Code, run `echo $CLAUDE_SESSION_ID` via Bash. If
that variable is empty (e.g. under Pi), use a short random hex string instead
(read `/proc/sys/kernel/random/uuid` and take the first 8 chars).

Keep the returned `session_slug` for the rest of the session: pass it to
`memory_store` (and `workflow_trace_mine`) so anything you record is attributed to
this session, and to `workflow_session_end` when you close. The protocol carries
no session state, so the handle is the only thing tying those calls together.

Confirm to the user: "Session linked to **{title}** (`{session_slug}`). Call
`/witan-workflow end` before you stop, or the Stop hook will auto-close it with a
placeholder summary."

---

## Create new project

Ask the user two questions in one `AskUserQuestion` call:

1. "Project title?" (free text — use "Other" as the entry point)
2. "Starting phase?" (options: discovery, spec, implementation, delivery)

Then call:

```
workflow_project_create(
    title="<title>",
    description="<brief description — ask if not obvious from the title>",
    phase="<phase>",
)
```

Return the new project slug and continue to Step 5 of the main flow.

---

## End session

Call `workflow_project_list()` to find active projects in this repo, then read
the `session_slug` from this session's state file in the system temp dir
(`$TMPDIR`, else the platform default — run `python -c "import tempfile;
print(tempfile.gettempdir())"` if unsure): it is
`workflow-session-<session id>.json`, where `<session id>` is the value passed
to `workflow_session_start` (`$CLAUDE_SESSION_ID` on Claude Code). If you no
longer have the id, pick the newest matching `workflow-session-*.json` in that
directory.

Ask the user for a session summary: "Briefly describe what this session
accomplished (will be saved to the workflow corpus)."

Call:

```
workflow_session_end(
    session_slug="<slug from state file>",
    summary="<user's summary>",
    files_changed=["<git diff --name-only HEAD, limited to 50 files>"],
)
```

Confirm: "Session closed. The Stop hook will not need to auto-close it."