mitodl/agent-kit/witan-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.

Asking the user

Several steps below ask the user to choose or type something. Ask the same way on every agent:

• If a structured question tool is actually available to you (e.g. Claude

Code's AskUserQuestion, or a question tool a Pi extension registers), use it with the header, question and options given. Where a step also needs free text, use whatever free-text entry that tool offers; if it offers none, ask for the text in a plain message.

• Otherwise, ask the same question in a normal message — number the

options, say what free-text answer is accepted — and end your turn and wait for the reply. Do not guess an answer or pick a default on the user's behalf.

Never add an option the step does not list just to get a free-text box. Either way, nothing that changes the graph (claiming a task, creating or starting a project or session) happens until the user has answered.

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.

Ask one question (see Asking the user):

• 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.

Wait for the answer before calling anything else — do not start a session or create a project on a guess.

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 (see Asking the user): "What phase is this session?" with options matching the project's valid phases: discovery, spec, implementation, delivery. List the project's current phase first, labelled "(current)", as the suggested answer — but still wait for the user to answer; do not start the session on the suggestion alone.

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, read your own platform's variable in your shell tool: echo $CLAUDE_SESSION_ID on Claude Code, echo $PI_SESSION_ID on Pi (which sets it for commands its bash tool runs), echo $CODEX_SESSION_ID on Codex. Don't use a fallback chain like ${CLAUDE_SESSION_ID:-$PI_SESSION_ID} — an agent launched from another one can inherit its id, and the chain would pick that. Use that value, not a made-up one — it is what the Stop hook (Claude Code, Codex) or the workflow extension's shutdown handler (Pi) looks the session up by to auto-close it. Only if all are empty (another agent), use any stable string unique to this session, and close the session yourself with /witan-workflow end, since nothing else can find it.

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 together (see Asking the user):

1. "Project title?" (free text)
2. "Starting phase?" (options: discovery, spec, implementation, delivery)

Do not call workflow_project_create until both are answered.

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, $PI_SESSION_ID on Pi, $CODEX_SESSION_ID on Codex). 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."