witan-project-tracker

Project Tracker

Tracks engineering work across sessions from discovery through delivery. Each project is a WorkflowProject node in the witan graph. Each agent session contributes a WorkflowSession. When a project completes, a WorkflowTrace is assembled for the corpus.

The context-injection hook (Claude Code) / extension (Pi) auto-injects active project context into every session in the repo, so you rarely need to find a project slug manually.

Starting a Session: Joining an Existing Project

When the hook injects context showing an active project that matches your work:

workflow_session_start(
    project_slug="wp-add-vault-k8s-auth-a3f912",
    session_id="<$CLAUDE_SESSION_ID on Claude Code, or any stable session UUID>",
    phase="implementation",
)

Link the session before doing substantive work. The phase should reflect what this particular session will focus on, not necessarily the project's current overall phase.

Hold on to the session_slug in the returned handle. Pass it to memory_store and workflow_trace_mine so what you record this session is attributed to it, and to workflow_session_end when you close. The protocol carries no session state, so the handle is the only link between these calls.

Starting a Session: Creating a New Project

If no active project in the injected context matches the work:

workflow_project_create(
    title="Add Vault K8s auth to ol-django",
    description="Wire Vault K8s auth using hvac for secret injection at runtime. Driven by compliance requirement to stop using static env secrets.",
    phase="discovery",
    github_issue="github.com/mitodl/ol-django/issues/847",
    tags=["vault", "kubernetes", "secrets"],
)

Then immediately start a session:

workflow_session_start(
    project_slug="<slug returned above>",
    session_id="<session UUID>",
    phase="discovery",
)

The call is re-entrant: if it returns existed: true, a session for this (project_slug, session_id) was already open and you've been handed that same handle back — safe to retry after a transport error without duplicating the session. Any newly-supplied repo and tags are merged in; phase stays at what the first call set. Once a session has been ended, the same session_id starts a fresh one, so several working stints under one Claude Code session each get their own record.