Next Session Bootloader#

Next Session Bootloader#

Last updated: 2026-04-09 by Cowork session (AI Lead) handing off to its successor.

This doc is a bootloader, not a summary. Read it, read the linked docs it points you at, internalize the state, then stop and wait for Dan's input. Do NOT start doing work off the "First Actions" list until Dan tells you to — that list is what he's planning to do with you, not a script to execute autonomously.

Who you are in this workflow#

You are the AI Lead in Dan's CSDLC methodology (see methodology/process.md and methodology/thesis.md). The three roles are Human (Dan), AI Lead (you, running in Cowork), and Sub-agents (Claude Code, spawned per-story via the foundry-cc-bridge we're designing). Your job is refinement, orchestration, and review — not direct code execution.

A previous persona called "Clay" lived in OpenClaw. Clay stays there. Dan has explicitly deferred picking a Cowork-side persona — don't pick one on your own, just be thoughtful and direct. If Dan wants to name you later, he'll bring it up.

Current focus#

Current focus#

Refining the foundry-cc-bridge design doc at projects/foundry-cc-bridge/design-draft. This is a new standalone project — an MCP server that lets you hand refined stories off to Claude Code sub-agents, running them in git worktrees and reporting results back via Foundry annotations. v0 is ~1-2 evenings of work once the design is settled.

v1 launch is blocked on Foundry bug #105 (unauthenticated /mcp/* write routes) — the bridge can't safely post to Foundry from CI runners or any non-trusted-network context until that's fixed. Track that issue closely during refinement; it may shape the bridge's auth model.

Active documents (read these in order)#

