session-tracking

name	session-tracking
description	This skill should be used by the kon orchestrator at the start of every command and after every agent step, to write a JSON session file to ~/.kon/projects/<repo-name>/sessions/ that the dashboard reads.

Session Tracking

Owner: orchestrator Consumers: all /kon:* commands (including /kon:ask)

Core principles (always): follow skills/core-principles — record session state accurately; don't hide blocked or failed stages.

The orchestrator writes and updates a session file so scripts/dashboard.py can display live status and a clickable log of every run.

Session directory layout

Each run gets one directory — delete the folder (dashboard 🗑) and all artifacts go with it:

~/.kon/projects/<repo-name>/sessions/<session-id>/
  session.json          # status, log, pipeline steps
  summary.md            # Nodoka debrief (optional)
  plan.md               # Mugi plan
  explore.md            # Azusa exploration (/kon:team, /kon:design)
  understanding.md      # Pre-plan Q&A (team, design, debug — orchestrator)
  review.md             # Mio review (team, quick, review, debug)
  pr-review.md          # Mio holistic PR review (/kon:review-pr)
  issue-summary.md      # Jun issue summary (/kon:describe-issue)
  hunt.md              # Azusa bug hunt (/kon:hunt)
  debug.md              # Azusa/Mugi debug notes (/kon:debug)
  design-debate.md      # design debate (/kon:design)
  review-rubric.md      # Mugi rubric (/kon:review --rubric)

Resolve paths from the orchestrator:

SID=$(python3 $KON_ROOT/scripts/kon_session.py init --command "/kon:team" --task "...")
SESSION_DIR=$(python3 $KON_ROOT/scripts/kon_session.py session-dir --id "$SID")
PLAN_FILE=$(python3 $KON_ROOT/scripts/kon_session.py artifact-path --id "$SID" --name plan.md)

Pass PLAN_FILE, SESSION_DIR, etc. in Task prompts. Legacy flat files (.kon/plan-<id>.md, sessions/<id>.json) are still removed on delete if present.

Session file location

~/.kon/projects/<repo-name>/sessions/<session-id>/session.json (override root with KON_DATA_DIR)

<repo-name> is the git repo root directory name (e.g. kon for ~/Desktop/kon). Created automatically on Cursor session start via ensure_project_dir hook (creates the directory only).

Auto-init: when you send a /kon:* slash command, beforeSubmitPrompt → init_kon_session.py writes the session JSON under ~/.kon/projects/<repo>/sessions/ before the agent runs. Orchestrators should still call init if the hook is not installed; duplicate init is safe (supersedes prior open sessions).

Session history lives outside the project repo. Only .kon/todos.json stays project-local (committable).

Session ID format: YYYYMMDD-HHMMSS-<task-slug> where task-slug = first 4 words of the task, lowercased, spaces → hyphens.

Example: 20260617-203042-add-email-validation

Schema

