eai-cli 0.0.0-bootstrap.0

package/resources/gofer/commands/7_gofer_save.md

@@ -0,0 +1,399 @@
+---
+name: 7_gofer_save
+description: "Save session state and create a handoff checkpoint for resumption in a new context."
+title: "Gofer Save"
+category: utility
+surfaces:
+  - claude
+  - claude-mirror
+  - copilot
+  - vscode
+  - codex
+  - gemini
+  - github-prompts
+  - agents-skills
+  - system-skills
+aliases: [gofer:save]
+---
+---
+description: Save session progress with comprehensive checkpoint for resumption
+---
+
+# Gofer Save
+
+## EAI Platform Session Preflight
+
+Before any Gofer stage/helper command does pipeline work:
+
+1. Treat durable delivery as EAI Platform delivery by default, with Azure second
+   and every other stack only by explicit exception.
+2. Run `eai whoami` and confirm the EAI CLI is installed, the user is logged in,
+   and an active tenant is visible.
+3. If `eai` is missing, `eai whoami` fails, the token is expired, or no active
+   tenant is available, stop and run `/gofer:eai-first-run` or ask the user to
+   approve login/setup before continuing.
+4. For EAI app delivery, do not continue into research, specification, planning,
+   tasks, implementation, or validation until
+   `.specify/specs/{feature}/eai-preflight.md` records login, tenant, template,
+   app-readiness, and next-action evidence.
+5. Do not write tokens, secrets, private tenant IDs, or local `.env` values into
+   Gofer artifacts; record only product-safe readiness status and evidence.
+
+## Token And Cost Policy
+<!-- gofer:token-cost-policy:start -->
+
+Before spawning agents, calling tools, or loading large files:
+
+1. Treat `.specify/memory/gofer-model-policy.yaml` as the repo-owned source of truth for simple, medium, hard, and arbiter model routing. If it is missing, run `/gofer:bootstrap-workspace` before continuing.
+2. Use the cheapest capable model first.
+   - Claude: Haiku for scouting/extraction; Sonnet for normal implementation, synthesis, validation, and security; Opus for high-risk arbitration or release-critical failures.
+   - Codex/OpenAI: GPT mini for simple coding; GPT nano only for locate/classify/summarize/mechanical work; GPT-5.3-Codex or flagship GPT for tool-heavy coding, architecture, and release-critical validation.
+   - Gemini: Flash-Lite for cheap large-context scan/summarize; Flash for default research synthesis; Pro for large-context architecture or high-risk arbitration.
+   - Copilot: prefer Auto for simple and default work; ask the user before choosing a paid/high-tier picker model for hard security, architecture, or release gates.
+3. Keep raw tool output out of the main conversation context. Save stable findings to `.specify/specs/{feature}/context-bundle.md`, then work from summaries.
+4. Use provider prompt/context caching only for stable, non-secret prefixes: Gofer scaffold, AGENTS/CLAUDE/Copilot instructions, constitution, repo map, stage contracts, and validation rubric.
+5. Before continuing after large research, planning, implementation, or validation bursts, checkpoint the durable artifacts and compact/clear/resume context when the host supports it.
+6. Escalate model tier only when a cheaper pass is low-confidence, contradictory, security-sensitive, or blocking release quality.
+<!-- gofer:token-cost-policy:end -->
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+---
+
+## When to Use This Command
+
+- User needs to stop mid-implementation
+- Switching to another task/feature
+- End of work session
+- Before a break or context switch
+- **Context window approaching limits (>50% usage)**
+- **Context health check returns WARNING or CRITICAL**
+- Before risky operations
+
+### Context-Triggered Saves (2025-2026 Best Practice)
+
+Run context health check periodically during long sessions:
+
+```bash
+.specify/scripts/bash/check-context-health.sh --json
+```
+
+| Status   | Token Usage | Action                                  |
+| -------- | ----------- | --------------------------------------- |
+| Healthy  | < 50%       | Continue normally                       |
+| Warning  | 50-70%      | Consider checkpoint, use sub-agents     |
+| Critical | > 70%       | **Save immediately**, start new session |
+
+**Why this matters**: Research shows LLMs lose accuracy as context grows.
+Effective context for Claude is ~60-120k tokens, not the advertised 200k.
+
+---
+
+## Step 1: Assess Current State
+
+### 1.1 Context Window Health
+
+```bash
+.specify/scripts/bash/check-context-health.sh
+```
+
+Document current context usage - this informs how much detail to include in
+handoff.
+
+### 1.2 Gather Session State
+
+1. **Review conversation history** to understand what was being worked on
+2. **Check git status** for uncommitted changes
+3. **Identify the active feature** from `.specify/specs/*/`
+4. **Review TodoWrite list** for current tasks
+5. **Check pipeline stage** - which Gofer command was last run
+
+```bash
+# Git state
+git status
+git log --oneline -5
+
+# Find active feature
+ls -la .specify/specs/
+```
+
+---
+
+## Step 2: Save Code Progress
+
+### 2.1 Commit Meaningful Work
+
+```bash
+git status
+git diff --stat
+
+# Create WIP commit if appropriate
+git add [specific files]
+git commit -m "WIP: [Feature] - [Current state description]
+
+Checkpoint created by /7_gofer_save
+Stage: [current pipeline stage]
+Next: [what needs to happen next]"
+```
+
+### 2.2 Document Uncommitted Changes
+
+If changes shouldn't be committed yet:
+
+- List files with unsaved changes
+- Explain why they weren't committed
+- Document what needs to be done before committing
+
+---
+
+## Step 3: Create Session Checkpoint
+
+Write to `{FEATURE_DIR}/session-checkpoint.md`:
+
+````markdown
+---
+feature: [Feature Name]
+created: [ISO timestamp]
+stage: [1_research|2_specify|3_plan|4_tasks|5_implement|6_validate]
+status: paused
+context_usage: [percentage from health check]
+last_commit: [git hash]
+branch: [current branch]
+---
+
+# Session Checkpoint: [Feature Name]
+
+## Current State
+
+### Pipeline Progress
+
+| Stage             | Status      | Artifact                 |
+| ----------------- | ----------- | ------------------------ |
+| 1_gofer_research  | [done/skip] | research.md              |
+| 2_gofer_specify   | [done/skip] | spec.md                  |
+| 3_gofer_plan      | [done/skip] | plan.md, data-model.md   |
+| 4_gofer_tasks     | [done/skip] | tasks.md                 |
+| 5_gofer_implement | [current]   | [files created/modified] |
+| 6_gofer_validate  | pending     | -                        |
+
+### Active Task
+
+- **Current Task**: [Task ID and description from tasks.md]
+- **File Being Modified**: `path/to/file.ts:line`
+- **What Was Happening**: [Detailed description]
+
+### Task Completion Status
+
+From tasks.md:
+
+- Completed: [X]/[Total] tasks
+- Current phase: [Phase name]
+- Next task: [Task ID and description]
+
+## Code Changes
+
+### Committed This Session
+
+```bash
+git log --oneline [session_start_commit]..HEAD
+```
+````
+
+### Uncommitted Changes
+
+| File           | Status   | Description                |
+| -------------- | -------- | -------------------------- |
+| `path/to/file` | Modified | [What was changed and why] |
+| `path/other`   | New      | [Purpose of new file]      |
+
+### Files NOT to Modify (Protected)
+
+From tasks.md Protected Files section:
+
+- [List protected files]
+
+## Context for Resumption
+
+### Key Decisions Made
+
+1. [Decision]: [Why and implications]
+2. [Decision]: [Why and implications]
+
+### Blockers Encountered
+
+- [Blocker]: [Status and workaround if any]
+
+### Gotchas Discovered
+
+- [Gotcha]: [How to handle]
+
+### Open Questions
+
+- [ ] [Question requiring user input]
+- [ ] [Question requiring research]
+
+## Resumption Instructions
+
+### Quick Resume
+
+```bash
+cd [repo path]
+git checkout [branch]
+# Read .specify/specs/[feature]/session-checkpoint.md
+# Continue with /5_gofer_implement or the stage recorded in the checkpoint
+```
+
+### Manual Resume Steps
+
+1. Read this checkpoint file
+2. Check `tasks.md` for current task
+3. Review `plan.md` for architecture context
+4. Continue with `/5_gofer_implement`
+
+### Context to Load First
+
+1. `{FEATURE_DIR}/tasks.md` - Current task list
+2. `{FEATURE_DIR}/plan.md` - Architecture decisions
+3. `[Current file being edited]` - Continue from here
+
+## Test Status
+
+- [ ] Build passes: `npm run build`
+- [ ] Tests pass: `npm test`
+- [ ] Lint passes: `npm run lint`
+
+## Notes
+
+[Any additional context that would help future you or another agent]
+
+````
+
+---
+
+## Step 4: Update Tasks.md
+
+Add checkpoint marker to tasks.md:
+
+```markdown
+## Checkpoint: [ISO timestamp]
+
+Progress saved at task [TaskID]. Resume by reading
+`session-checkpoint.md` in a fresh session and continuing from the recorded
+stage.
+````
+
+---
+
+## Step 5: Present Summary
+
+```
+================================================================
+  SESSION SAVED: [Feature Name]
+================================================================
+
+  Branch: [branch name]
+  Stage: [pipeline stage]
+  Tasks: [X]/[Total] complete
+
+  Checkpoint: {FEATURE_DIR}/session-checkpoint.md
+
+  Code Status:
+  - Committed: [X] files
+  - Uncommitted: [Y] files (documented)
+  - Tests: [passing/failing/not run]
+
+  To resume:
+  Read {FEATURE_DIR}/session-checkpoint.md in a fresh session
+
+  Or manually:
+  cd [repo] && git checkout [branch]
+  Read: {FEATURE_DIR}/session-checkpoint.md
+  Continue: /5_gofer_implement
+
+================================================================
+```
+
+---
+
+## Step 6: Observability Logging
+
+```bash
+.specify/scripts/bash/log-stage.sh 7_save --complete --tokens [N] --compactions [N]
+```
+
+---
+
+## Best Practices for Checkpoints
+
+### Always Capture
+
+- Exact file and line number being edited
+- Why you stopped (not just what you were doing)
+- Any mental model or context not in artifacts
+- Test status at time of save
+
+### Machine-Readable State
+
+The YAML frontmatter allows automated tools to:
+
+- Detect where to resume
+- Calculate time between sessions
+- Track feature velocity
+
+### Human-Readable Context
+
+The markdown body ensures:
+
+- Any agent (or human) can understand the state
+- No context is lost between sessions
+- Resumption is fast and accurate
+
+---
+
+## Context Management Best Practices (2025-2026 Research)
+
+### What to Preserve (High Value)
+
+- **Key decisions and rationale** - These are hard to reconstruct
+- **Blockers and workarounds** - Prevent repeated dead ends
+- **Exact file:line being edited** - Enables precise resumption
+- **Mental model context** - Insights not captured in artifacts
+
+### What to Summarize (Medium Value)
+
+- Tool outputs and exploration results
+- Code snippets that are in committed files
+- Error messages (keep only the key ones)
+
+### What to Omit (Low Value / High Cost)
+
+- Full file contents (can be re-read)
+- Repetitive conversation history
+- Superseded attempts or dead ends
+- Verbose tool outputs
+
+### Handoff Size Target
+
+Aim for session-checkpoint.md to be:
+
+- **< 2,000 tokens** for critical information
+- **< 5,000 tokens** total including context
+
+This ensures the resume session starts with clean context.
+
+---
+
+## Integration
+
+This command works with:
+
+- `/5_gofer_implement` - Can resume implementation
+- `/6_gofer_validate` - Can validate partial progress
+- `/0_gofer_start` - Detects saved sessions
+- `check-context-health.sh` - Triggers save at thresholds