SMTM v4 — Project Workflow Design Spec

Status: Revised 2026-03-24 Date: 2026-03-24 Replaces: SMTM_System.md v3.4 (project workflow sections)

Goal

Upgrade the SMTM project workflow to handle multi-phase development projects reliably — with a high-level TOC artifact, clean document responsibilities, and a phase lifecycle that prevents context accumulation and orientation loss across AI sessions.

Core Problem Being Solved

Context corruption after compaction occurs when NEXT-STEPS.md accumulates across phases (because project-task-complete was never called at phase boundaries). AI sessions lose orientation in a 1,000+ line file. The fix: enforce phase boundaries, add a lean orientation anchor to STATUS.md, and introduce ROADMAP.md as the always-current project TOC.

Document Responsibilities (Single-Responsibility Principle)

Document	Single responsibility	SSoT for
`ROADMAP.md`	Structure — phases + tasks (living TOC)	“What are we building and how is it structured?”
`STATUS.md`	State — what’s done/not done	”Where are we right now?”
`NEXT-STEPS.md`	Communication — Claude/Talbot dialogue	”What are we doing next?”
`LESSONS.md`	Learning — decisions, patterns, significant pivots	”What have we learned and decided?”
`DASHBOARD.md`	View — Obsidian presentation layer (optional)	(no data — renders STATUS + task frontmatter)

Hard rules:

STATUS.md contains only state. No decisions, no feedback, no instructions.
NEXT-STEPS.md is the only communication channel. Talbot feedback goes here as a Talbot Response — not in STATUS.md.
Key decisions belong in LESSONS.md, not STATUS.md. DESIGN.md (dev) captures technical decisions; LESSONS.md captures process decisions and what to do differently.
ROADMAP.md and STATUS.md are always updated atomically — change one, change both in the same session.
_active.md in Tasks/ is retained unchanged — it tracks open task files across all projects and is read by AI at session start.

Project Tiers

Simple Project

Fewer than ~10 tasks, single phase, parallel agent delegation still possible.

Projects/[name]/
├── ROADMAP.md              ← task list + goals (living TOC)
├── Task-1-[descrip].md     ← task brief
├── Task-2-[descrip].md
├── ...
├── STATUS.md               ← current task + overall state
├── NEXT-STEPS.md           ← Claude/Talbot dialogue
├── LESSONS.md
├── logs/
└── archive/

Cancelled phases: Move the phase folder directly to archive/ with a note in LESSONS.md explaining why it was cancelled.

Complex Project

Multiple phases, each with multiple tasks. Some tasks may be delegated to external AI agents (Cursor, Claude Code, etc.).

Projects/[name]/
├── ROADMAP.md              ← multi-phase TOC (living, always current)
├── DASHBOARD.md            ← Obsidian view layer (optional)
├── phases/
│   ├── Phase-1-[name]/     ← moved to archive/ when phase complete
│   │   ├── Task-1-[descrip].md
│   │   ├── Task-2-[descrip].md
│   │   └── ...
│   └── Phase-2-[name]/     ← active phase
│       ├── Task-1-[descrip].md
│       └── ...
├── ARCHITECTURE.md         ← dev projects only
├── DESIGN.md               ← dev projects only (replaces DESIGN-Decisions.md)
├── STATUS.md               ← state only: phase checkboxes + orientation block
├── NEXT-STEPS.md           ← phase-scoped; resets at each phase boundary
├── LESSONS.md              ← key decisions, patterns, significant pivots
├── logs/
└── archive/

ROADMAP.md Format

Pure TOC — structure only, no status, no dates. Always reflects the current plan (updated freely when plans change; significant pivots noted in LESSONS.md).

# [Project Name] — Roadmap

**Goal:** One sentence — what this project delivers when done.
**Type:** Simple | Complex
**Description:** Optional 2-3 sentence context.

---

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

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

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

## Future / Backlog
- [Ideas not yet committed to a phase]

Simple projects: Replace phases with a flat task list under a single ## Tasks heading.

STATUS.md Format (state only)

# [Project Name] — Status

**Last Updated:** YYYY-MM-DD

