SMTM v4.0 Upgrade

Date: 2026-03-24 Task: SMTM-Upgrade.md Status: ✅ Complete

What This Was

A full-session upgrade of the SMTM project workflow from v3.4 to v4.0. The trigger was a specific failure: the five-phase SD App had no high-level plan document — the original plan was buried in an archive note. When context compacted mid-session, Claude lost direction and reported things it hadn’t done. The root cause was structural: no orientation anchor, no phase boundaries, and NEXT-STEPS.md had accumulated across two phases without a reset.

The upgrade addressed both the structural gap (missing ROADMAP.md) and the process gap (skills that relied on in-context memory instead of reading files fresh).

Key Design Decisions

Two Project Tiers

Tier	When	Structure
Simple	<~10 tasks, single phase	Flat — task files directly in project root
Complex	Multiple phases, external agent delegation	`phases/Phase-N-[name]/` folders + full scaffold

A simple project promotes to complex when it grows beyond one phase. Task files carry over; add phases/ folder.

Single-Responsibility Artifacts

Artifact	Owns	Does NOT own
ROADMAP.md	Project structure, phase/task TOC	State, decisions, history
STATUS.md	Current state (with Current Phase block)	Plans, dialogue, history
NEXT-STEPS.md	Active Claude/Talbot dialogue (resets per phase)	State, structure
LESSONS.md	Per-project learning candidates	Workflow processing
UPGRADES.md	Ideas not committed to phases	Priority ranking, workflow
DASHBOARD.md	Optional Obsidian Dataview view	Any workflow processing

ROADMAP.md as TOC Only

ROADMAP.md is a pure Table of Contents: phases, tasks, goal. It does not contain state, decisions, or feedback. This separation means the roadmap never gets stale from session churn — only structure changes update it.

Format settled on:

# [Project Name] — Roadmap

**Summary:** [one sentence — what this project delivers]
**Description:** [2-3 sentences context + scope]
**Type:** Complex | Simple

---

## Phase 1 — [Name]
- Task-1: [description]
- Task-2: [description]

## Future Upgrades
> See [[UPGRADES]] for possible upgrade ideas not yet committed to a phase.

STATUS.md Current Phase Block

The fix for context corruption is a 4-line block at the top of STATUS.md:

## Current Phase
**Phase:** 2 — SvelteKit Renderer
**Active tasks:** Task-3-renderers, Task-4-normalization
**Last action:** Term loan renderer complete (2026-03-22)
**Next:** Output simplification + live API form

Any AI session reads STATUS.md first, gets instant orientation in 4 lines. No need to read NEXT-STEPS.md history.

ROADMAP ↔ STATUS Sync Hook

PostToolUse hook on Edit/Write runs smtm-roadmap-sync.py when ROADMAP.md is edited. It updates task/phase descriptions in STATUS.md without touching checkboxes. This keeps the two files consistent without manual effort.

Task Brief Format

Tasks that get delegated to external AI agents need a self-contained brief. New format (Task-Brief-N-[descrip].md):

# Task: [N]-[description]

**Project:** [name]
**Phase:** [N] — [phase name]
**Status:** pending | active | complete
**Assignee:** talbot | claude | cursor | tbd
**Agent used:** [filled in on completion: e.g., claude-sonnet-4-6 via Cursor]
**Independent:** yes | no
**Prerequisites:** Task-1, Task-2 (or "none")

---

## Context
[Self-contained. No external docs required.]

## Reference Files
- `path/to/file` — why it matters

## Hard Rules
- [Rule 1]

## Deliverables
[Exact outputs: files, tests, etc.]

