From 63115f0e929fecb0895e23f1d3ece4e68ee50f8e Mon Sep 17 00:00:00 2001 From: Ajay Gunalan Date: Sun, 25 Jan 2026 11:49:23 -0500 Subject: [PATCH] feat: add session management and execution verification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New commands: - /pause: Save position before ending session - /resume: Restore context at start of new session - /verify-execution: Verify execution matched the spec New artifact: - STATE.md: Durable memory for active spec and progress Workflow: /shape-spec → execute → /verify-execution Use /pause and /resume across sessions Co-Authored-By: Claude Opus 4.5 --- commands/agent-os/pause.md | 105 ++++++++++++++++++++ commands/agent-os/resume.md | 87 ++++++++++++++++ commands/agent-os/verify-execution.md | 137 ++++++++++++++++++++++++++ scripts/project-install.sh | 35 +++++++ 4 files changed, 364 insertions(+) create mode 100644 commands/agent-os/pause.md create mode 100644 commands/agent-os/resume.md create mode 100644 commands/agent-os/verify-execution.md diff --git a/commands/agent-os/pause.md b/commands/agent-os/pause.md new file mode 100644 index 00000000..02cb1cba --- /dev/null +++ b/commands/agent-os/pause.md @@ -0,0 +1,105 @@ +# Pause + +Save your position before ending a session. Simple, fast, minimal questions. + +## Usage + +``` +/pause +/pause "note about where I left off" +``` + +## Process + +### Step 1: Load Current State + +1. Read `agent-os/STATE.md` (create if missing using template below) +2. Get active spec path from STATE.md +3. If no active spec in STATE.md: + - Look at `agent-os/specs/` for folders + - If folders exist: use most recent by timestamp (folder name is YYYY-MM-DD-HHMM-slug) + - Update STATE.md with this active spec + - If no folders: inform user "No specs found. Run /shape-spec first." + +### Step 2: Derive Progress + +Read `agent-os/specs/{spec}/plan.md` and count tasks: +- Tasks use checkbox format: `- [ ] Task name` (incomplete) or `- [x] Task name` (done) +- Count total checkboxes +- Count checked boxes +- Current task = first unchecked +- If no checkboxes found, count `## Task` headings and assume 0 done + +No questions. Auto-derive from plan.md. + +### Step 3: Get Optional Note + +If user provided a note as argument, use it. + +Otherwise, use AskUserQuestion: + +``` +Brief note for next session? (optional, press enter to skip) +``` + +Keep it short. One line max. + +### Step 4: Update STATE.md + +Update `agent-os/STATE.md`: +- Status: `paused` +- Last activity: current timestamp +- Current task: first incomplete task +- Next step: inferred from progress +- Note: user's note (if provided) + +### Step 5: Confirm + +Output: + +``` +Saved to STATE.md + +Active: {spec path} +Progress: {done}/{total} tasks +Next: {suggested action} + +See you next session. +``` + +Done. No commit, no ceremony. + +## STATE.md Template + +If `agent-os/STATE.md` doesn't exist, create it: + +```markdown +# Agent OS State + +## Active Spec +Path: None +Status: idle + +## Progress +Tasks: 0/0 done +Current: None + +## Session +Last activity: None +Note: None + +## Next Step +Run /shape-spec to create a spec + +## Decisions (latest 5) +- None + +## Blockers +- None +``` + +## Tips + +- Run /pause before context gets too full +- Keep notes brief - just enough to jog memory +- STATE.md is the only file updated diff --git a/commands/agent-os/resume.md b/commands/agent-os/resume.md new file mode 100644 index 00000000..73fe4940 --- /dev/null +++ b/commands/agent-os/resume.md @@ -0,0 +1,87 @@ +# Resume + +Restore context at the start of a new session. Shows where you left off and suggests next action. + +## Usage + +``` +/resume +``` + +## Process + +### Step 1: Load State + +Read `agent-os/STATE.md`. + +If it doesn't exist: +``` +No STATE.md found. Run /shape-spec to start a new spec. +``` + +If status is `idle` or no active spec: +``` +No active work. Run /shape-spec to create a spec. +``` + +If status is `done`: +``` +Previous spec completed: {spec path} +Run /shape-spec to start a new spec. +``` + +### Step 2: Load Spec Context + +Read from active spec folder: +- `agent-os/specs/{spec}/shape.md` (scope) +- `agent-os/specs/{spec}/plan.md` (tasks + progress) + +### Step 3: Display Status + +Output: + +``` +Welcome back. + +Active: {spec path} +Status: {planning | executing | verifying | paused} +Progress: {done}/{total} tasks +Paused: {last activity timestamp} +Note: "{user's note}" (if any) + +Current task: {task name} +Scope: {summary from shape.md} + +Suggested: {next action} +``` + +### Step 4: Offer Choice + +Use AskUserQuestion: + +``` +What would you like to do? + +1. Continue implementation +2. Show full plan +3. Run /verify-execution +4. Show scope +``` + +Then proceed based on choice: +- Continue: remind user of current task, let them work +- Show plan: read and display plan.md +- Verify: tell user to run /verify-execution +- Scope: read and display scope from shape.md + +### Step 5: Update State + +Update `agent-os/STATE.md`: +- Status: `executing` (or keep as `verifying` if that was the state) +- Last activity: current timestamp + +## Tips + +- /resume is for new sessions after /pause +- If you just want to check status mid-session, read STATE.md directly +- The suggested action is based on progress - trust it or override diff --git a/commands/agent-os/verify-execution.md b/commands/agent-os/verify-execution.md new file mode 100644 index 00000000..a44d8864 --- /dev/null +++ b/commands/agent-os/verify-execution.md @@ -0,0 +1,137 @@ +# Verify Execution + +Verify that the execution matched the spec. Check if what was built aligns with what was planned. + +## Important Guidelines + +- **Always use AskUserQuestion tool** when asking the user anything +- **Verify the intent, not just tasks** — scope in shape.md is the contract +- **Prefer automated checks** — tests/lint/typecheck/build when available +- **Update STATE.md** — enable pause/resume across sessions + +## Usage + +``` +/verify-execution +/verify-execution 2026-01-24-1430-user-comment-system +``` + +## Process + +### Step 1: Resolve Active Spec + +1. Read `agent-os/STATE.md` +2. If an argument is provided, resolve it to a spec folder +3. Otherwise, use the active spec path from STATE.md + +If still unknown, list recent spec folders in `agent-os/specs/` and ask the user to choose. + +### Step 2: Load Spec Context + +Read: +- `agent-os/specs/{spec}/shape.md` (scope — what we intended to build) +- `agent-os/specs/{spec}/plan.md` (tasks — what steps were planned) + +### Step 3: Detect What Changed + +Run `git diff HEAD --name-only` to see all uncommitted files (staged + unstaged). + +If uncommitted files exist: +- These are the files that were just created/modified during execution +- List them for the user + +If no uncommitted files: +- Check `git log --oneline -5` for recent commits +- Ask user: "Did you already commit? Which files were part of this spec?" + +### Step 4: Run Automated Checks (If Available) + +Look for existing test/build commands: +- `package.json` scripts (`test`, `lint`, `typecheck`, `build`) +- `Makefile` targets +- Common runners (`pytest`, `go test`, `bundle exec rspec`, etc.) + +Run the lightest meaningful set. If none exist, note: "No automated suite found." + +### Step 5: Manual Verification + +Present to user: + +``` +Scope (from shape.md): +{scope summary} + +Files changed: +{list from git diff or user input} + +Tests: {pass/fail/none} +``` + +Use AskUserQuestion: + +``` +Does the feature work as intended? + +- Yes: everything works +- No: describe what's wrong +``` + +### Step 6: Record Results + +Update `agent-os/specs/{spec}/plan.md` by adding a section: + +```markdown +## Verification Results + +Date: {YYYY-MM-DD} + +### Files Changed +- {file1} +- {file2} + +### Automated Checks +- {command}: {result} + +### Manual Verification +- {pass/fail}: {notes} +``` + +### Step 7: Handle Gaps + +If issues were found: + +1. Add fix tasks to plan.md (1-3 max): + ```markdown + ## Fix Tasks + + - [ ] Fix: {description of issue} + ``` + +2. Update `agent-os/STATE.md`: + - Status: `executing` + - Current task: first fix task + - Next step: implement fixes, then run /verify-execution again + +3. Tell user: "Fix tasks added. Implement them, then run /verify-execution again." + +### Step 8: Complete + +If everything passes: + +1. Update `agent-os/STATE.md`: + - Status: `done` + - Next step: commit work, then /shape-spec for next feature + +2. Output: + ``` + Verification passed. + + Suggested: commit your work, then run /shape-spec for the next feature. + ``` + +## Tips + +- Run /verify-execution after completing all tasks, not after each task +- Trust automated checks over manual verification when both exist +- Keep fix tasks small — if a gap requires major work, consider a new spec +- Uncommitted files = what was just executed (easiest to verify) diff --git a/scripts/project-install.sh b/scripts/project-install.sh index 8688d4ad..368fa0c2 100755 --- a/scripts/project-install.sh +++ b/scripts/project-install.sh @@ -198,6 +198,38 @@ create_project_structure() { ensure_dir "$PROJECT_DIR/agent-os" ensure_dir "$PROJECT_DIR/agent-os/standards" + # Create durable state file (do not overwrite if it exists) + local state_file="$PROJECT_DIR/agent-os/STATE.md" + if [[ ! -f "$state_file" ]]; then + cat > "$state_file" << 'EOF' +# Agent OS State + +## Active Spec +Path: None +Status: idle + +## Progress +Tasks: 0/0 done +Current: None + +## Session +Last activity: None +Note: None + +## Next Step +Run /shape-spec to create a spec + +## Decisions (latest 5) +- None + +## Blockers +- None +EOF + print_success "Created agent-os/STATE.md" + else + print_verbose "State file already exists: $state_file" + fi + print_success "Created agent-os/ directory structure" } @@ -470,6 +502,9 @@ main() { echo "Next steps:" echo " 1. Run /discover-standards to extract patterns from your codebase" echo " 2. Run /inject-standards to inject standards into your context" + echo " 3. Run /shape-spec (plan mode) to shape and save a spec" + echo " 4. Execute the plan, then /verify-execution" + echo " 5. Use /pause and /resume across sessions" echo "" }