forge-refactor: Handoff¶

Date: 2026-04-28 Owner: Opus worker (forge-refactor_Opus47) Parent session: biz-inbox_Sonnet46

The Goal¶

Prune, rewrite, and harden the forge workspace so that every future Claude session boots with accurate context, no dead weight, and correct architecture. The output is a forge where MEMORY.md, CLAUDE.md, system-map/steering.md, and all skills reflect exactly what exists today, not what existed 3 months ago.

Justin will do some of this himself. Your job is the clear-cut mechanical work plus drafted proposals for the decisions that need his input.

Current State¶

Forge is working well but has accumulated significant drift: - Architecture has evolved (TickTick out, Notion/Google/Forge as the three-system stack, manager bot as unified output, Ava as coordinator layer, full email suite built) - Dead tmux sessions, stale session JSON files, and old task files are sitting around - MEMORY.md has entries for things that have changed or no longer exist - system-map/steering.md was written before the current architecture - notify.sh still has Discord/Slack as active channels, neither is used - n8n has TickTick workflows that are now legacy - Skills may have stale trigger descriptions

The parent session (biz-inbox_Sonnet46) built and shipped today: - Full Gmail workflow suite (12 workflows in infra/n8n/workflows/) - @Manager_JForgeBot as unified output channel (token in ~/.forge-secrets/telegram-manager.env) - @Ava_JForgeBot was built by another worker today (forge-telegram-ava.service running) - Email voice/sign-off rules saved to memory - Second brain stack decision: Notion/Google/Forge only, TickTick out

Files You'll Work With¶

File / Path	Purpose
`MEMORY.md`	Primary agent memory index, audit every entry
`CLAUDE.md`	Session bootstrap, update stale sections
`system-map/steering.md`	Agent routing rules, needs full rewrite
`system-map/fleet.md`	Fleet map, verify still accurate
`system-map/architecture.md`	System topology, verify still accurate
`scripts/notify.sh`	Notification routing, prune Discord/Slack, keep manager
`infra/n8n/workflows/`	n8n workflow JSONs, flag TickTick ones as legacy
`.claude/skills/`	Skills, audit trigger descriptions
`~/.claude/sessions/*.json`	Session files, clean dead ones
`tasks/pending/`, `tasks/completed/`, `tasks/failed/`	Task queue, archive old items
`logs/`	Log files, archive or rotate old ones
`memory/general/`	Topical memory files, check for staleness
`memory/handoffs/`	Old handoffs, archive anything >30 days

Approach¶

Phase 1: Mechanical Prune (do this autonomously)¶

Kill dead tmux sessions, any session from before today that isn't biz-inbox_Sonnet46, forge-home_Opus47, forge-cleanup_Opus47, notion-scaffold_Sonnet46, n8n-telegram_Opus47, mkdocs-build_Opus47. Check they're truly idle before killing.
Clean dead session JSON files, ~/.claude/sessions/*.json for processes that no longer exist. Keep files for live sessions.
Archive old task files, anything in tasks/completed/ and tasks/failed/ older than 7 days → tasks/archive/YYYY-MM/. Keep tasks/pending/ untouched.
Rotate old logs, anything in logs/ older than 14 days that isn't a current rotating log → logs/archive/. Don't delete, just move.
Archive old handoffs, memory/handoffs/ entries older than 30 days → memory/handoffs/archive/.
Prune notify.sh, remove Discord and Slack from the critical dispatch path (they're not configured and never used). Keep the functions but don't call them by default. Manager bot is the real channel.

Phase 2: Audit and Draft (produce proposals for Justin)¶

MEMORY.md audit, go line by line. For each entry:
Verify the referenced file/tool/script still exists at the stated path
Flag entries that reference TickTick (mark as legacy)
Flag entries where the description contradicts current reality
Produce a docs/refactor/memory-audit-2026-04-28.md with proposed edits (don't auto-apply the big ones)
Apply small fixes (typos, wrong paths) directly
system-map/steering.md rewrite draft, the current steering.md was written before the current architecture. Write a new version that reflects:
Manager bot as unified output for all agents
Ava (@Ava_JForgeBot) as coordinator/LifeOS assistant
Notion/Google/Forge as the three-system stack (TickTick out)
Email suite via n8n (12 workflows)
Dispatcher → manager bot for completion notifications
Save the draft to docs/refactor/steering-draft-2026-04-28.md, don't overwrite the live file until Justin reviews
Skills audit, list every skill in .claude/skills/ and ~/.claude/skills/. For each:
Is the trigger description accurate?
Does it reference the right files/commands?
Is there a missing skill for something built today (email workflows, manager bot)?
Produce docs/refactor/skills-audit-2026-04-28.md with recommendations
CLAUDE.md gaps, review CLAUDE.md and note what's missing or wrong given the new architecture. Produce a short diff/notes file rather than rewriting it directly.

Phase 3: Register new tools (do autonomously)¶

Any tool/workflow built in the last 7 days that isn't in MEMORY.md, add it.
Specifically ensure all 12 Gmail n8n workflows are correctly documented.
Ensure @Manager_JForgeBot and @Ava_JForgeBot are in MEMORY.md with correct entries.

Do NOT Do¶

Don't rewrite CLAUDE.md or system-map/steering.md in place, produce drafts for Justin to review
Don't delete anything, archive or flag, never rm
Don't touch tasks/pending/, the dispatcher is live
Don't modify any systemd services or cron jobs without flagging first
Don't touch ~/.forge-secrets/ beyond reading what's needed
Don't modify n8n workflows (just flag TickTick ones as legacy in docs)
Don't kill sessions that might be doing active work, check their pane output first
Don't rewrite skills in place without flagging the change, some have subtle trigger logic

Deliverables¶

Pruned workspace, dead sessions killed, session files cleaned, old tasks/logs archived, old handoffs archived
docs/refactor/memory-audit-2026-04-28.md, line-by-line MEMORY.md audit with proposed edits
docs/refactor/steering-draft-2026-04-28.md, new system-map/steering.md draft
docs/refactor/skills-audit-2026-04-28.md, skills review with recommendations
docs/refactor/claude-md-notes-2026-04-28.md: CLAUDE.md gaps/notes
Updated MEMORY.md, small fixes applied, TickTick flagged, new tools registered
Notification to manager bot when complete, scripts/notify.sh info "Forge Refactor Complete" "Audit docs in docs/refactor/. Review before applying."