Chat session log — scaffolder — 2026-03-16

Session goal

Assess impact of filesystem MCP access on workflow, design new session architecture, create GitHub issues for all work. No building this session.

Outcome

Design confirmed. 13 GitHub issues written and ready for Harley. Session state files written directly to repo via MCP — first use of new pattern.

Decisions made

Filesystem MCP changes everything about session context

Joker now has direct read/write access to D:\Claude via MCP. The handoff doc pattern (produce → download → manually move → upload to Project Files) is retired as the context mechanism. Joker reads and writes session files directly. Needs an ADR in docs/decisions/.

Dual session state files

sessions/CURRENT.md → renamed to sessions/CURRENT-CODE.md (Harley’s state). New file sessions/CURRENT-CHAT.md added (Joker’s state). Both live in sessions/, both go to git, both are read by the other AI at session start for full context.

SESSION log files for Joker

Joker writes immutable session logs to sessions/logs/ at session end, same as Harley. Format: v[XX].[XX].[XX]-[YYYY]-[MM]-[DD]-chat-[operator].md.

PROJECT-INSTRUCTIONS.md stripped to persona + file reading list

With MCP access, PROJECT-INSTRUCTIONS no longer needs embedded workflow, folder structure, or discovery process. Strip to: persona, operator overrides, hard rules, and on-session-start file reading list. Target ~2KB. Workflow lives in CHAT-REFERENCE.md and skills — never duplicated in PROJECT-INSTRUCTIONS.

Session skills bridge Joker and Harley

Two new Chat skills: sc-session-start (reads both CURRENT files, confirms goal) and sc-session-end (writes CURRENT-CHAT.md + session log, suggests AR name). Harley’s existing skills updated to match new file names and drop the “upload to Project Files” reminder.

CURRENT-CHAT.md belongs in sessions/ not _system/

Project-specific. Goes to git. Visible to team. Mirrors CURRENT-CODE.md pattern exactly. One per project, not one global file.

Issue files are dated and named, never overwrite the template

Template stays at _system/GITHUB-ISSUES.md. Dated issue files written alongside it: _system/GITHUB-ISSUES-[date]-[topic].md.

SOURCE OF TRUTH for templates is scaffolder project on D: drive

_system/ files are operator reference copies and may be stale. Always read from D:\Claude\projects\scaffolder\templates\ first.

RFCs/ADRs touched

None produced this session. ADR needed for filesystem MCP session architecture decision — captured in issue #10 (workflow issue).

Issues created this session

All 13 issues written to: D:\Claude_system\GITHUB-ISSUES-2026-03-16-session-architecture.md Ready for Harley to open. Milestone: v0.10.0.

#287 refactor: rename sessions/CURRENT.md to sessions/CURRENT-CODE.md #288 feat: add sessions/CURRENT-CHAT.md template for Joker session state #289 feat: add chat session log format to sessions/logs/ #290 feat: update session-start skill to also read CURRENT-CHAT.md #291 feat: update session-end skill to write CURRENT-CODE.md, drop upload reminder #292 feat: new Chat skill sc-session-start for Joker session initialisation #293 feat: new Chat skill sc-session-end for Joker session close #294 refactor: strip PROJECT-INSTRUCTIONS.md template to persona and file reading list #295 docs: update CHAT-REFERENCE.md for MCP access and new session file names #296 workflow: Joker writes session state files directly via filesystem MCP #297 chore: consolidate GITHUB-ISSUES.md template to _system/ only #298 chore: apply issues workflow patch to templates/STANDARDS.md #299 chore: remove stale SCAFFOLDER-HANDOFF-2026-03-16-v2.md from _system/

Handoff to Harley

No Harley work this session. Next Harley task: open the 13 issues above. File: D:\Claude_system\GITHUB-ISSUES-2026-03-16-session-architecture.md

Open items

GitHub issues triage (#242–#283 + new) — separate chat
Skill fixes sc-discovery and sc-doc-production (#244, #245) — separate chat
sc-session-start and sc-session-end skill build — separate chat, after issues open

Next session

Suggested name: build — session architecture — 2026-03-16 Goal: Build the session architecture changes (issues 1–10) once Harley has opened all issues and they are on the milestone.