## Current Phase
**Phase:** 2 — [Phase Name]
**Active tasks:** Task-2-[descrip], Task-3-[descrip]  *(list all tasks in flight)*
**Last action:** [Brief description] (YYYY-MM-DD)
**Next:** [Brief description of next task or decision]

---

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

## Phase 2 — [Name] 🟡 (Active)
- [x] Task-1: [description]
- [ ] Task-2: [description]
- [ ] Task-3: [description]

## Phase 3 — [Name] ⬜
- [ ] Task-1: [description]

Nothing else. No Key Decisions (→ LESSONS.md), no Feedback (→ NEXT-STEPS.md Talbot Response), no instructions.

What Talbot/Claude may change in STATUS.md: Only checkboxes (state). Phase and Task names/descriptions are read-only in STATUS.md — they come from ROADMAP.md and are updated only by the sync hook.

Synchronization rule: ROADMAP.md is the authoritative source for Phase/Task names. STATUS.md mirrors those names exactly. Sync is enforced by a Claude Code hook — not by skill instructions or human memory:

Hook (primary): A Claude Code PostToolUse hook fires on every Write/Edit to ROADMAP.md. It automatically updates Phase/Task descriptions in STATUS.md to match. The hook does NOT touch checkboxes (state is never overwritten).
Skills do NOT enforce sync — the hook handles it every time, unconditionally.
Session-start check: /project-continue still verifies STATUS.md phase names match ROADMAP.md as a sanity check; flags any mismatch (indicates the hook was bypassed or not yet configured).

NEXT-STEPS.md Format (phase-start template)

After project-task-complete resets NEXT-STEPS.md, the new file looks like:

# [Project Name] — Next Steps

> Entry point for both parties. Use /project-continue to pick up any session.
> **Current phase:** Phase [N] — [Phase Name] | Active tasks: `phases/Phase-N-[name]/`

---

## Claude Response — YYYY-MM-DD

### Phase [N] started
- [x] [Previous phase archived to logs/]
- [x] STATUS.md updated — Phase [N] now active

### Next Steps for Talbot
- [ ] [First task or decision for this phase]

## Talbot Response

---

The phase pointer in the header gives any AI session immediate context without reading STATUS.md first.

Task Brief Format

For any assignee — human, Claude, or external agent (Cursor, etc.). The Agent used field enables learning about which models/tools work best for which task types.

Filename: Task-Brief-N-[descrip].md — mirrors the associated task file name with “Brief” inserted (e.g., Task-Brief-3-reconciliation-engine.md pairs with Task-3-reconciliation-engine.md).

Context rule: The brief’s Context section opens with a direct link to Task-N-[descrip].md as the SSoT. It does not duplicate the full task description — the task file is the authoritative source. The brief adds only what the executing agent needs to know for delegation: hard rules, deliverables, completion signal.

Note: The Agent Response section is appended by the executing agent on completion — it is not a session log. Separate dated session logs are written to logs/ by Claude at phase completion via project-task-complete.

# Task Brief: [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
**Full task spec:** [Task-N-[descrip].md](Task-N-[descrip].md) — read this first.

[Brief summary of what this delegation needs to accomplish and what it enables downstream.
No need to repeat what is already in the task file.]

## Reference Files
- `path/to/file` — why this file matters for this task

## Hard Rules
- [Rule 1]
- [Rule 2]

## Deliverables
[Exact outputs: files created/modified, tests that must pass, etc.]

