| 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": "Azusa", "summary": "Found 3 relevant files in auth/"},
{"ts": "2026-06-17T20:31:10Z", "agent": "Mugi", "summary": "Plan written, 4 steps, 0 decisions needed"},
{"ts": "2026-06-17T20:32:05Z", "agent": "Yui", "summary": "Step 2/4 in progress — editing auth.py"}
]
}
Session lifecycle
in_progress → waiting → completed
↓
blocked
in_progress — agents are actively runningwaiting — pipeline commands finished (/kon:team, …) — stays open until user actscompleted — 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 sessionblocked — 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": null,
"task_agents": {
"impl-loop": {
"Yui": "<cursor-task-subagent-id>",
"Sawako": "<cursor-task-subagent-id>",
"Mio": "<cursor-task-subagent-id>"
}
},
"log": [...]
}
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"
python3 $KON_ROOT/scripts/kon_session.py maybe-clear-task-agents --id "$SID"
python3 $KON_ROOT/scripts/kon_session.py clear-task-agents --id "$SID"
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.
python3 $KON_ROOT/scripts/kon_session.py wait-for-user --id "$SID" \
--after plan --summary "Plan ready — approve to start?"
python3 $KON_ROOT/scripts/kon_session.py user-continued --id "$SID" --summary "Approved plan"
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:
python3 $KON_ROOT/scripts/kon_session.py init --command "/kon:ask" --task "<question>"
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)"
