GITHUB-ISSUES — Session architecture + cleanup — 2026-03-16

What this file is

Issue-only doc. NOT a TASKS.md file. Harley’s job: open the GitHub issues listed below and stop. Do not build anything. Do not create branches. Do not write code.

Rules for Harley

Run gh label list before creating any issues — never create a label that already exists
Create issues one at a time
Confirm each issue URL before moving to the next
Do not modify issue content
Report any failures to operator immediately
Stop after all issues are created — no other work

Issues

Issue 1 — rename CURRENT.md to CURRENT-CODE.md

gh issue create \
  --title "refactor: rename sessions/CURRENT.md to sessions/CURRENT-CODE.md" \
  --label "enhancement" \
  --milestone "v0.10.0" \
  --body "sessions/CURRENT.md is Harley's session state file. Rename to CURRENT-CODE.md to distinguish it from the new CURRENT-CHAT.md (Joker's session state). Update all references: CLAUDE.md template, session-start skill, session-end skill, sc-start command, sc-end command, sc-done command, START-HERE.md, CHAT-REFERENCE.md, PROJECT-INSTRUCTIONS.md template, and any other files that reference sessions/CURRENT.md."

Issue 2 — add CURRENT-CHAT.md template

gh issue create \
  --title "feat: add sessions/CURRENT-CHAT.md template for Joker session state" \
  --label "enhancement" \
  --milestone "v0.10.0" \
  --body "Create templates/CURRENT-CHAT.md — the Joker session state file. Joker writes this at session end via filesystem MCP. Harley reads it at session start for context. Contents: session goal and outcome, decisions made (with ADR/RFC refs), RFCs produced or updated (status + path), ADRs proposed or accepted, issues created (number + title), what was handed to Harley (branch, task file), open items and unresolved questions, files to read before next Joker session, suggested next session name and goal."

Issue 3 — add chat session log format

gh issue create \
  --title "feat: add chat session log format to sessions/logs/" \
  --label "enhancement" \
  --milestone "v0.10.0" \
  --body "Joker writes immutable session logs to sessions/logs/ at the end of every chat session, mirroring what Harley already does. Filename format: v[XX].[XX].[XX]-[YYYY]-[MM]-[DD]-[HHMM]-chat-[operator].md. Contents: frontmatter (version, date, time, type: chat, operator, project), session goal, outcome summary, decisions made, RFCs/ADRs touched, issues created, handoff to Harley, next steps. Add this format to the session log spec and document alongside the existing code log format."

Issue 4 — update session-start skill to read CURRENT-CHAT.md

gh issue create \
  --title "feat: update session-start skill to also read CURRENT-CHAT.md" \
  --label "enhancement" \
  --milestone "v0.10.0" \
  --body "Harley's session-start skill currently reads sessions/CURRENT.md (to become CURRENT-CODE.md per #[rename issue]). Update it to also read sessions/CURRENT-CHAT.md so Harley has full context on what Joker decided last session before starting any work. Summarise both files in the session start report. If CURRENT-CHAT.md does not exist, note this and proceed normally. Depends on: rename issue (CURRENT.md → CURRENT-CODE.md)."

Issue 5 — update session-end skill for new file names

gh issue create \
  --title "feat: update session-end skill to write CURRENT-CODE.md, drop upload reminder" \
  --label "enhancement" \
  --milestone "v0.10.0" \
  --body "Harley's session-end skill currently writes sessions/CURRENT.md and reminds the operator to upload it to Chat Project Files. Two changes: (1) update all references from CURRENT.md to CURRENT-CODE.md, (2) remove the 'Upload updated sessions/CURRENT.md to your Chat Project Files' reminder — this is no longer needed now that Joker reads files directly via filesystem MCP. Depends on: rename issue (CURRENT.md → CURRENT-CODE.md)."

Issue 6 — new Chat skill: sc-session-start

gh issue create \
  --title "feat: new Chat skill sc-session-start for Joker session initialisation" \
  --label "enhancement" \
  --milestone "v0.10.0" \
  --body "Create a new Chat skill (zip, uploaded to Settings → Skills) that Joker uses at the start of every session. Behaviour: read sessions/CURRENT-CHAT.md and summarise last Joker session state; read sessions/CURRENT-CODE.md and summarise last Harley session state; confirm the session goal with the operator before doing any work. If CURRENT-CHAT.md does not exist (new project), note this and prompt for goal. Skill should trigger automatically when starting a Joker session on a project."

Issue 7 — new Chat skill: sc-session-end