## Completion Signal
[How we know it's done]

---

## Agent Response
[Agent appends summary here on completion — model, what was done, issues]

The Agent used field creates a data point per task for learning which models work best.

ARCHITECTURE.md + DESIGN.md (Dev Projects Only)

File	Purpose
`ARCHITECTURE.md`	System design, tech stack, component boundaries — stable
`DESIGN.md`	Evolving design decisions (renamed from DESIGN-Decisions.md)

Relationship to CLAUDE.md: During brainstorming, confirmed decisions go into ARCHITECTURE/DESIGN. At implementation start, Claude distills hard rules from those docs into the repo’s CLAUDE.md. CLAUDE.md is updated from ARCHITECTURE/DESIGN — never independently.

UPGRADES.md — Ideas Parking Lot Only

UPGRADES.md is a simple reference doc, not a workflow artifact. It holds ideas in priority order. No promotion workflow — that’s a human decision, not a skill step. Linked from the bottom of ROADMAP.md as ## Future Upgrades → See [[UPGRADES]].

Context Compaction Fix (Skills)

Root cause: /task-continue and /project-continue relied on in-context memory to determine the last Talbot Response. After compaction, that memory was wrong.

Fix: Both skills now mandate a shell command unconditionally:

tail -n +$(grep -n "## Talbot Response" "/path/to/file.md" | tail -1 | cut -d: -f1) "/path/to/file.md"

This finds the line number of the LAST ## Talbot Response heading and prints everything from there to EOF. Correct regardless of file size or prior cycles. “Even if you just wrote to this file moments ago, the file may have been modified since.”

What Was Built

Rewrote /project-start skill — full ROADMAP, STATUS, NEXT-STEPS, LESSONS, UPGRADES creation steps
Updated /project-continue skill — mandatory shell read of last Talbot Response
Updated /task-continue skill — same mandatory shell read fix
Rewrote SMTM_System.md to v4.0 — all artifacts, templates, lifecycle, Document Responsibilities table
Folded SMTM-v4-design.md into SMTM_System.md — design doc archived
Created SMTM/UPGRADES.md — SMTM project’s own ideas backlog
Created SD-App ROADMAP.md — five-phase structure
Updated SD-App UPGRADES.md — seeded from Phase 5+ ROADMAP content
Updated SD-App STATUS.md — state-only with Current Phase block
Updated monorepo/CLAUDE.md + apps/sd-app/CLAUDE.md — session start reads NEXT-STEPS.md, not STATUS.md Feedback
Updated MEMORY.md — v4.0 project structure
Saved feedback memory: feedback_file_state_memory.md — never use in-context memory for file state
Deleted stale files: STATUS_Template.md, TASKS_md_Template.md
Archived: SMTM-v4-design.md, SMTM-v4-plan.md → archive/

Files Changed

File	Action
`~/.claude/commands/project-start.md`	Rewritten — full v4 scaffold creation
`~/.claude/commands/project-continue.md`	Updated — mandatory shell read of last Talbot Response
`~/.claude/commands/task-continue.md`	Updated — same mandatory shell read fix
`~/.claude/settings.json`	Added PostToolUse hook for ROADMAP↔STATUS sync
`/mnt/d/FSS/Scripts/smtm-roadmap-sync.py`	Created — syncs ROADMAP.md → STATUS.md descriptions
`SMTM_System.md`	Rewritten to v4.0 — design spec folded in
`SMTM/UPGRADES.md`	Created
`SMTM/archive/SMTM-v4-design.md`	Archived (was active spec)
`SMTM/archive/SMTM-v4-plan.md`	Archived
`SMTM/STATUS_Template.md`	Deleted (stale)
`SMTM/TASKS_md_Template.md`	Deleted (stale)
`Projects/SD-App/ROADMAP.md`	Created — five-phase structure
`Projects/SD-App/UPGRADES.md`	Created — seeded from Phase 5+ content
`Projects/SD-App/STATUS.md`	Updated — state-only + Current Phase block
`monorepo/CLAUDE.md`	Updated session start instructions
`apps/sd-app/CLAUDE.md`	Updated session start instructions
`~/.claude/projects/.../MEMORY.md`	Updated to v4.0
`~/.claude/projects/.../feedback_file_state_memory.md`	Created — file state memory rule

Commits

fe07bc2 — docs(smtm): rewrite SMTM_System.md to v4.0
4f3554e — docs(sd-app): migrate SD-App project to SMTM v4 (ROADMAP.md + STATUS.md)
f87993a — docs(monorepo): update CLAUDE.md session start for SMTM v4

Gotchas

/task-continue relied on in-context memory — the real failure wasn’t compaction per se; it was that skills assumed they knew the file state without reading it. Fix: mandatory tail -n +$(grep -n...) command, not tail -20, not memory.
ROADMAP format had Goal: but needed Summary: + Description: — Talbot applied this correction directly during review. Simple tier also needs Description (originally omitted).
UPGRADES.md must be a reference doc only — first draft included a “promotion workflow” section. Talbot corrected: it’s just an ideas list in priority order, no workflow processing.
SMTM_System.md is the SSoT — the design doc (SMTM-v4-design.md) was the spec being folded in. Do not delete the system doc; archive the spec.
[[UPGRADES]] not [[UPGRADES.md]] — Obsidian idiomatic wikilink style, consistent everywhere.

Pending (Talbot testing)

Run /project-start test-smtm-v4 — validate full skill chain end-to-end
Review SD-App ROADMAP.md — confirm phase/task breakdown looks right
Investigate CLAUDE/AGENTS.md SSoT architecture (flag for planning session)
Explore Agent Teams (CC experimental, released 2026-03-22)