# Session Claim > Claim or resume a work item before implementation. Use when the user asks to start, continue, resume, claim, or take a queued work item, or before applying/implementing selected project work. Writes Active Work and captures baseline dirty files. - Skill: `57luo/session-claim` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add 57luo/session-claim` - Raw SKILL.md: https://api.skillmd.com/api/skills/57luo/session-claim/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: 57Luo (https://skillmd.com/u/57luo) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/57luo/session-claim --- # Session Claim Claim or resume a work item before implementation. This is the pre-work gate and may write the handoff Board. ## Shared Handoff Schema `session-handoff/schema/handoff.md` is the authoritative contract; when duplicated rules differ, the shared schema wins unless this skill states a claim-specific exception. **Do NOT read the full schema for a warm (Fast Path) claim.** The Schema Essentials below cover everything the Fast Path needs. Read the full schema only on the cold/conflict path (`references/conflict-path.md`), or when a rule in question is not covered by the essentials. ### Schema Essentials (warm claim) - Active Work columns: `Slot | Work Item | Status | Workspace | Branch | MergeCommit | Started | Completed`. - `Slot` = `S`, per-day numbering: allocate max `S` of today's rows + 1; no cross-day continuation. - At claim: `Status` = `in-progress`, `Branch` = the now-checked-out intended ref, `MergeCommit` and `Completed` empty (handoff fills them on completion). - `Workspace` = normalized absolute path of the working tree; on Windows escape backslashes as `\\` inside table cells. - Board writes go through `session-handoff/scripts/locked_write.py` (read → `--md5` → prepare full new content in a temp file → lint with `session-handoff/scripts/lint_board.py --expect-rows ` → write with `--content-file --expect-md5`). Exit 3 = re-read and retry; exit 4 = another writer, wait and retry. - Related Docs = durable documentation/planning artifacts needing a sync check because of the claimed work; never source/test/generated files or Spectra workflow artifacts (`proposal.md`, `design.md`, `tasks.md`, spec deltas). ## Artifact Boundary - Write handoff state only under shared project paths, preferably `.session/handoff/` at the main repo/worktree root. - Never write generated handoff data inside skill installation directories. - Historical handoffs are read-only. Record corrections in today's handoff rather than editing older daily files. ## Handoff Root Resolution Follow `## Handoff Root Resolution` in `session-handoff/schema/handoff.md`. As a writer skill: refuse to write a divergent worktree-local handoff directory and report it as a migration/mismatch warning. ## Core Rules - Do not implement, archive, commit, or apply changes from this skill. - If no work item is explicitly provided, run `session-brief` first and ask the user which item to claim. - Do not infer the work item from recent conversation when multiple candidates are plausible. - Read project instructions when present. Follow the `Project Instruction Reading Boundary` in `session-handoff/schema/handoff.md`; do not read `.claude/settings.json` by default. - Use `.session/handoff/YYYY-MM-DD.md` for today's handoff; create it from the latest unfinished Board if needed, following the inheritance rules in `## Artifact Boundary` of the shared schema and renumbering inherited Active Work rows per the schema's `Slot` rule (fresh `S1` sequence; previous day's Slot IDs are not preserved). - Keep `Remaining` claimable only. Remove the claimed item from `Remaining`. - Update `Phase Plan` only enough to mark the selected item active/in-progress. - Never silently overwrite another session's Active Work row. - Capture baseline dirty files and show them to the user; do not attribute baseline files to this session later unless explicitly touched. - Record a concise baseline note in the handoff when possible, keyed by session/work item/workspace/branch. If no durable baseline exists, `session-handoff` must treat baseline comparison as unavailable. ## Concurrent Write Guard Follow `## Concurrent Write Guard` in `session-handoff/schema/handoff.md` — prefer the `session-handoff/scripts/locked_write.py` helper over manual lock steps. Apply the guard to `Active Work`, `Phase Plan`, `Remaining`, `Related Docs`, `Open Questions`, `Blockers`, and `Spectra`. ## Quote-Trace Discipline Follow `## Quote-Trace Discipline` in `session-handoff/schema/handoff.md`. ## Claim Board Scope - If Spectra is detected by CLI or `openspec/`, `Active Work`, `Remaining`, and `Phase Plan` should track Spectra change names only. - In Spectra projects, reject non-Spectra claims without writing `Active Work`. Optionally record only Board-safe context in `Open Questions`, `Blockers`, or `Related Docs` when explicitly requested; for retrospective notes, tell the user to use `session-handoff`. - In Spectra projects, do not claim existing non-Spectra `Remaining` entries. Tell the user to run `session-update` to move them out of the claimable queue. - If Spectra is absent, non-Spectra claims are allowed only with a stable slug/name and either a progress source or explicit handoff-only completion criteria. ## Active Work Schema Follow `## Active Work Schema` (including `### Workspace x Branch Matrix`) in `session-handoff/schema/handoff.md` for column semantics, the `Slot` per-day numbering rule, and the conflict matrix. Claim-specific delta only: - At claim time, write `Branch` = the now-checked-out intended ref; leave `MergeCommit` and `Completed` empty. `session-claim` never lands work, so it never fills `MergeCommit`. Branch creation, baseline capture, and Remaining removal are claim responsibilities defined in `## Core Rules` and `references/branch-policy.md`; they are not column semantics and are not repeated here. ## Conflict, Branch & Worktree Handling Clean Fast-Path claims do not need any of the following — they create the branch inline (Fast Path step 3). Load a reference only when the Fast Path gate routes you here: - Resolving / creating the intended branch, or the checkout is on a different branch than intended → `references/branch-policy.md`. - The checkout is occupied by another `in-progress` row, or dirty files belong to another in-progress item (parallel work) → `references/worktree-isolation.md`. - The Fast Path gate failed for any reason (cold start, existing `in-progress` row, parked change, conflict) → `references/conflict-path.md`, which covers full Spectra Discovery, Conflict Handling, Ideas Backlog Interaction, and the ordered Cold / Conflict Workflow. The Workspace x Branch Matrix referenced throughout is defined once in `## Workspace x Branch Matrix` in `session-handoff/schema/handoff.md`. ## Fast Path (Warm Claim) Claim is a pre-work marker. Most claims happen in a session that already established state (a `propose` / `brief` / `start` ran, or another claim today). Do NOT pay the cold-start cost in that case. **Gate - take the Fast Path only when ALL of these hold:** 1. Today's handoff file `.session/handoff/YYYY-MM-DD.md` already exists. 2. The target work item has no existing `in-progress` row in `## Active Work`. 3. The current `Workspace` + `Branch` has no OTHER `in-progress` row (i.e. the checkout is not already occupied by a different active work item). If it is, the Workspace x Branch Matrix must run; escalate to the full Workflow. 4. `openspec/changes//` exists on disk. If it does NOT exist, do NOT judge the item stale because a parked change is moved out of `openspec/changes/` by design, so escalate to the full Workflow (which runs parked discovery via `spectra list --parked --json`) rather than failing here. 5. The workspace is clean (no dirty files) OR all dirty files are baseline. If dirty files are attributable to another in-progress item, escalate to the full Workflow (Worktree Recommendation required). Scan conditions 2 and 3 from the rows already in the handoff; condition 5 from `git status`. No Spectra CLI needed. **Fast Path does ONLY these (everything else is skipped):** 1. **Acquire the handoff lock first.** A missing `in-progress` row does NOT mean there is no concurrent writer; another `session-claim` / `session-update` / `session-handoff` may be mid-write. The lock is mandatory. 2. **Re-read and re-validate under the lock.** After acquiring the lock, re-read the handoff and re-check gate conditions 2, 3, and 5 against the just-read content, then allocate the Slot as max `S` + 1 over the rows currently written in *today's* `## Active Work` table (per-day reset; see Active Work Schema `Slot` rule). If re-validation fails (a row appeared since the pre-lock scan), release the lock and escalate to the full Workflow. You MAY skip the full 7-step snapshot guard (mtime/size/ first-80-lines diff), but re-read + re-validate + re-allocate is NOT optional. 3. **Create / checkout the intended branch** if not already on it. The intended branch name follows `references/branch-policy.md`'s naming rule, inlined here so the Fast Path needs no reference read: Spectra change → `spx/` (exact change name, no invented slug); non-Spectra → stable lowercase hyphenated slug with a conventional prefix (`feat/`, `fix/`, `docs/`, `chore/`, `refactor/`, `test/`), or `work/` when no prefix is obvious; if multiple names are plausible, ask before claiming. Gate 5 has confirmed clean/baseline, so the clean path applies directly: if the branch does not exist, `git checkout -b `; if it already exists, `git checkout ` (resume — surface its state). 4. **Write the row + Board flips in one read-modify-write** - add the Active Work row (Branch = the now-checked-out intended branch), flip the item's `## Phase Plan` entry to in-progress, set `## Spectra` Active. Release the lock. 5. **Populate Related Docs** - identify durable documentation artifacts that may need a sync check because of the claimed work item and write them into `## Related Docs`, per `## Related Docs Scope` in `session-handoff/schema/handoff.md` (no source/test/generated files, no Spectra workflow artifacts). 6. **Capture baseline** - one `git status`; record the one-line summary. 7. **Build session todo list** - see Session Todo List (at claim). 8. **Concise output** - see Output section. **Explicitly skipped on the Fast Path:** full Spectra Discovery (`spectra --help` / `list` / `list --parked`), prior-day Board inheritance, the Workspace x Branch Matrix, the Worktree Recommendation tree, and reading the change's proposal / design / tasks (apply reads those, not claim). Branch creation (step 3) is NOT skipped — it runs on both paths. The mandatory lock + re-read + re-validate (steps 1-2) are also NOT among the skipped items; only the snapshot-diff portion of the write guard is. **Escalate to the full Cold / Conflict Workflow (`references/conflict-path.md`) when ANY gate condition fails:** today's handoff is missing (cold start; needs creation + inheritance + full discovery), the target item already has an `in-progress` row, the current checkout is occupied by another in-progress item (Matrix required), dirty files are attributable to another in-progress item (Worktree Recommendation required), or the change is absent from `openspec/changes/` (could be parked; needs parked discovery). Every "escalate to the full Workflow" note above routes here. ## Session Todo List (at claim) Claim is the start-of-work gate, so materialize the work item's lifecycle steps as a tracked todo after writing the Active Work row. - Look in the project's `CLAUDE.md` for a change lifecycle (the ordered steps to take a work item from start through wrap-up, e.g. a `Change Lifecycle` heading). - **If the project section references the standard skeleton** (points at `references/lifecycle-skeleton.md` in this skill), load that file and merge it with the project's parameters (verification classes, deploy method) to get the concrete ordered steps. A project-defined full lifecycle wins over the skeleton; a skeleton reference with no parameters means every change takes the STOP path. - **Linear lifecycle**: materialize with the harness task tools — one `TaskCreate` per lifecycle step, in order (seed every phase, including wrap-up). These tools are deferred: run `ToolSearch` with `select:TaskCreate,TaskUpdate` first (skip only if such a call already succeeded this session), and `TaskList` to avoid duplicating an earlier claim. Mark the active step `in_progress`; mark condition-gated steps (verification, authorization, worktree-vs-not) `pending`, using `addBlockedBy` for serial ordering. Do NOT render the list as chat-text checkboxes only. - **Branching / decision-tree lifecycle** (conditional wrap-up keyed on the work item's properties — select one branch, gate the rest): see `references/todo-materialization.md`. - **No lifecycle found, or not reliably interpretable**: do NOT infer steps. Tell the user none is defined and offer to scaffold one from the `## CLAUDE.md Template` section in `references/lifecycle-skeleton.md` (skeleton reference + project-parameters table to fill in). - Scope: this is a runtime tracking aid — do NOT write it into the handoff Board. It tracks the **change lifecycle** (claim → apply → archive → commit → handoff), NOT the per-task progress of `spectra-apply`, whose source of truth is the `tasks.md` checkboxes — never mirror those into the task tool. ## Output **Default - concise (always use this unless a conflict needs a decision):** Claim is a marker, not a report. Emit 3 lines: ``` claimed: (in-progress, ) baseline: next: ``` The `next:` line depends on the project and work-item state: - Spectra project with an existing change and unfinished executable tasks: `next: /spectra-apply ` - Spectra project with unclear requirements, missing proposal/tasks, or a change that needs more context: name the appropriate next workflow step (`/spectra-discuss`, `/spectra-propose`, or `/spectra-ingest`) instead of defaulting to apply. - Spectra project with state not verified by claim: `next: follow Spectra workflow appropriate to current change state` - non-Spectra project: `next: start implementation` (or the project's own implementation entry point, if the Board / progress source names one) If a baseline dirty file is the user's pre-existing WIP, say so in the one-liner so it is not later attributed to this session. ### Handing Off to the Next Step After emitting the 3-line output (including `next:`), check whether the project defines a lifecycle that covers the `next:` step: 1. **IF** `CLAUDE.md` (or equivalent project instructions) defines a change lifecycle, **AND** that lifecycle says the `next:` step does not require user authorization (e.g. "apply directly once claim is done; no need to wait for authorization"): → **Invoke the `next:` step immediately.** Do not ask for confirmation, do not emit "shall I proceed?", do not stop between claim and the next step. The lifecycle already granted authorization. 2. **IF** no project lifecycle exists, or the lifecycle marks the `next:` step as requiring user authorization (a decision point, go-ahead gate): → **Stop after emitting `next:`.** Let the user drive the transition. This skill never implements/applies itself (see Core Rules); "invoke the next step" means calling that step's skill (e.g. `/spectra-apply`), not doing implementation work here. **Expanded - only when the claim hit a conflict or needs a user decision** (occupied checkout, branch mismatch, stale row, worktree question). Then add: - whether the item is new, resumed, or conflicted - the Workspace x Branch matrix outcome and the chosen resolution - full baseline dirty file list - Related Docs to keep synchronized Do NOT emit the expanded form for a clean claim.