1. projects/foundry-cc-bridge/design-draft — The design doc we're about to refine. Read the whole thing, especially the "Open Questions" section (8 items) and the "Decisions Log" (7 decisions already locked in).
2. methodology/thesis.md — Dan's CSDLC thesis, co-authored with Clay. Explains the methodology the bridge operationalizes.
3. methodology/process.md — Operational CSDLC process doc. Three roles, seven-step pipeline, refinement as the core practice.
4. projects/foundry/design.md (if it exists — didn't verify path) — For context on Foundry itself.

Recent decisions (locked in, do not relitigate without reason)#

1. Foundry-cc-bridge is a standalone Python project, not embedded in Foundry. Separation of concerns: Foundry owns docs, the bridge owns execution.
2. Bridge runs locally on Dan's Mac, inherits gh/claude/git auth. No remote hosting in v1.
3. Primary completion signal is a Foundry annotation write-back to the story doc, posted by the bridge after a run finishes. You'll see it on the next get_page / list_annotations call.
4. Secondary completion signal is GitHub's own mobile notifications — NOT Slack. This was a late simplification. The v3 "Slack DM" phase from the original draft has been obsoleted; update the draft to reflect this during refinement. GitHub already sends push notifications on PR opened / reviewed / checks complete, and Dan already has the GitHub mobile app configured. One fewer moving part, one fewer secret.
5. Inbound mobile UX is iPad + remote desktop to the Mac (Tailscale + macOS Screen Sharing as the starting setup). NOT a custom messaging MCP. This preserves session continuity perfectly because the iPad is just glass into the running session. Details in the "Decisions Log" section of the design draft.
6. Dispatch is a manual fallback for quick mobile one-shots, not a primary channel. It cannot inject into existing sessions (architectural + security constraint) and always spawns ephemeral new sessions.
7. Git worktrees, one per run, under ../worktrees/<story-slug> (sibling of main repo). Unique branch names via ulid suffix.
8. Single mutex in v1 — no concurrent runs. Debuggability over throughput. Concurrent orchestration is deferred to v4.
9. Visual QA via Claude in Chrome MCP is a free win of staying in Cowork — after CC opens a PR, you can pull up the preview deploy URL in Chrome, screenshot, click through, verify. This is now an expected step in the CSDLC review flow and should be mentioned in the design during refinement.
10. We're staying with Cowork, not building a custom Agent SDK harness. Dan considered it on a walk — we talked through the tradeoffs and agreed to run at least one full CSDLC cycle in Cowork with the bridge in place before reconsidering. The Cowork security constraints (MCP pull-only, no injection into live sessions) are features, not bugs.

First actions for the next session (wait for Dan's go-ahead)#

First actions for the next session (wait for Dan's go-ahead)#

These are the things Dan and I planned to do together at the start of the next session. Propose them back to Dan in order and let him confirm or re-sequence:

1. Remind Dan to rotate the GitHub PAT that leaked into the previous session's conversation context (gho_PSq1pjZ..., was in foundry/.env). STILL UNROTATED as of 2026-04-09 session end — Dan was reminded twice, hasn't done it yet. Mention it once, don't nag.
2. Clean up the corrupted projects/foundry-cc-bridge/design page. See "Gotchas" section below for what happened. Simplest fix: delete it (if Foundry has a delete_doc affordance — still didn't verify), or recreate it fresh with the refined content from design-draft.
3. Begin refining the bridge design doc at projects/foundry-cc-bridge/design-draft. Start with the "Open Questions" section — there are 8 items that need Dan's input to lock down. Pay special attention to questions touching on auth/identity, since Foundry bug #105 (unauthenticated writes) is still open and shapes the bridge's posture.
4. Potentially draft a separate mini-design for "Foundry as shared async queue" (Open Question #2) as projects/foundry-chat-queue/design.

Done in the previous session, do not redo:

• ✅ Cowork "engineering" plugin installed (and we mapped out exactly what its bundled GitHub connector can and can't do — see Gotchas #7).
• ✅ All 8 Foundry bugs filed as GitHub issues #98–#105 on danhannah94/foundry. List with numbers is in the "Foundry bugs filed" section below.
• ✅ Tailscale + Jump Desktop set up for iPad → Mac remote, validating decision #5 (inbound mobile UX = remote desktop, not custom messaging MCP). Works great.

Foundry bugs to file (discovered in smoke test)#

Foundry bugs filed (was: to file — all done as of 2026-04-09)#

All 8 bugs are filed on danhannah94/foundry. Filing was done via Claude in Chrome MCP after the GitHub-MCP-write path was found to be blocked (see Gotchas #7).

The two highest-priority for the bridge work are #105 (blocks v1 launch — the bridge will post to Foundry from non-trusted networks) and #103 (silent-append on heading mismatch — it's the bug that'll bite the AI Lead in every refinement session until fixed; my own update_section workflow has to use the workaround in Gotcha #1).

Gotchas (read these, do not rediscover)#

Gotchas (read these, do not rediscover)#

1. Foundry update_section has append-on-missing semantics. (Now filed as bug #103 — but until it's fixed, this workaround is mandatory.) If you pass a heading that doesn't resolve, instead of returning a 404 it silently appends your content as a new section with the same name, producing duplicates like Overview [2]. This is how the original projects/foundry-cc-bridge/design page got corrupted. When updating nested sections, the correct heading format is # Page H1 Title > ## H2 Title > ### H3 Title — note the # prefix on every level, separated by >. The tool description says "## Overview" or "## Architecture > ### Tech Stack" but it lies about nested-doc semantics. Workaround if in doubt: create a fresh blank doc via create_doc(template='blank'), then do a single update_section on the H1 with the entire content (including all H2/H3 headings) as body text — Foundry will parse them into proper child sections on save. This is how status/next and projects/foundry-cc-bridge/design-draft were written. Verified working pattern for in-place edits: use the # H1 > ## H2 format and ALWAYS re-fetch with get_page after each update to confirm no silent append. The AI Lead's previous session updated this very doc using that pattern.

2. MCP schema reloads. (Now filed as bug #102.) Sometimes an MCP tool call fails with a weird schema error (missing required param, wrong type). The fix is usually to call ToolSearch with select:<full_tool_name> to force a schema reload, then retry. Dan's aware of this pattern.

3. Sandbox cannot reach github.com or fly.dev. WebFetch and curl return 403 from the sandbox for Dan's repos and Foundry's deployed instance. If you need to read a file from the Foundry repo, use the local clone at /sessions/<session-id>/mnt/foundry instead. This is also why we couldn't use the gh CLI with a PAT for issue filing — the sandbox can't reach github.com regardless of auth.

4. GitHub PAT in .env — STILL NOT ROTATED. /sessions/<session-id>/mnt/foundry/.env contains GITHUB_TOKEN=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 and FOUNDRY_WRITE_TOKEN=84b05d673a19a8e4a423f89b888d6505f966d04e564fe0781e68c8cf5853f4ab. The GitHub token is considered compromised (touched by LLM context) and Dan needs to rotate it. As of 2026-04-09 session end, this is still unrotated despite two reminders. Don't use it; don't echo it unnecessarily. Mention it once at the start of next session, then drop it.

5. Cowork cannot reach into live sessions. Nothing external (MCP tool, webhook, scheduled task, other session) can inject a turn into a running Cowork session. This is a load-bearing security property, not a limitation to work around. Every "messaging" design must account for this. If you're tempted to build a feature that poll-wakes the session externally — stop and re-read this line.

6. Foundry is Dan's own deployed instance. https://foundry-claymore.fly.dev. Uses SSE transport at /mcp/sse, NOT the root URL. If connector setup fails, verify the URL ends in /mcp/sse.

7. Cowork's GitHub story is more tangled than it looks. Three different "GitHub" things, only one of which actually writes. (Hard-won knowledge from the 2026-04-09 session.)

There are three distinct GitHub integrations you might encounter in Cowork, and they are NOT interchangeable:

• (a) First-party "GitHub Integration" connector — The OAuth-handoff entry that ships with Cowork. This grants OAuth scopes for Chat/Projects/Claude-Code-repo-browsing UI features. It exposes ZERO MCP tools to the agent. No list_issues, no create_issue, nothing. If you only have this connected, you cannot file issues from a session no matter what scopes you grant. Visible in screenshots but the tool list is empty.

• (b) engineering plugin's bundled GitHub connector — Same shape as (a). Bundled with the plugin for convenience but gives you the same zero-tool OAuth handoff. Installing the engineering plugin does NOT give you write access to GitHub. (It's still worth installing for the skills — code-review, debug, tech-debt, etc. — just don't expect tools out of its GitHub entry.)

• (c) Custom MCP connector pointing at https://api.githubcopilot.com/mcp — GitHub's official remote MCP server. This DOES expose the full read+write toolset (list_issues, create_issue, add_issue_comment, create_pull_request, etc.). HOWEVER: it requires (i) an active GitHub Copilot subscription on Dan's account, AND (ii) the underlying GitHub App token to have the right scopes — and in the 2026-04-09 session, even with Copilot enabled and the connector freshly OAuth-flowed, all writes returned 403 Resource not accessible by integration. Reads worked fine. The diagnosis: the GitHub App backing api.githubcopilot.com/mcp doesn't auto-grant write scopes through the Copilot OAuth flow, and there's no obvious in-product path to escalate. Worth retrying in a future session in case GitHub fixes the scope handling.

• (d) github/github-mcp-server self-hosted binary — The escape hatch we did NOT try but should next time if the bridge work needs GitHub writes from sessions. Dan runs the binary locally on his Mac with a fine-grained PAT in its env, and Cowork connects to it as a local-stdio MCP. PAT never enters LLM context. This is the pattern that should work for the bridge orchestration anyway.

For the 2026-04-09 session, after exhausting (a)/(b)/(c), we pivoted to Claude in Chrome MCP to drive github.com directly: filled the new-issue form via form_input on stable element refs (ref_146 title, ref_181 body, ref_214 Create button, ref_209 "Create more" checkbox) and submitted 8 issues in ~2 minutes. The "Create more" checkbox is the key — it clears the form on submit and stays on the same URL, so refs stay stable across submissions and you don't have to re-navigate. This pattern is the recommended fallback for any bulk-content-into-a-web-app task where the dedicated MCP path is blocked.

8. Claude Code in GitHub Actions = API key only. The anthropics/claude-code-action GitHub Action does not work with Max-plan OAuth tokens. There was a brief window (~v1.0.44) where claude setup-token worked, but Anthropic's February 2026 ToS update explicitly prohibits using Free/Pro/Max OAuth tokens outside of Claude.ai and the Claude Code CLI itself. CI/CD use is now ANTHROPIC_API_KEY only (consumption billing). If the bridge work or @claude triggers ever land on the foundry repo, plan for metered API spend with a tight monthly cap set in the Anthropic console.

Open pins (things deferred, don't lose)#

Open pins (things deferred, don't lose)#

• Clay-successor persona for Cowork. Deferred. Dan will bring it up when he wants to.
• Foundry-as-chat shared queue (projects/foundry-chat-queue/design). Open Question #2 in the design draft. Probably its own mini-project.
• Skills kit for CSDLC: csdlc:session-start (reads this doc), csdlc:session-end (writes this doc), csdlc:standup, csdlc:craft-agent-prompt. Not yet built. The 2026-04-09 session-end pattern (re-writing this doc by hand via update_section) would be a good first target for csdlc:session-end.
• Cowork engineering plugin's skills (code-review, debug, tech-debt, system-design, testing-strategy, etc.) may subsume some of the CSDLC skills. Investigate during the bridge refinement work — engineering:system-design and engineering:architecture look most relevant.
• Updating Foundry templates to be CC-compatible and to fix the *(Optional)* heading issue from bug #104.
• Try github/github-mcp-server self-hosted binary on Dan's Mac as the long-term GitHub-write path for bridge orchestration. See Gotcha #7(d).
• Tailscale + Jump Desktop are live — the iPad-as-glass-into-Mac decision (#5) is now validated in practice. Worth mentioning in the bridge design doc as the established mobile-out-of-the-house workflow.

First thing to say back to Dan#

First thing to say back to Dan#

Something short like: "I'm caught up from status/next.md. Last session we filed all 8 Foundry bugs (#98–#105) and got Tailscale + Jump Desktop running. Today we're refining the foundry-cc-bridge design draft — first steps are PAT rotation reminder, cleaning up the corrupted design page, then working through the 8 open questions in the draft. Bug #105 (unauthenticated /mcp/* writes) blocks v1 launch and may shape the auth model — heads up on that during refinement. Ready when you are — which of those do you want to start with?"

Then wait.