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<n>, per-day numbering: allocate max S<n> 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 <tmp> --expect-rows <N> → 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/<name>/ 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<n> + 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/<change-name> (exact change name, no invented slug); non-Spectra → stable lowercase hyphenated slug with a conventional prefix (feat/, fix/, docs/, chore/, refactor/, test/), or work/<slug> 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 <intended-branch>; if it already exists, git checkout <intended-branch> (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:

<Slot> claimed: <work-item> (in-progress, <branch>)
baseline: <one-line dirty summary, or "clean">
next: <next-step; see below>

The next: line depends on the project and work-item state:

• Spectra project with an existing change and unfinished executable tasks: next: /spectra-apply <work-item>
• 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.