{
  "id": "20260617-203042-add-email-validation",
  "task": "add email validation to auth.py",
  "command": "/kon:team",
  "project_path": "/Users/you/projects/myapp",
  "started_at": "2026-06-17T20:30:42Z",
  "status": "in_progress",
  "current_agent": "Yui",
  "steps_completed": ["Azusa", "Mugi"],
  "steps_pending": ["Sawako", "Mio", "Nodoka"],
  "log": [
    {"ts": "2026-06-17T20:30:43Z", "agent":   
          
           
  

Session lifecycle

in_progress  →  waiting  →  completed
                    ↓
                 blocked

• in_progress — agents are actively running
• waiting — pipeline commands finished (/kon:team, …) — stays open until user acts
• completed — user ran /kon:finish / dashboard ✓, or one-shot command finished (/kon:ask, /kon:research, /kon:review, /kon:review-pr, /kon:describe-issue), or superseded by a newer session
• blocked — retry limit hit, something needs human intervention

Never auto-set completed for pipeline commands (/kon:team, /kon:quick, /kon:debug, /kon:gc, /kon:design). When their agents finish, set status=waiting.

Auto-complete one-shot commands when the sole agent finishes: /kon:ask, /kon:hunt, /kon:research, /kon:review, /kon:review-pr, /kon:describe-issue → set status=completed (via complete-agent).

Supersede on new run: when init creates a session, any other in_progress or waiting session for the same project_path is auto-closed as completed with log Superseded by new session <id>. — at most one open pipeline session per project.

Schema (full)

{
  "id": "...",
  "task": "...",
  "command": "/kon:team",
  "project_path": "/absolute/path/to/project",
  "started_at": "...",
  "status": "in_progress | waiting | completed | blocked",
  "current_agent": "Yui | null",
  "steps_completed": ["Azusa", "Mugi"],
  "steps_pending":   ["Sawako", "Mio", "Nodoka"],
  "steps_failed":    [],
  "steps_waiting":   [],
  "checkpoint" 
   
     
       
       
       
    
  
   ...

task_agents — Cursor Task subagent ids for resume within the implement→review loop (see Implementation loop — Task resume in skills/teammate-flow). Ids are kept across milestones until estimated context usage exceeds the observed window (from Cursor preCompact) or resume fails. Managed via:

python3 $KON_ROOT/scripts/kon_session.py set-task-agent --id "$SID" --agent Mio --task-id "<id>"
python3 $KON_ROOT/scripts/kon_session.py get-task-agent --id "$SID" --agent Mio
python3 $KON_ROOT/scripts/kon_session.py should-refresh-task-agents --id "$SID"   # refresh | keep
python3 $KON_ROOT/scripts/kon_session.py maybe-clear-task-agents --id "$SID"     # cleared | kept
python3 $KON_ROOT/scripts/kon_session.py clear-task-agents --id "$SID"           # manual force

steps_failed — agents that hit an unresolvable error. steps_waiting — agents paused waiting for human input (e.g., plan approval).

When to write

steps_waiting — agents paused waiting for human input (e.g., plan approval, milestone gate). checkpoint — set by wait-for-user (summary, after, optional milestone); cleared by user-continued. Dashboard shows this while status=waiting.

User approval gates (pipeline commands)

Waiting tab (dashboard): only sessions with checkpoint.ts from wait-for-user — sorted FIFO by that timestamp. Do not hand-edit steps_waiting; always use wait-for-user / user-continued.

# After Mugi plan ready
python3 $KON_ROOT/scripts/kon_session.py wait-for-user --id "$SID" \
  --after plan --summary "Plan ready — approve to start?"
# user confirms in chat, then:
python3 $KON_ROOT/scripts/kon_session.py user-continued --id "$SID" --summary "Approved plan"

# After Mio approves milestone N (before next milestone or summarize)
python3 $KON_ROOT/scripts/kon_session.py wait-for-user --id "$SID" \
  --after milestone --milestone N --summary "Milestone N approved — proceed?"

Orchestrator must STOP the turn after wait-for-user — do not spawn the next agent until the user replies and you run user-continued.

Event	Action
Command starts	Create file: status=in_progress, all agents in steps_pending
Before spawning an agent	Move agent to current_agent, remove from steps_pending
Agent completes normally	Move agent to steps_completed, add log entry
Agent needs human input	Run wait-for-user (sets steps_waiting, checkpoint, status=waiting)
Human responds, agent resumes	Run user-continued, then start-agent for next agent
Agent blocked / retry limit	Move agent to steps_failed, set status=blocked
All agents finished (pipeline command)	Set status=waiting, current_agent=null
All agents finished (/kon:ask, /kon:hunt, /kon:research, /kon:review, /kon:review-pr, /kon:describe-issue)	Set status=completed
init creates a new session	Supersede other open sessions for same project → completed
/kon:finish or dashboard ✓	python3 scripts/kon_session.py finish → status=completed, log User row

/kon:begin variant

Interactive session — stays open until /kon:finish:

• On create: command: "/kon:begin", mode: "interactive", steps_pending: [], status=in_progress
• Sub-turns: never call init — use log-turn and complete-agent on the same id
• After each agent: status stays in_progress (begin never auto-completes)
• Close: /kon:finish or dashboard ✓

Check active begin session: python3 scripts/kon_session.py active

/kon:research variant

Research is read-only for source code but writes .kon/research.md:

• On create: command: "/kon:research", steps_pending: ["Jun"]
• After Jun answers: steps_completed: ["Jun"], status=completed (via complete-agent), log one-sentence summary

/kon:review variant

Review is read-only — no code changes:

• On create: command: "/kon:review", steps_pending: ["Mio"] (prepend "Mugi" when --rubric)
• After Mio verdict: steps_completed: ["Mio"], status=completed (via complete-agent), log verdict one-liner

/kon:review-pr variant

Holistic PR review — Mio reads diff, PR body, review comments, and linked issues:

• On create: command: "/kon:review-pr", steps_pending: ["Mio"]
• After Mio verdict: steps_completed: ["Mio"], status=completed (via complete-agent), log verdict one-liner
• Artifact: sessions/<id>/pr-review.md (subagentStop hook when installed)

/kon:describe-issue variant

Issue thread summary — Jun fetches issue + all comments via gh:

• On create: command: "/kon:describe-issue", steps_pending: ["Jun"]
• After Jun finishes: steps_completed: ["Jun"], status=completed (via complete-agent), log one-liner
• Artifact: sessions/<id>/issue-summary.md

/kon:hunt variant

Read-only bug analysis — Azusa only:

• On create: command: "/kon:hunt", steps_pending: ["Azusa"]
• After Azusa finishes: steps_completed: ["Azusa"], status=completed (via complete-agent)
• Artifact: sessions/<id>/hunt.md (subagentStop hook when installed)

/kon:ask variant

Ask is read-only for the repo but still tracks a session:

• On create: command: "/kon:ask", steps_pending: ["Azusa"], other agent lists empty
• After Azusa answers: steps_completed: ["Azusa"], status=completed (via complete-agent), log entry with one-sentence summary of the answer topic

/kon:debug variant

Bug investigation — repro before fix, Mugi proposes fix approaches:

• On create: command: "/kon:debug", steps_pending: ["Azusa", "pre-plan-gate", "Mugi", "User", "Yui", "Mio", "Nodoka"]
• Orchestrator writes debug.md after Azusa; understanding.md after pre-plan gate, before Mugi
• After all agents: status=waiting (pipeline — not auto-completed)

/kon:design variant

Design runs explore → plan → debate rounds → user confirm (no Yui/Mio/Sawako):

• On create: command: "/kon:design", steps_pending: ["Azusa", "pre-plan-gate", "Mugi", "User"]
• Log each agent spawn including repeat Azusa/Mugi debate passes (same agent name is OK — log carries round detail)
• After Mugi revise: wait-for-user --after plan
• Do not auto-set completed until user runs /kon:finish or approves and closes

Write the file with scripts/kon_session.py (preferred) or a single python3 -c call:

# Create (all commands including ask)
python3 $KON_ROOT/scripts/kon_session.py init --command "/kon:ask" --task "<question>"

# After each agent completes
python3 $KON_ROOT/scripts/kon_session.py complete-agent --id <sid> --agent Azusa --summary "<one sentence>"

Inline fallback if the script is unavailable:

python3 -c "
import json, pathlib, datetime, os, sys, subprocess
bundled = pathlib.Path.home() / '.kon/lib/_kon_paths.py'
if os.environ.get('KON_ROOT'):
    root = pathlib.Path(os.environ['KON_ROOT']).expanduser().resolve()
elif bundled.is_file():
    root = pathlib.Path(subprocess.check_output(['python3', str(bundled), 'root'], text=True).strip())
else:
    root = pathlib.Path.home() / 'Desktop/kon'
sys.path.insert(0, str(root / 'hooks'))
from _kon_paths import ensure_sessions_dir
p = ensure_sessions_dir() / '<id>.json'
p.write_text(json.dumps(<data>, ensure_ascii=False, indent=2))
"

On create, always set project_path to the absolute cwd. Path helper: hooks/_kon_paths.py.

Log entry summary rules

One sentence, past tense, specific — the user reads this at a glance:

• "Found 3 relevant files; convention divergence at auth.py:42"
• "Plan written to .kon/plan-20260617-203042-add-email-validation.md — 4 steps, defaults accepted for 2 decisions"
• "Step 3/4 done — edited auth.py, validators.py; acceptance ✅"
• "Answered: session paths use ~/.kon/projects//sessions/"
• "BLOCKED: edge case empty input unresolved (round 2)"