feat: add session management and execution verification

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

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

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)

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 ""
 }