## Completion Signal
[How we know it's done — test output, build success, file exists, etc.]

---

## Agent Response
[Agent appends summary here on completion — model used, what was done, issues found.
This is an in-task summary only. Session logs are written separately to logs/ at phase completion.]

Phase Lifecycle (Critical Discipline)

Phase boundary = required `project-task-complete` call

When a phase completes:

Call /project-task-complete
Archives NEXT-STEPS.md conversation cycles → logs/YYYY-MM-DD_Phase-N-[name].md
Resets NEXT-STEPS.md to the phase-start template (see above)
Ticks the completed phase in STATUS.md, sets next phase as active
Updates “Current Phase” block in STATUS.md
Moves phases/Phase-N-[name]/ → archive/Phase-N-[name]/
Review LESSONS.md — identify entries to promote to global or project CLAUDE.md/AGENTS.md; mark with [→ global CLAUDE.md] or [→ project CLAUDE.md]

Hard rule: NEXT-STEPS.md is always phase-scoped. It never accumulates across phases. A NEXT-STEPS.md older than one phase is a signal that project-task-complete was skipped.

Simple project closure

When a simple project completes:

Call /project-task-complete
Archives NEXT-STEPS.md → logs/YYYY-MM-DD_[project]-complete.md
Mark STATUS.md as ✅ Complete
Review LESSONS.md — identify any entries that should be promoted to global CLAUDE.md or project AGENTS.md; mark candidates with [→ global CLAUDE.md] or [→ project CLAUDE.md]
Remove from Tasks/_active.md
Offer git commit
Optional: move project folder to 09_Logs/Projects/[name]/ at full closure

Dev Project Extras

For software/app development projects only:

File	Purpose
`ARCHITECTURE.md`	System design, tech stack, component boundaries — stable reference
`DESIGN.md`	Evolving technical/architectural design decisions (replaces `DESIGN-Decisions.md`)

Responsibility split: DESIGN.md captures technical decisions about the product (what to build and how). LESSONS.md captures process decisions and what to do differently (how we work). They do not overlap.

Relationship to CLAUDE.md: ARCHITECTURE.md and DESIGN.md are the human-readable planning layer. At implementation start, their confirmed decisions and hard rules are distilled into the repo’s CLAUDE.md (at the appropriate folder level). CLAUDE.md is updated from them — never independently.

DASHBOARD.md (Optional — Obsidian only)

Not a data source. A view layer over STATUS.md and task file frontmatter using Obsidian Dataview or Bases. Stores nothing. Markdown-only users ignore it.

Task brief frontmatter (Status, Assignee, Phase, Independent) is Obsidian-queryable:

TABLE status, assignee, phase FROM "Projects/SD-App/phases"
WHERE contains(file.name, "Task-")
SORT phase, file.name

Skills Changes Required

Skill	Change
`/project-start`	Creates ROADMAP.md + STATUS.md + NEXT-STEPS.md + LESSONS.md; prompts Simple or Complex; creates `phases/` if Complex
`/project-continue`	Reads STATUS.md “Current Phase” block first; verifies phase names match ROADMAP.md (flags mismatch as hook misconfiguration); then reads NEXT-STEPS.md tail
`/project-task-complete`	Required at every phase boundary; archives NEXT-STEPS.md to logs/; resets to phase-start template; moves phase folder to archive/; updates STATUS.md; reviews LESSONS.md for CLAUDE.md/AGENTS.md promotion candidates; for simple project closure: marks ✅, removes from _active.md
`/write-task-brief`	New skill — guides creation of a task brief for external AI agent delegation; prompts for context link, reference files, hard rules, deliverables, completion signal; outputs a `Task-Brief-N-[descrip].md` file in the correct phase folder; executing agent appends `Agent Response` section on completion
`ROADMAP.md sync hook`	New Claude Code hook — `PostToolUse` on Write/Edit to ROADMAP.md; syncs Phase/Task descriptions to STATUS.md without touching checkboxes
`SMTM_System.md`	Update to v4 (see migration notes)

SMTM_System.md Migration Notes

Changes required when updating SMTM_System.md to v4:

Project structure diagrams → add ROADMAP.md, phases/ folder (complex), task brief files
STATUS.md template → remove Key Decisions and Feedback sections; add Current Phase block
Project lifecycle diagram → add phase boundary rule, NEXT-STEPS.md reset
Skills table → updated descriptions for project-start, project-continue, project-task-complete
Add: ROADMAP.md template
Add: NEXT-STEPS.md phase-start template
Add: Task Brief template
Add: Simple project closure steps
Add: _active.md retained (clarify it is unchanged from v3.4)
Update MEMORY.md (~/.claude/projects/) references to STATUS.md Feedback section → NEXT-STEPS.md
Update CLAUDE.md files that reference STATUS.md Feedback section → NEXT-STEPS.md Talbot Response

Spec written 2026-03-24. Awaiting second review.