You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
New session-flow plugin bundling four session-lifecycle skills as one cohesive capability:
Skill
Question it answers
/session-flow:workflow
Where am I in the staged dev workflow (contract → explore → research → plan → implement → test → review → verify → retro), and what comes next? Modes: default, steps, pre-pr, wrap-up, philosophy, spec-first
/session-flow:handoff
How do I save session state for /clear-and-resume? Full handoff file (seven sections + TaskList snapshot + session-id chain frontmatter) or prompt-only; hard STOP gate after emitting the save-point
/session-flow:retro
What happened, what did we learn, how do we codify it? Bundled stdlib-only transcript parser (multi-session-aware via the handoff chain), five-dimension assessment, approval-gated codification, score-history trends
/session-flow:orchestration-brief
How do I arm this session (or export a paste-ready brief for a spawned worker / fresh session) with six proactive-orchestration imperatives?
No source-repo refs (grep-verified: no medley, no .work/, no source-repo tooling paths). Source-repo-specific machinery re-seamed: workflow stages route to the CONSUMER's own stage skills when they exist and degrade gracefully to inline execution; convention/quality-gate content routes through the consumer's CLAUDE.md / .claude/rules/.
Save-point location honors a consumer-documented convention, defaulting to .claude/handoffs/ (project files by design — they travel with the repo). The bundled parser resolves handoff chains in both flat and subdir-prefixed layouts.
Bundled parser referenced via ${CLAUDE_PLUGIN_ROOT}; retro score history persists under ${CLAUDE_PLUGIN_DATA} (per-project files), never in the consumer's repo. No ../ reach-outs.
Sibling-skill refs stay bare (/retro, /handoff inside the plugin); no dependency on any other plugin.
No userConfig — the only variability that surfaced (artifact location, stage skills, conventions) routes through consumer context (no speculative knobs).
Parser portability widened during migration: PEP 758 bare-comma except clauses parenthesized so the script runs on Python 3.10+ (was 3.14+); match statements set the 3.10 floor.
Gate evidence (speed-adjusted per issue)
claude plugin validate --strict ./plugins/session-flow → Validation passed; claude plugin validate --strict . (catalog manifest) → Validation passed.
--plugin-dir smoke test in a clean non-source fixture repo (headless claude -p): skill loaded under the session-flow: namespace, context/steps.md read from the plugin root, content answered correctly ("Skill invoked: session-flow:workflow. Loaded content defines 9 numbered workflow stages (0–8). Stage 7: Verify outcome.").
Contract tests: pytest suite for the bundled parser — 25 tests pass locally (including new flat-layout chain-resolution coverage); parse-transcript.test.sh wrapper integrates with scripts/run-plugin-tests.sh and SKIPs cleanly when Python 3.10+/pytest is absent. shellcheck clean; markdownlint clean; typos clean.
Full baseline/parity apparatus not required per the issue (non-destructive skill content; source-repo originals remain until the cutover issue).
Security review (playbook acceptance)
No hooks, no MCP servers, no agents, no userConfig. Surfaces 1/2/3: N/A.
Cache isolation (surface 4): verified — bundled assets via ${CLAUDE_PLUGIN_ROOT}, state via ${CLAUDE_PLUGIN_DATA}, no ../ reach-outs, no absolute/machine paths. The parser reads only local ~/.claude/projects/ transcripts and handoff files the consumer created.
Data egress (surface 5): none — no network calls anywhere in the plugin; the parser is stdlib-only and offline.
Only write surfaces: handoff files into the consumer's project (user-visible save-points, the skill's purpose) and retro codifications behind an explicit interactive approval gate.
Low Risk
Adds markdown skills and an offline local transcript parser; the only writes are user-requested handoff files in the project and approval-gated rule/memory edits—no hooks, network, or privileged automation.
Overview
Adds the session-flow plugin (0.1.0) to the marketplace and root README catalog under productivity, shipping four repo-agnostic skills for session lifecycle management.
workflow navigates a staged pipeline (contract through retro), infers position from artifacts, and exposes modes for full steps, pre-PR gates, wrap-up, philosophy, and spec-first /clear between stages—routing to the consumer’s own stage skills when present.
handoff implements the /clear-and-resume pattern: durable save-points (default .claude/handoffs/) with chained session_id / previous_handoff frontmatter, TaskList reconstitution, and a mandatory STOP after the resume prompt; orchestration-brief primes the session or exports paste-ready worker/handoff briefs for six delegation imperatives.
retro runs session / codify / trends / quick modes with approval-gated codification into repo rules or auto-memory; score history lives under ${CLAUDE_PLUGIN_DATA}. A new stdlib-only parse_transcript.py (Python 3.10+, pytest contract tests + optional shell wrapper) reads local Claude Code JSONL transcripts and aggregates metrics across handoff chains via --chain-from.
Reviewed by Cursor Bugbot for commit 1166073. Bugbot is set up for automated code reviews on this repo. Configure here.
Four session-lifecycle skills as one cohesive capability: workflow
(staged dev-workflow navigator), handoff (save-point + resume prompt
for /clear-and-resume), retro (transcript-metrics retrospective with
learning codification), and orchestration-brief (proactive-orchestration
imperatives for a session or spawned worker).
Closesmelodic-software/medley#1284.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is needed before merge; no additional reviewers were assigned (solo-maintained repo, author is the only human contributor).
Sent by Cursor Approval Agent: Pull Request Router and Approver
High-quality, well-structured submission. The plugin is cleanly repo-agnostic, properly namespaced, security-clean, and the bundled Python parser has good test coverage. One confirmed bug in the parser's multi-session error handling (the Codex-flagged issue), a related test gap, and a minor documentation note. Everything else passes.
Confirmed Bug: parse_transcript.py — zero-transcript multi-session treated as warning
When --sessions or --chain-from resolves to one or more session IDs but all their JSONL files are absent (transcripts_present == 0, len(session_ids) > 0), this evaluates to "warning" and exits 0.
Why it matters:retro/context/session.md Phase 1 says:
Skip this phase if the user explicitly requests it, or if the parser errors (exit 2)
The exit logic (sys.exit(0 if output["status"] in {"pass", "warning"} else 2)) exits 0 on "warning", so a completely empty transcript run is silently treated as a successful parse. The retro skill then presents all-zero metrics as real data — indistinguishable from a session that genuinely had zero tool use.
The docstring at the top of the file correctly states: 2 = error (e.g., invalid arguments, no files at all) — confirming this is the intended behavior, just not implemented.
# was: status = "pass" if transcripts_present == len(session_ids) else "warning"iftranscripts_present==len(session_ids):
status="pass"eliftranscripts_present==0:
status="error"else:
status="warning"
No other changes needed — the existing exit logic already maps "error" to exit code 2 correctly.
Test gap: no all-missing multi-session test case
test_parse_transcript.py covers the one-missing scenario (test_multi_session_one_missing) and the no-SIDs scenario (test_chain_from_handoff_without_session_id), but has no test for the case where SIDs are supplied but ALL transcripts are absent. Should assert status == "error" and returncode == 2.
Minor: test_chain_from_handoff_without_session_id also doesn't assert returncode == 2 (only checks status), though the behavior is correct.
Invoke the sibling retro skill (/retro, or /retro quick under context pressure).
When consumed as a plugin, the retro skill lives at session-flow:retro. A consumer without a standalone retro skill would get an "unknown skill" error on bare /retro. This is instructional text to the model rather than a code path, so the model's context should disambiguate — but a more precise reference (/session-flow:retro) removes the ambiguity for first-time users.
CLAUDE.md checklist
Criterion
Result
Notes
Repo-agnostic
✅
All paths via ${CLAUDE_PROJECT_DIR}, CLAUDE.md, env vars
Configurable without editing
✅
No userConfig needed; variability routes through consumer context
Plugin-form-safe
✅
${CLAUDE_PLUGIN_ROOT} for assets, ${CLAUDE_PLUGIN_DATA} for state, no ../
No PII / secrets
✅
Clear
Versioned
✅
0.1.0 in plugin.json
Security
✅
No hooks, MCP, agents, network calls; parser is stdlib-only, reads only local user transcripts; writes only to user-visible project dirs behind approval gate
Ready to merge pending the line-605 fix (and ideally an accompanying test). The rest of the plugin is well-engineered — the parser's type-safety and stream-parse approach are solid, the test suite is thorough, the shell wrapper's SKIP behavior is correct, and the skill content correctly defers convention/gate authority to the consumer repo.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is needed before merge; no reviewers assigned (solo-maintained repo, author is the only human contributor).
Sent by Cursor Approval Agent: Pull Request Router and Approver
Multi-session parse now errors (exit 2) when every SID resolves to
nothing, instead of reading as a successful all-zero retro; NotebookEdit
now counts toward files_modified.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
iftranscripts_present==len(session_ids):
status="pass"eliftranscripts_present>0oragg_subagents:
# Genuine partial chain: some transcripts, or subagent evidence only.status="warning"else:
# Nothing found at all — must fail loudly.status="error"
The or agg_subagents branch handles the subtle case where no main JSONL exists but subagent records do (Claude Code writes subagents into a sibling directory). That path is reachable per parse_one_session returning subagents even when transcript_present is False — so "warning" is the right status there rather than a false error. The logic is correct.
2. NotebookEdit added to _FILE_MODIFYING_TOOLS — fixed
parse_transcript.py:80: frozenset({"Write", "Edit", "NotebookEdit"}). Both Write/Edit and NotebookEdit carry file_path in their input, so the existing extraction path is correct.
3. Both tests added
test_multi_session_all_missing_is_error — asserts returncode == 2, status == "error", and transcript_present == False for every session entry. Complete.
test_notebook_edit_counts_as_file_modification — asserts "analysis.ipynb" in data["files_modified"]. Complete.
One Remaining Issue
steps.md:87 bare /retro invocation — still not fixed
Invoke the sibling retro skill (`/retro`, or `/retro quick` under context pressure).
Same bare refs appear in workflow/context/wrap-up.md:15-16 and workflow/templates/checklist.md:20,42.
When the model reads steps.md inside a plugin context and follows its instruction to "Invoke … /retro", it will attempt to run /retro bare. In a consumer repo that only has the plugin installed (not a standalone /retro skill), this silently fails. The correct invocations for instructional text that the model should execute are session-flow:retro and session-flow:handoff. Prose references that merely name the concept ("write a /handoff save-point") are fine as-is.
test_chain_from_handoff_without_session_id (line 666) only asserts output["status"] == "error" and not result.returncode == 2. Since the exit logic correctly maps "error" → exit 2, the behavior is fine — this is just an incomplete assertion that could mask a regression.
Verdict
The two confirmed bugs are correctly fixed and both tests are solid. The bare-invocation issue in steps.md / wrap-up.md / checklist.md is the last open item before merge.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is needed before merge; no reviewers assigned (solo-maintained repo, author is the only human contributor).
Sent by Cursor Approval Agent: Pull Request Router and Approver
Probe for a Python 3.10+ interpreter instead of assuming bare python,
and derive the handoff chain directory from the consumer-documented
save-point location rather than hardcoding the default.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
python3-first ordering is correct (more likely to be new on systems that split the two). The in-process version check (sys.exit(0 if sys.version_info >= (3, 10) else 1)) is the right idiom — it avoids parsing --version output. Matches how the test-runner wrapper (parse-transcript.test.sh) already discovers the interpreter.
# Multi-session form (handoff chain exists). Set HANDOFF_DIR to the consuming# repo's documented save-point location when it declares one (see the handoff# skill's "Where handoffs live"); the plugin default is .claude/handoffs/.
HANDOFF_DIR=.claude/handoffs
NEWEST=$(ls -1 "$HANDOFF_DIR"/*-handoff-*.md 2>/dev/null | sort | tail -1)
The variable is named, the comment directs the model to override from consumer convention, and ls … 2>/dev/null gracefully handles a missing or empty directory. The approach is consistent with how the rest of this skill handles consumer-variability (comment-driven model guidance rather than code-driven lookup). The note correctly cross-references the handoff skill's "Where handoffs live" section.
When PY is empty (no qualifying interpreter found), "$PY" "$PARSER" … expands to "" "$PARSER" …, which bash evaluates as a command with an empty name — this fails with bash: : command not found rather than a controlled skip. The prose guidance to skip appears after the snippet, so a model executing the block literally would hit the error before reading it.
In practice, the model will often recover from the bash error by reading the surrounding prose — this isn't a hard blocker — but the snippet as written is technically broken for the no-Python case and diverges from the contract it documents. Fix this →
Carried Items (Unchanged from Prior Reviews)
Item
Status
Bare /retro / /handoff sibling refs in steps.md, wrap-up.md, checklist.md
Declined by author — stated rationale: sibling refs within a plugin stay bare; they resolve correctly from the session-flow: namespace during execution. Accepted as a design decision.
Minor incomplete assertion; behavior is correct. Not blocking.
CLAUDE.md Checklist (unchanged — all pass)
Criterion
Result
Repo-agnostic
✅
Configurable without editing
✅
Plugin-form-safe
✅
No PII / secrets
✅
Versioned
✅
Security
✅
Verdict
c747602 correctly addresses both Codex findings from the prior round. The one new issue (unguarded "$PY" invocation when the empty-PY case is hit) is minor — a model following the skill will typically recover — but is worth a quick fix before merge since the snippet documents a contract it doesn't enforce inline.
Everything else is in order. Ready to merge after the PY-empty guard is addressed.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is needed before merge; no reviewers assigned (solo-maintained repo, author is the only human contributor).
Sent by Cursor Approval Agent: Pull Request Router and Approver
PR Review: feat: add session-flow plugin — Follow-up on 9e37eee
Gather context and review latest commit
Verify PY-empty guard was addressed (open item from prior review)
Check Codex finding: MultiEdit missing from _FILE_MODIFYING_TOOLS
Check Codex finding: unrelated handoff chaining via previous_handoff
Scan for any new issues introduced by merge
Post final verdict
What 9e37eee Changes
The merge commit brings in only 2774ffa (code-tidying plugin) from main. No session-flow files were modified. All prior state carries forward unchanged from c747602.
Carried Open Item: PY-empty guard — still unaddressed
The prior review verdict was "Ready to merge after the PY-empty guard is addressed." It has not been addressed.
The prose on line 46 says "If PY resolves empty … skip metrics extraction and note why" — but that instruction appears after both invocations. When PY="", bash evaluates "" "$PARSER" … as a command with an empty name and emits bash: : command not found before the model reaches the skip instruction. The model will usually recover from the error by reading the surrounding prose, but the snippet documents a contract it does not enforce.
Fix: wrap both invocations in a guard (Fix this →):
Claude Code's MultiEdit tool carries input.file_path (same shape as Edit — a single path plus an edits array of {old_string, new_string} pairs). Sessions that use MultiEdit will have those tool calls counted in tool usage but the target file will never appear in files_modified, causing incomplete file-change reporting in retrospectives.
If a consumer's .claude/handoffs/ directory contains completed handoffs from a prior (unrelated) task, and they then start a new task's first handoff, PRIOR will resolve to that unrelated file and the new handoff will emit previous_handoff/previous_session_id pointing into the old task's chain. A subsequent /retro --chain-from on the new task would then walk into and aggregate the old task's transcripts.
The correct fix is non-trivial — disambiguating task continuity requires either: (a) the model making a judgment call based on conversation context, (b) requiring an explicit --no-chain flag, or (c) documenting the limitation clearly. Given this is instructional text (not compiled code) and the handoff skill is explicitly a manual workflow (STOP gate, user-initiated), the most pragmatic path is adding a comment to the snippet noting that PRIOR should be omitted when this is demonstrably a new/unrelated task. The current prose does not flag this edge case.
This is a design note rather than a hard blocker — the primary workflow (chain → clear → resume → chain) is correct, and fixing it fully changes the skill's behavior in ways that need deliberate product decisions. Worth a comment or a prose caveat in the "Where handoffs live" section.
CLAUDE.md Checklist (unchanged — all pass)
Criterion
Result
Repo-agnostic
✅
Configurable without editing
✅
Plugin-form-safe
✅
No PII / secrets
✅
Versioned (0.1.0)
✅
Security (no hooks, MCP, network)
✅
Verdict
The merge commit adds nothing to session-flow. The PY-empty guard from the prior review remains unaddressed — that was the explicit merge condition. Two new issues surface from the latest Codex round: MultiEdit missing from the write-tool allowlist (concrete data loss in files_modified) and unrelated handoff chaining (design edge case, needs at minimum a prose caveat).
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is needed before merge; no reviewers assigned (solo-maintained repo, author is the only human contributor).
Sent by Cursor Approval Agent: Pull Request Router and Approver
MultiEdit carries input.file_path with the same shape as Edit, so the existing extraction path is correct. Test added (test_multi_edit_counts_as_file_modification) asserting "src/app.py" in data["files_modified"] for a MultiEdit tool call. Solid fix.
Chain continuity — same task only. Emit previous_handoff / previous_session_id ONLY when this session actually continued the prior handoff's work: it resumed from that handoff (the resume prompt loaded it), or the task/topic clearly matches. A shared handoff directory accumulates entries from unrelated tasks — pointing at the newest file regardless would splice unrelated sessions into one chain…
Clear, unambiguous prose. The existing snippet on line 114 is correctly left intact (it discovers the candidate but the new section establishes when not to use it). This is the right fix for an inherently model-driven judgment call — the model needs the rule, not just the code.
One Carried Open Item: PY-empty guard — still unaddressed
This has been the explicit merge condition since the c747602 review.
Line 46 reads: "If PY resolves empty … skip metrics extraction and note why" — but that prose appears after both invocations. When PY="", bash expands "" "$PARSER" … as a command with an empty name and emits bash: : command not found before the model ever reaches the skip instruction. The probe loop added in c747602 correctly finds Python 3.10+, but this guard was the one remaining piece that wasn't addressed.
whilecursorandcursor.is_file() anddepth<limit: # limit defaults to 10
The function already has seen: set[str] for cycle detection — that prevents infinite loops from circular chains. The depth < limit guard is a secondary hard stop that silently truncates legitimate chains longer than 10 handoffs without any signal in the output JSON. For a task spanning 11+ /clear-and-resume cycles (the exact use case this skill targets), older transcripts are dropped and the retro output presents the truncated aggregate as complete.
The output schema has no warnings field; the summary string doesn't mention truncation. The docstring on line 502 says "NOTE: callers separately prepend the current $CLAUDE_CODE_SESSION_ID" but says nothing about the cap.
The fix doesn't need to remove the limit — it just needs to surface it. The smallest correct change is having extract_chain_from_handoff signal truncation to its caller and propagate a warning into the output JSON:
# extract_chain_from_handoff: return (sids, truncated: bool)# build_multi_session_output: add "warnings": ["chain truncated at 10 entries; pass --limit to extend"]
The b4b16e5 commit cleanly addresses both the MultiEdit gap and the handoff-chaining design note from the prior round. The PY-empty guard remains the one explicit merge condition that hasn't been touched across three review cycles — the probe loop is in place but the guard around the invocations is not. The chain-traversal silent cap is a secondary issue worth fixing before merge since it violates the output contract the file documents.
Ready to merge after the PY-empty guard and the chain-truncation warning.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is needed before merge; no reviewers assigned (solo-maintained repo, author is the only human contributor).
Sent by Cursor Approval Agent: Pull Request Router and Approver
limit raised from 10 → 1000. Hitting 1000 real handoffs for one task is effectively impossible in practice — this resolves the silent-truncation concern for all real workloads.
Explicit cycle detection added via visited_files: set[Path] using cursor.resolve(). Pointer cycles now emit a stderr warning and stop the walk; this is the correct primary fix since cycles (symlinks, typos in previous_handoff) are the real infinite-loop risk.
When the depth guard fires, a stderr warning names the truncation point rather than silencing it.
The prior review asked for a warnings key in the JSON output. The implementation went with stderr instead. Given that the limit is now 1000 (unreachable in practice), and cycles are the real-world failure mode that's now explicitly handled, this divergence is acceptable — the output contract stays clean and the stderr signal is sufficient for the model to detect the anomaly.
New test: test_chain_from_breaks_on_pointer_cycle — constructs an A→B→A cycle and asserts "cycle" in stderr, returncode == 0, and each SID appearing exactly once. Correct and complete. There is no test for the 1000-entry truncation case; given the limit is practically unreachable, this gap is not material.
One Carried Open Item: PY-empty guard — still unaddressed
This has been the explicit merge condition since c747602, three review cycles ago. It has not been touched in b5c6b34 either.
Line 46 says "If PY resolves empty … skip metrics extraction and note why" — but that prose appears after both invocations. When PY="", bash expands "" "$PARSER" … as a command with an empty name and emits bash: : command not found before the model reaches the skip instruction. The probe loop (added in c747602) correctly finds Python 3.10+; the missing piece is the guard around the invocations themselves.
previous_handoff + previous_session_id present IF a prior handoff exists there (omitted otherwise)
context/structure.md (fixed in b4b16e5) now has the "same task only" rule. But the exit checklist in SKILL.md still frames this as a directory-existence check rather than a task-continuity check. A model following the checklist literally without reading structure.md carefully will add unrelated pointers. Design note — not a hard blocker given structure.md is referenced just above the checklist — but the checklist item should read: "IF this session continued the prior handoff's work (task continuity; see context/structure.md)" to be self-consistent.
The NEWEST=$(ls -1 ...) line selects the newest file in the handoff directory unconditionally. The Phase 1.0 prose instructs the model to use the multi-session form only "when handoff save-points exist", which the model interprets as "when there's a relevant chain" — so in practice this is model-judgment-driven. Design note rather than a hard bug; the instructional framing is the correct mitigation for skill-content constraints.
Summary
Item
Status
Chain-traversal silent cap
✅ Fixed in b5c6b34 — limit raised to 1000, cycle detection added, stderr warnings
Cycle-detection test
✅ Added in b5c6b34
MultiEdit in _FILE_MODIFYING_TOOLS + test
✅ Fixed in b4b16e5
Handoff chaining continuity caveat
✅ Fixed in b4b16e5
PY-empty guard in session.md:35–43
🔴 Still open — carried since c747602 (3 cycles)
SKILL.md:161 checklist vs task-continuity
🟡 Design note — not blocking
session.md:43 retro multi-session gate
🟡 Design note — not blocking
Verdict
b5c6b34 correctly resolves the chain-traversal concern — cycle detection is the right primary fix, the raised limit makes the depth guard practically unreachable, and both conditions now emit explicit stderr warnings rather than truncating silently. The implementation diverges from the requested JSON warnings field but the result is sound.
The PY-empty guard is the last explicit merge condition and remains unaddressed after three consecutive review cycles. Everything else is in order.
Ready to merge after the PY-empty guard is applied to session.md:35–43.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is needed before merge; no reviewers assigned (solo-maintained repo, author is the only human contributor).
Sent by Cursor Approval Agent: Pull Request Router and Approver
def_frontmatter_value(line: str) ->str:
"""Extract a scalar frontmatter value: text after the first colon, with any trailing inline YAML comment (` # ...`) and surrounding quotes stripped."""value=line.split(":", 1)[1].strip()
value=value.split(" #", 1)[0].strip()
iflen(value) >=2andvalue[0] ==value[-1] andvalue[0] in {'"', "'"}:
value=value[1:-1]
returnvalue
Applied at both session_id: and previous_handoff: extraction sites in extract_chain_from_handoff. The implementation is correct:
split(":", 1) is safe because the call sites gate on line.startswith("session_id:") / line.startswith("previous_handoff:"), so a colon is always present.
split(" #", 1)[0] correctly uses the space-prefixed comment marker (per YAML spec, inline comments require a space before #), so # inside a path like abc#def.md is preserved.
Quote stripping checks both ends symmetrically before removing, avoiding partial-quote corruption.
Test test_chain_from_strips_inline_yaml_comments constructs a two-entry chain where both frontmatter values carry the documented comment suffixes (# REQUIRED, # CONDITIONAL), runs --chain-from, and asserts both SIDs appear with transcript_present == True. Complete and correct.
2. Continuity gate in session.md — added correctly
Continuity gate first. Use --chain-from ONLY when the newest handoff belongs to the current work: this session resumed from it (the resume prompt loaded it), this session wrote it, or its topic/Task section clearly matches the current task. A shared directory can hold save-points from completed or abandoned tasks — chaining from an unrelated newest file would splice stale sessions into this retro's aggregate. When continuity is absent or unclear, fall back to the single-session form.
Clear and unambiguous. Placed before the snippet so a model reading sequentially encounters the gate before the --chain-from invocation.
- [ ] `previous_handoff` + `previous_session_id` present IF this session continued a prior
handoff's task (chain continuity per `context/structure.md`); omitted otherwise — including when
the directory holds only unrelated-task handoffs
Self-consistent with context/structure.md now. The design note from the b4b16e5 round is resolved.
One Carried Open Item: PY-empty guard — still unaddressed (5th cycle)
This has been the explicit merge condition since c747602.
The prose on line 53 says "If PY resolves empty … skip metrics extraction and note why" — but that instruction appears after both invocations. When PY="", bash evaluates "" "$PARSER" … as a command with an empty name and emits bash: : command not found before the model ever reaches the skip instruction. The probe loop (lines 35–40, added in c747602) correctly finds Python 3.10+; the missing piece is the guard around the two "$PY" invocations themselves.
if [ -n"$PY" ];then# Single-session form:"$PY""$PARSER" --sessions "${CLAUDE_CODE_SESSION_ID}" --base "$SESSION_DATA_DIR"# Multi-session form (handoff chain exists). Set HANDOFF_DIR to the consuming# repo's documented save-point location when it declares one (see the handoff# skill's "Where handoffs live"); the plugin default is .claude/handoffs/.
HANDOFF_DIR=.claude/handoffs
NEWEST=$(ls -1 "$HANDOFF_DIR"/*-handoff-*.md 2>/dev/null | sort | tail -1)"$PY""$PARSER" --chain-from "$NEWEST" --current-session "${CLAUDE_CODE_SESSION_ID}" --base "$SESSION_DATA_DIR"elseecho"No Python 3.10+ found; skipping metrics extraction."fi
Then remove line 53's trailing prose since the else branch handles it.
Summary
Item
Status
YAML comment stripping in _frontmatter_value() + test
✅ Fixed in 1166073
session.md Phase 1.0 continuity gate
✅ Fixed in 1166073
SKILL.md:161 checklist vs task-continuity
✅ Fixed in 1166073
Chain-traversal cap → cycle detection + loud bound
✅ Fixed in b5c6b34
MultiEdit in _FILE_MODIFYING_TOOLS + test
✅ Fixed in b4b16e5
Handoff chaining caveat in structure.md
✅ Fixed in b4b16e5
PY-empty guard in session.md:42–50
🔴 Still open — carried since c747602 (5 cycles)
Verdict
1166073 cleanly resolves the YAML comment stripping finding — the _frontmatter_value() helper is the right abstraction, the strip logic is correct per YAML spec, and the test exercises the documented template exactly. The continuity gate prose and SKILL.md checklist alignment are also solid. Every Codex finding across all rounds is now resolved except one.
The PY-empty guard is the last remaining explicit merge condition and has not been addressed in five consecutive review cycles. Everything else is in order.
Ready to merge after the if [ -n "$PY" ] guard is wrapped around session.md:42–50.
The reason will be displayed to describe this comment to others. Learn more.
Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is needed before merge; no reviewers assigned (solo-maintained repo, author is the only human contributor).
Sent by Cursor Approval Agent: Pull Request Router and Approver
The reason will be displayed to describe this comment to others. Learn more.
Guard parser calls when Python 3.10+ is unavailable
When the Phase 1 probe finds neither python3 nor python at 3.10+, PY stays empty, but this command is still executed before the documented skip note below. In that environment /retro session reports a shell “command not found”/parser failure instead of gracefully skipping metrics as promised; wrap the parser calls in a non-empty $PY check (as the test wrapper does) before running either form.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
Closes melodic-software/medley#1284 (EPIC melodic-software/medley#1273).
What
New
session-flowplugin bundling four session-lifecycle skills as one cohesive capability:/session-flow:workflow/session-flow:handoff/clear-and-resume? Full handoff file (seven sections + TaskList snapshot + session-id chain frontmatter) or prompt-only; hard STOP gate after emitting the save-point/session-flow:retro/session-flow:orchestration-briefMarketplace entry:
category: productivity, tagsorchestration+ per-component. Explicit semver0.1.0inplugin.jsononly.Decoupling (playbook per-plugin gate)
medley, no.work/, no source-repo tooling paths). Source-repo-specific machinery re-seamed: workflow stages route to the CONSUMER's own stage skills when they exist and degrade gracefully to inline execution; convention/quality-gate content routes through the consumer'sCLAUDE.md/.claude/rules/..claude/handoffs/(project files by design — they travel with the repo). The bundled parser resolves handoff chains in both flat and subdir-prefixed layouts.${CLAUDE_PLUGIN_ROOT}; retro score history persists under${CLAUDE_PLUGIN_DATA}(per-project files), never in the consumer's repo. No../reach-outs./retro,/handoffinside the plugin); no dependency on any other plugin.userConfig— the only variability that surfaced (artifact location, stage skills, conventions) routes through consumer context (no speculative knobs).exceptclauses parenthesized so the script runs on Python 3.10+ (was 3.14+);matchstatements set the 3.10 floor.Gate evidence (speed-adjusted per issue)
claude plugin validate --strict ./plugins/session-flow→ Validation passed;claude plugin validate --strict .(catalog manifest) → Validation passed.claude plugin detailsprojected token cost: ~543 tok always-on (handoff ~110, orchestration-brief ~190, retro ~130, workflow ~110; on-invoke ~3.5k / ~2.4k / ~1.9k / ~2.1k).--plugin-dirsmoke test in a clean non-source fixture repo (headlessclaude -p): skill loaded under thesession-flow:namespace,context/steps.mdread from the plugin root, content answered correctly ("Skill invoked:session-flow:workflow. Loaded content defines 9 numbered workflow stages (0–8). Stage 7: Verify outcome.").parse-transcript.test.shwrapper integrates withscripts/run-plugin-tests.shand SKIPs cleanly when Python 3.10+/pytest is absent. shellcheck clean; markdownlint clean; typos clean.Security review (playbook acceptance)
userConfig. Surfaces 1/2/3: N/A.${CLAUDE_PLUGIN_ROOT}, state via${CLAUDE_PLUGIN_DATA}, no../reach-outs, no absolute/machine paths. The parser reads only local~/.claude/projects/transcripts and handoff files the consumer created.Docs consulted this session per the fresh-docs mandate: https://code.claude.com/docs/en/plugins-reference (manifest/marketplace schemas,
${CLAUDE_PLUGIN_DATA}resolution, validate--strictsemantics), https://code.claude.com/docs/en/skills (frontmatter fields, namespacing).Note
Low Risk
Adds markdown skills and an offline local transcript parser; the only writes are user-requested handoff files in the project and approval-gated rule/memory edits—no hooks, network, or privileged automation.
Overview
Adds the
session-flowplugin (0.1.0) to the marketplace and root README catalog under productivity, shipping four repo-agnostic skills for session lifecycle management.workflownavigates a staged pipeline (contract through retro), infers position from artifacts, and exposes modes for full steps, pre-PR gates, wrap-up, philosophy, and spec-first/clearbetween stages—routing to the consumer’s own stage skills when present.handoffimplements the/clear-and-resume pattern: durable save-points (default.claude/handoffs/) with chainedsession_id/previous_handofffrontmatter, TaskList reconstitution, and a mandatory STOP after the resume prompt;orchestration-briefprimes the session or exports paste-ready worker/handoff briefs for six delegation imperatives.retroruns session / codify / trends / quick modes with approval-gated codification into repo rules or auto-memory; score history lives under${CLAUDE_PLUGIN_DATA}. A new stdlib-onlyparse_transcript.py(Python 3.10+, pytest contract tests + optional shell wrapper) reads local Claude Code JSONL transcripts and aggregates metrics across handoff chains via--chain-from.Reviewed by Cursor Bugbot for commit 1166073. Bugbot is set up for automated code reviews on this repo. Configure here.