| name | save-to-md |
| description | Save the current agent session to an in-repo markdown file with observed metadata, git state, session context, verification evidence, errors, open questions, and next steps. Use when the user asks to save session notes, persist conversation context, create a session log, document the current work, or when another workflow such as quick-push needs post-push session documentation. |
Save To Markdown
Workflow
- Resolve the repository root with
git rev-parse --show-toplevel.
- Collect observed context with shell commands; do not invent missing values.
- Resolve the output path:
- If the user provided a path, resolve it relative to the repo root unless it is absolute.
- If no path was provided, use
.docs/sessions/YYYY-MM-DD-description.md under the repo root.
- Reject paths outside the repo root.
- If the target file exists, append
-v2, -v3, etc. before .md.
- Create the parent directory only if it does not already exist.
- Write a concise markdown session document.
- Print the final absolute path.
Context To Collect
Run the relevant commands from the repo root:
TZ=America/New_York date '+%Y-%m-%d %H:%M:%S EST'
git remote get-url origin
git branch --show-current
git rev-parse --short HEAD
git log --oneline -5
git status --short
git log --oneline --name-only -10
pwd
git worktree list
gh pr view --json number,title,url
For Claude transcript paths, use ls -t ~/.claude/projects/$(pwd | sed 's|/|-|g')/*.jsonl 2>/dev/null | head -1. For Codex sessions, include the observed session path only if it is directly available; otherwise put the uncertainty in Open Questions.
Document Format
Start with a YAML metadata block using only observed values:
date: YYYY-MM-DD HH:MM:SS EST
repo: <remote URL>
branch: <current branch>
head: <HEAD commit SHA>
plan: <path or none>
agent: <Claude, Codex, Gemini, etc>
session id: <observed id if available>
transcript: <observed path if available>
working directory: <pwd>
worktree: <worktree line if applicable>
pr: <PR number, title, URL if applicable>
Then include these sections when applicable:
- User Request: Original goal in one or two sentences.
- Session Overview: What was accomplished.
- Sequence of Events: Major events in chronological order, no timestamps.
- Key Findings: Important discoveries with file paths and line numbers where useful.
- Technical Decisions: Choices and rationale.
- Files Modified: Files created or changed and why.
- Commands Executed: Critical commands and results.
- Errors Encountered: Failure, root cause, and resolution.
- Behavior Changes (Before/After): User-visible or system-visible changes.
- Verification Evidence: Table with
command | expected | actual | status.
- Risks and Rollback: Risks and concrete rollback path.
- Decisions Not Taken: Alternatives rejected and rationale.
- References: Docs, PRs, issues, URLs, or local artifacts consulted.
- Open Questions: Unresolved facts or assumptions.
- Next Steps: Separate unfinished work from follow-on tasks.
Quality Rules
- State facts only; do not infer unobserved values.
- Keep sections concise, but preserve critical evidence and safety context.
- Use repo-relative paths by default; include
file:line references for code-specific findings.
- Do not overwrite an existing session file.
- Keep the workflow in-repo unless the user explicitly asks otherwise.