gh issue create \
  --title "feat: new Chat skill sc-session-end for Joker session close" \
  --label "enhancement" \
  --milestone "v0.10.0" \
  --body "Create a new Chat skill (zip, uploaded to Settings → Skills) that Joker uses at the end of every session. Behaviour: write sessions/CURRENT-CHAT.md with full session state (decisions, RFCs/ADRs touched, issues created, handoff to Harley, open items, next session suggestion); write an immutable session log to sessions/logs/ with filename format v[XX].[XX].[XX]-[YYYY]-[MM]-[DD]-[HHMM]-chat-[operator].md; suggest an AR name for the conversation. Joker writes files directly via filesystem MCP — no download or copy step required."

Issue 8 — strip PROJECT-INSTRUCTIONS.md template

gh issue create \
  --title "refactor: strip PROJECT-INSTRUCTIONS.md template to persona and file reading list" \
  --label "enhancement" \
  --milestone "v0.10.0" \
  --body "PROJECT-INSTRUCTIONS.md template is currently ~16KB with embedded workflow, folder structure, discovery process, and session management. With filesystem MCP, Joker reads these from source files directly. Strip the template to: (1) persona and personality rules, (2) operator overrides (names, environment, brain fog note), (3) hard rules (confirm before generating, number questions, etc.), (4) on session start, read these files list: _system/CHAT-REFERENCE.md, _system/STANDARDS.md, sessions/CURRENT-CHAT.md, sessions/CURRENT-CODE.md. Target: under 2KB. Workflow and standards live in the files Joker reads — never duplicated in PROJECT-INSTRUCTIONS again."

Issue 9 — update CHAT-REFERENCE.md for new session architecture

gh issue create \
  --title "docs: update CHAT-REFERENCE.md for MCP access and new session file names" \
  --label "documentation" \
  --milestone "v0.10.0" \
  --body "CHAT-REFERENCE.md needs to reflect the new session architecture: (1) rename all references from sessions/CURRENT.md to sessions/CURRENT-CODE.md and add sessions/CURRENT-CHAT.md, (2) update session start/end process to reflect that Joker reads files directly via filesystem MCP — no manual uploads to Project Files for context, (3) add sc-session-start and sc-session-end to skill references, (4) remove the 'Upload sessions/CURRENT.md to Project Files' instruction from existing project start flow, (5) update key locations section to note MCP-accessible paths."

Issue 10 — workflow decision: Joker writes session files via MCP

gh issue create \
  --title "workflow: Joker writes session state files directly via filesystem MCP" \
  --label "workflow" \
  --milestone "v0.10.0" \
  --body "Decision to record: Joker now writes sessions/CURRENT-CHAT.md and sessions/logs/ entries directly via filesystem MCP at session end. The handoff doc (SCAFFOLDER-HANDOFF-*.md produced as a download and manually uploaded to Project Files) is retired as the context mechanism between Joker sessions. Context is maintained via sessions/CURRENT-CHAT.md in the project repo, written by Joker and read by Joker at next session start. This decision should be recorded as an ADR in docs/decisions/."

Issue 11 — consolidate GITHUB-ISSUES.md to _system/

gh issue create \
  --title "chore: consolidate GITHUB-ISSUES.md template to _system/ only" \
  --label "chore" \
  --milestone "v0.10.0" \
  --body "GITHUB-ISSUES.md exists in two places: D:\Claude\GITHUB-ISSUES.md (root, newer version with Notes for Joker section) and D:\Claude\_system\GITHUB-ISSUES.md (slightly older). Merge the best of both into _system/GITHUB-ISSUES.md as the single canonical copy. Remove the root copy. The root file at D:\Claude\ was a temporary working copy — it should not live there permanently. Also confirm this file is referenced correctly in CHAT-REFERENCE.md and STANDARDS.md."

Issue 12 — apply STANDARDS.md issues workflow patch

gh issue create \
  --title "chore: apply issues workflow patch to templates/STANDARDS.md" \
  --label "chore" \
  --milestone "v0.10.0" \
  --body "D:\Claude\STANDARDS-issues-workflow-patch.md contains the updated issues workflow section (canonical label system, Conventional Commits prefix mapping, GITHUB-ISSUES.md template reference). Apply this patch: replace the existing '## Issues workflow' section in templates/STANDARDS.md with the content from the patch file. Also apply to the live scaffolder project's STANDARDS.md. After applying, delete the patch file from D:\Claude\ root. Also add canonical label list to CLAUDE.md template as noted in previous session."

Issue 13 — remove stale handoff doc from _system/

gh issue create \
  --title "chore: remove stale SCAFFOLDER-HANDOFF-2026-03-16-v2.md from _system/" \
  --label "chore" \
  --milestone "v0.10.0" \
  --body "SCAFFOLDER-HANDOFF-2026-03-16-v2.md is sitting in D:\Claude\_system\ — it is a session handoff doc, not a system file, and does not belong there. Once the new session architecture (CURRENT-CHAT.md) is in place, handoff docs are retired entirely. Remove this file from _system/. No content needs to be preserved — the v3 handoff in Project Files and the new CURRENT-CHAT.md approach supersede it."