Autonomous Session Workflow · diff
git:20260710.2925510 to git:20260710.62afd0f
221 added, 14 removed. Audit B to A.
---
- title: "Autonomous Session Workflow"
+ name: "Autonomous Session Workflow"
+ slug: "autonomous-session-workflow"
description: "5-phase repeatable structure for autonomous agent sessions: context-load, tiered work-selection, coordination claim, execute, and persist-learning. Prevents duplicate work across concurrent sessions and ensures every run produces durable artifacts. Runtime-agnostic — Claude Code, gptme, Codex, or any persistent-workspace agent."
verification: "listed"
source: "https://github.com/agentskillexchange/skills/pull/15"
- category:
- - "Templates & Workflows"
- framework:
- - "Claude Code"
+ category: "Templates & Workflows"
+ framework: "Claude Code"
---
# Autonomous Session Workflow
- 5-phase repeatable structure for autonomous agent sessions: context-load, tiered work-selection, coordination claim, execute, and persist-learning. Prevents duplicate work across concurrent sessions and ensures every run produces durable artifacts. Runtime-agnostic — Claude Code, gptme, Codex, or any persistent-workspace agent.
+ A 5-phase repeatable structure for autonomous agent sessions that prevents duplicate
+ work, ensures durable learning capture, and keeps output bias toward meaningful shipped
+ artifacts rather than motion.
+ Battle-tested across thousands of autonomous sessions on the gptme architecture. The
+ phases are runtime-agnostic — adapt the specific tools to your stack while keeping
+ the phase structure intact.
+
+ ## When to Use
+
+ - At the start of every autonomous agent session (no live human directing the work)
+ - When the agent must select its own work from a backlog or queue
+ - When sessions run unattended and need to produce durable artifacts
+
+ ## When Not to Use
+
+ - Interactive sessions where a human provides the next prompt each turn — just respond
+ - One-shot tool invocations with a fixed target (no selection needed)
+ - Sub-agent calls spawned from a parent task (the parent already selected the work)
+
+ ## The 5 Phases
+
+ ### Phase 1: Context Load
+
+ Load the agent's identity, session state, and current world model.
+
+ ```bash
+ # Read identity files — persona, goals, operating constraints
+ # (adapt to your stack: CLAUDE.md, AGENTS.md, system prompt, etc.)
+
+ # Read dynamic context — recent journal, task queue, git status, notifications
+ # (adapt: a context script, config-driven include, or prompt injection)
+
+ # Assess loose ends from prior sessions:
+ # - Stale claims that should be completed or abandoned
+ # - Pending replies on issues/PRs you promised to close
+ # - In-progress branches or open worktrees
+ ```
+
+ **Key question**: "What did I leave unfinished and what changed while I was offline?"
+
+ If a loose end is resolvable in <5 min, handle it here. Otherwise note it and proceed.
+
+ ### Phase 2: Work Selection
+
+ Try tiers in order until you find actionable work. The tiers prevent the agent from
+ inventing busy-work when real tasks exist, and prevent starvation when all tasks
+ are blocked.
+
+ ```
+ Tier 1 — Active tasks: work already in progress; highest priority
+ Tier 2 — Backlog quick wins: dependency-ready items you can complete this session
+ Tier 3 — Self-improvement: when all tasks are externally blocked
+ ├─ Idea backlog (advance the highest-scored idea)
+ ├─ Self-review / audit (find and fix a real issue)
+ ├─ Internal tooling improvement
+ ├─ Documentation (stale docs only)
+ ├─ Code quality (typecheck, tests, lint)
+ └─ Lesson quality (repair harmful or outdated lessons)
+ ```
+
+ **Anti-monotony guard**: If the same category has dominated the last N sessions,
+ skip it even if it looks like the best pick. Category diversity is a forcing function
+ for learning new failure modes.
+
+ **When everything is dry**: If all Tier 1/2 tasks are externally blocked and Tier 3
+ lanes are saturated (daily limits hit), write a short restraint journal recording what
+ you checked and deliberately skipped. A justified NOOP is better than fabricating work.
+
+ ### Phase 3: Claim
+
+ Before executing, acquire an exclusive coordination claim. This prevents two concurrent
+ sessions from executing the same work, flooding the same PR thread, or writing
+ the same file.
+
+ ```bash
+ # Generic coordination pattern — adapt the tool to your stack:
+ claim_key="task:<task-id>" # for task-backed work
+ claim_key="github:<owner>/<repo>#<num>" # for issue-backed work
+ claim_key="content:<slug>:<date>" # for content/artifact creation
+
+ # Acquire claim (example using a coordination CLI):
+ coordination work-claim "<session-id>" "$claim_key" --ttl 60
+ # CLAIMED → proceed
+ # DENIED → another session is already on it; pick the next candidate
+ ```
+
+ **Notify-before-claim rule**: Any action visible to others (posting a comment,
+ sending a message, opening a PR) must be gated by a claim first. Social actions
+ without claims converge and spam — a claimed-then-post pattern prevents flooding.
+
+ On completion: `coordination work-complete "<session-id>" "$claim_key"`
+ On pivot/failure: `coordination work-abandon "<session-id>" "$claim_key"`
+
+ ### Phase 4: Execute
+
+ Do real work. The key discipline is shipping, not perfecting.
+
+ ```
+ - Commit early and often (small, well-described commits)
+ - Run tests before committing (catch issues before CI does)
+ - Use conventional commits: feat/fix/docs/refactor/chore
+ - Push to origin before the session ends
+ - If stuck for >10 minutes, move on — don't sink budget in a rabbit hole
+ - Don't add unrequested features or scope creep
+ ```
+
+ **50-minute budget**: Most autonomous sessions should complete meaningful work within
+ 50 minutes. If the task is larger, ship an incremental slice and create a follow-up
+ task for the remainder.
+
+ ### Phase 5: Persist
+
+ The most undervalued phase. Everything done in Phases 1–4 evaporates between sessions
+ unless it's durably committed.
+
+ ```bash
+ # 1. Write the journal entry (session-specific file, append-only)
+ cat > journal/$(date +%Y-%m-%d)/session-<HASH>.md << 'EOF'
+ # Session <HASH>
+ **Date**: YYYY-MM-DD
+ **Outcome**: productive|blocked|noop — one sentence
+ **Category**: code|research|strategic|maintenance|...
+
+ ## Why this work
+ [What led here]
+
+ ## What I Did
+ [Concrete changes with commit/PR links]
+
+ ## Verification
+ - [Tests passing? CI green?]
+
+ ## Persisted Learning
+ - Task state: <task> → done/waiting
+ - New lessons: [if any]
+ - "No durable feedback this session" — if genuinely nothing to add
+
+ ## Next
+ [Clear next action or blocking factor]
+ EOF
+
+ # 2. Update task state
+ task edit <task-id> --set state done # or waiting, if blocked
+
+ # 3. If a recurring failure pattern was discovered, write a lesson/rule
+ # (keyword-matched context file injected at the next session start)
+
+ # 4. Push all commits
+ git push origin master
+ ```
+
+ **Persist-first rule**: If you discovered something useful, write the lesson BEFORE
+ applying it to the current work. Once the fix is in, the failure mode feels solved
+ and the lesson gets skipped. The journal captures what happened; the lesson captures
+ when to recognize it again.
+
## Installation
- Choose whichever fits your setup:
+ ### Claude Code
- 1. Copy this skill folder into your local skills directory.
- 2. Clone the repo and symlink or copy the skill into your agent workspace.
- 3. Add the repo as a git submodule if you manage shared skills centrally.
- 4. Install it through your internal provisioning or packaging workflow.
- 5. Download the folder directly from GitHub and place it in your skills collection.
+ Copy this skill directory into your agent's skill folder:
- ## Source
+ ```bash
+ cp -R skills/autonomous-session-workflow ~/.claude/skills/autonomous-session-workflow
+ ```
- - [Agent Skill Exchange](https://agentskillexchange.com/skills/autonomous-session-workflow/)
+ Then invoke with `/autonomous-session-workflow` to load the 5-phase checklist into context.
+
+ ### Manual / any runtime
+
+ Copy `SKILL.md` into your agent's context path and load it at session start. The phases
+ are plain markdown — include the whole file or cherry-pick the sections relevant to
+ your stack.
+
+ ## Common Rationalizations
+
+ | Rationalization | Reality |
+ |---|---|
+ | "I'll skip the claim — I'm the only session running right now" | You can't see other sessions launching. Concurrent spawning is the default on production runtimes. The claim is the gate, not the observation. |
+ | "I'll write the journal after I finish the next task" | Sessions get interrupted. The journal gets skipped. Write it before pushing, not after "one more thing." |
+ | "This task is almost done — I'll skip Phase 5 and just commit" | Learning only compounds if it's persisted. The session that "almost" closed the loop is the session whose insight disappears by next run. |
+ | "My selection is obvious — I don't need to work through the tiers" | Selection that skips the tiers is the primary source of redundant work and duplicate PRs. The tiers exist because "obvious" is often not what actually needs doing. |
+ | "The lesson is too specific to be reusable" | Specific lessons (exact error message, exact command, exact failure mode) are the most valuable — they trigger precisely when needed. |
+ | "A justified NOOP feels like failure" | It isn't. A filler commit to dodge the NOOP label burns quota, feeds convergence churn, and hides the jam. A restraint journal IS the deliverable. |
+
+ ## Red Flags
+
+ - Starting execution before claiming (convergence risk)
+ - Session ends with no journal and no updated task state
+ - Committing "in a moment" — if you haven't pushed before ending, you haven't shipped
+ - Three consecutive sessions in the same category without a forced diversity break
+ - "I'll remember this" — you won't; write the lesson now
+
+ ## Verification
+
+ A well-run session satisfies all of these before closing:
+
+ - [ ] Claimed before acting (or justified why no claim was needed)
+ - [ ] Meaningful work committed and pushed
+ - [ ] Tests passed (or a known failure documented with reason)
+ - [ ] Journal entry written with `Persisted Learning` section filled in
+ - [ ] Task state updated (`active → done`, `active → waiting`, etc.)
+ - [ ] Claim completed or abandoned (not left as dangling lease)
+
+ ## Adapting to Your Stack
+
+ | gptme concept | Your equivalent |
+ |---|---|
+ | `gptodo` | any task manager with state transitions |
+ | `coordination work-claim` | a lock file, Redis SETNX, or GitHub comment gate |
+ | `lessons/<category>/name.md` | any keyword-matched context file injected at session start |
+ | `journal/<date>/session-<hash>.md` | any append-only session log |
+ | `cascade-selector.py` | your work-selection heuristic or scheduler |
+
+ The pattern is the value, not the specific tools.
+
+ ## Related
+
+ - `self-push` (in this catalog) — lazy-check before shipping any output
+ - `pre-landing-review` (in this catalog) — gate before merging significant changes
+ - `multi-lens-review` (in this catalog) — structured PR review across multiple lenses
+ - `five-element-spec` (in this catalog) — scope definition before starting work