Simple Markdown Task Management (SMTM)

Version: 5.0 — Updated 2026-04-12 Status: Active system

Summary

Talbot’s authoritative guide for task, project, and log management across the KB and all AI sessions.

Description

A lightweight, file-based system for managing tasks, projects, and logs in Obsidian. Designed for AI-assisted workflows — each project has a ROADMAP.md (structure), STATUS.md (state), and NEXT-STEPS.md (active conversation), giving any AI session immediate orientation without prior context. When onboarding a new AI tool, point it here.

Future Upgrades

See UPGRADES for possible upgrade ideas

The Lifecycle

Two separate lifecycles — Tasks and Projects — share the same principles but different structures.

Task Lifecycle

┌─────────────────────────────────────────────────────────┐
│  HUMAN INITIATES: /task-start [filename]                │
│                                                         │
│  Quick task → add to Tasks/_tmp.md (personal scratch)   │
│  Substantive task → create Tasks/YYYY-MM-DD_Name.md     │
│  + add pointer in Tasks/_active.md                      │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  AI SESSION                                             │
│                                                         │
│  1. Read Tasks/_active.md  (active task tracker)        │
│  2. Read task file if named (current state)             │
│  3. Execute work                                        │
│  4. Append ## Claude Response to END of task file       │
│     • Summary (checkboxes for completed items)          │
│     • Next Steps for Talbot                             │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  TALBOT RESPONDS                                        │
│                                                         │
│  Primary: numbered list items indented under each       │
│  Next Steps checkbox (Alt+0 toggles paragraph to list)  │
│    - [ ] Item A                                         │
│      1. Talbot's response to A                          │
│  Catch-all: free-form text in ## Talbot Response        │
│                                                         │
│  Next session: /task-continue [filename]                │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
                 [repeat until done]
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  COMPLETION: /task-complete [filename]                  │
│                                                         │
│  • AI suggests LESSONS.md candidates                    │
│  • Purge to keep only what has reference value          │
│  • Option: log to 09_Logs, delete, or keep as reference │
│  • Offer to commit                                      │
│  • Update Tasks/_active.md                              │
└─────────────────────────────────────────────────────────┘

Project Lifecycle

┌─────────────────────────────────────────────────────────┐
│  HUMAN INITIATES                                        │
│                                                         │
│  /project-start [name]                                  │
│  → creates Projects/[name]/ROADMAP.md                   │
│  → creates Projects/[name]/STATUS.md                    │
│  → creates Projects/[name]/NEXT-STEPS.md                │
│  → creates Projects/[name]/LESSONS.md                   │
│  → prompts: Simple or Complex?                          │
│    Complex → creates phases/ subfolder                  │
│  + optional SPEC.md, PLAN.md, DESIGN.md                 │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  TALBOT RESPONDS                                        │
│                                                         │
│  Write direction in NEXT-STEPS.md                       │
│  below the ## Talbot Response heading                   │
│                                                         │
│  /project-continue [name]                               │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  AI SESSION                                             │
│                                                         │
│  1. Read STATUS.md  (Current Phase block + blockers)    │
│  2. Verify phase names match ROADMAP.md                 │
│  3. Read NEXT-STEPS.md  (latest Talbot Response)        │
│  4. Execute work                                        │
│  5. On finish:                                          │
│     • Tick checkboxes in STATUS.md                      │
│     • Append Claude Response to NEXT-STEPS.md           │
│     • Write YYYY-MM-DD_Description.md → logs/           │
│     • Final message: WSL + Windows paths                │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
                 [repeat until done]
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  PHASE BOUNDARY: /project-task-complete (REQUIRED)      │
│                                                         │
│  • Archives NEXT-STEPS.md → logs/                       │
│  • Resets NEXT-STEPS.md to phase-start template         │
│  • Moves phase folder → archive/ (Complex projects)     │
│  • Updates STATUS.md Current Phase block                │
│  • Reviews LESSONS.md for promotion candidates          │
│                                                         │
│  Simple project closure:                                │
│  • Marks STATUS.md ✅ Complete                          │
│  • Removes from Tasks/_active.md                        │
│  • Archives to 09_Logs/Projects/[name]/                 │
└─────────────────────────────────────────────────────────┘

Phase boundary rule: /project-task-complete is required at every phase end — not just end-of-session. Each phase completion archives NEXT-STEPS.md and resets it to the phase-start template so the next phase starts clean.

Layer 1: Tasks

Where: Tasks/_tmp.md (personal scratch — AI never reads or writes) + Tasks/_active.md (AI-managed active tracker) + _WorkingOn/Tasks/ (named task files for anything needing a spec or feedback loop).

Tasks/_tmp.md — Personal Scratch + Quick AI Tasks

Tasks/_tmp.md serves two purposes:

Personal scratch pad — drafts, notes, quick ideas, anything Talbot wants to jot down
Quick AI tasks — for lightweight tasks that don’t need a named file or log

AI access via /task-start _tmp.md: When _tmp.md is passed explicitly, /task-start runs in _tmp.md mode — finds unchecked tasks or instructions, executes them, appends results and a ## Claude Response section. No _active.md tracking, no /task-complete workflow needed.

Not suitable for: anything complex, high-risk, or requiring a feedback loop. Use a named task file for those.

Tasks/_active.md — Active Task Tracker (AI-Managed)

Tasks/_active.md is a simple list of active named task files, maintained by the AI. Contains an ## Active section with wiki links to open task files. AI reads this at session start to orient itself, and updates it when tasks are started or completed.

## Active
- [[2026-03-16_web_deploy_CLI]]
- [[2026-03-14_KB-Folder-Notes]]

Tasks/ — Individual Task Files

For anything needing a spec, feedback loop, or more than 30 minutes, create a named task file:

_WorkingOn/Tasks/
├── _tmp.md                    ← personal scratch + quick AI tasks (/task-start _tmp.md)
├── _active.md                 ← active task tracker (AI-managed)
├── Tasks-Template.md          ← SSoT template (copy to create new tasks)
├── DASHBOARD.md               ← Obsidian Bases view over task frontmatter (optional)
├── SMTM-Upgrade.md            ← active task (PascalCase, no date prefix)
└── KB-Folder-Notes.md         ← active task

When to create a task file: task > 30 min, needs a spec, or involves human↔AI back-and-forth. When to use _tmp.md: quick personal notes, or lightweight AI tasks via /task-start _tmp.md. File naming: PascalCase.md — no date prefix. Dates belong in the frontmatter date field and in log filenames, not task filenames. Log: For completed tasks — optional. Keep only if it has future reference value. Promote to Project when: task expands beyond one session, needs phases, or requires a persistent STATUS.md.

Tasks-Template

→ SSoT: _WorkingOn/Tasks/Tasks-Template.md

The task file is a single file for the entire lifecycle. Nothing is deleted — the full Claude↔Talbot conversation history stays in the file. New sections are always appended to the END. After each Claude Response, Claude appends ## Talbot Response + --- so Talbot can write their reply directly.

Cycle: Claude appends → Talbot appends → Claude appends → … → /task-complete

Skills:

/task-prep [filename] — prepares a task with full context; sets status: ready; use before /task-start for complex or delegated tasks
/task-start [filename] — Claude reads task file, executes it, appends first Claude Response (first session only)
/task-continue [filename] — Claude reads latest Talbot Response and appends new Claude Response
/task-complete [filename] — closes the task: LESSONS.md candidates, purge, log/delete option, commit offer

Task Frontmatter Parameters

Every task file can include an optional YAML frontmatter block. Defaults apply when fields are omitted — add only what’s useful for the task.

---
title: Task Name
date: YYYY-MM-DD        # creation date (modified date from git/filesystem)
model: default          # light | default | high | highest
model-type: auto        # auto | free | local
task-type: planning     # code | research | brainstorm | planning | writing | review | ops
risk: low               # low | medium | high | critical
status:                 # (blank) | ready | active | blocked | complete
prerequisites: none     # none | TaskName | Phase2/TaskName
assignee: claude        # claude | cursor | talbot | tbd
---

Parameter Definitions

Param	Values	Default	Meaning
`date`	YYYY-MM-DD	creation date	Task creation date. Modified date is derivable from git — no separate field needed.
`model`	light / default / high / highest	default	Maps to Haiku / Sonnet / Opus / Opus+thinking
`model-type`	auto / free / local	auto	`free` = Gemini free tier; `local` = Ollama; `auto` = best available
`task-type`	code / research / brainstorm / planning / writing / review / ops	—	Informs skill behavior (debug mode, research tools, risk gates)
`risk`	low / medium / high / critical	low	Governs validation rigor and approval requirements
`status`	(blank) / ready / active / blocked / complete	—	Task lifecycle state; powers Dashboard queries
`prerequisites`	none / TaskName / Phase2/TaskName	none	Tasks that must complete first. `none` implies independence.
`assignee`	claude / cursor / talbot / tbd	claude	Who executes

Status Lifecycle

(no status) — created, not yet prepped
  ready     — /task-prep ran; context complete; waiting for /task-start or agent dispatch
  active    — currently being executed (/task-start sets this)
  blocked   — waiting on prerequisite or external dependency
  complete  — done (/task-complete sets this)

Risk Level Behavior

Risk	Behavior
`low`	Execute autonomously
`medium`	Extra validation; flag edge cases in Claude Response
`high`	Talbot sign-off required before closing; `/task-QA` check (Phase 4)
`critical`	Mandatory plan-first gate — no auto-execution. Applies to: code security, data privacy, financial, AI risk to core services

Dashboard

Tasks/DASHBOARD.md contains Obsidian Bases queries that use these frontmatter params to display active tasks, the ready queue, tasks by risk level, and blocked tasks. See the file for query templates.

Layer 2: Projects

Document Responsibilities

Each document has one clear job. Never store content in the wrong place.

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?”
`UPGRADES.md`	Ideas — discovered during dev, not yet committed	”What could we improve or add later?”
`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 (process) or DESIGN.md (technical, dev projects) — not STATUS.md.
UPGRADES.md is a parking lot for ideas discovered during development. Ideas are not committed to phases until promoted to ROADMAP.md ## Future / Backlog.
ROADMAP.md and STATUS.md are always updated atomically — change one, the hook syncs the other.

Simple Project Structure

For most projects — fewer than ~10 tasks, single-phase or loosely phased:

_WorkingOn/Projects/[name]/
├── ROADMAP.md      ← project TOC: flat task list (Simple) or phase hierarchy (Complex)
├── STATUS.md       ← state-only: Current Phase block + phase checkboxes (AI reads first)
├── NEXT-STEPS.md   ← active Claude/Talbot conversation; phase-scoped, resets at phase boundary
├── LESSONS.md      ← process decisions, patterns, significant pivots
├── UPGRADES.md     ← ideas discovered during dev (not committed to phases)
├── SPEC.md         ← optional: what we're building (requirements, stays current)
├── PLAN.md         ← optional: how we'll build it (approach + phases, stays current)
├── logs/           ← dated session logs (YYYY-MM-DD_Description.md)
└── archive/        ← completed reference documents (moved here when no longer active)

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

Complex Project Structure

For multi-phase projects with substantial work per phase:

_WorkingOn/Projects/[name]/
├── ROADMAP.md      ← phase hierarchy with tasks per phase
├── DASHBOARD.md    ← optional: Obsidian view layer (no data — renders STATUS + task frontmatter)
├── STATUS.md       ← state-only: Current Phase block + phase checkboxes
├── NEXT-STEPS.md   ← phase-scoped conversation; resets at each phase boundary
├── LESSONS.md      ← process decisions, patterns, significant pivots
├── UPGRADES.md     ← ideas discovered during dev (not committed to phases)
├── ARCHITECTURE.md ← dev projects only: system design + tech stack (stable reference)
├── DESIGN.md       ← dev projects only: evolving technical/architectural decisions
├── SPEC.md         ← optional
├── PLAN.md         ← optional
├── phases/
│   ├── Phase-1-[name]/
│   │   ├── Task-1-[descrip].md    ← task spec + delegation brief (run /task-prep to embed context)
│   │   ├── Task-2-[descrip].md
│   │   └── ...
│   └── Phase-2-[name]/
│       └── ...
├── logs/           ← dated session logs
└── archive/        ← completed phases + reference documents

Key principle: NEXT-STEPS.md and STATUS.md are always live. ROADMAP.md is the authoritative source for phase and task names — STATUS.md mirrors those names exactly. SPEC and PLAN are the current version — no date prefix. Logs are historical records — always dated.

NEXT-STEPS.md — The Conversation Container

The central document for all project-level Claude/Talbot dialogue. It is phase-scoped — at each phase boundary, /project-task-complete archives the current NEXT-STEPS.md to logs/ and resets it to the phase-start template. This keeps the conversation focused on the current phase.

AI reads: latest Talbot Response → executes work → appends new Claude Response
Talbot reads: latest Claude Response → Next Steps → writes Talbot Response
Completed cycles are archived to logs/; each phase starts fresh

# [Project Name] — Next Steps

> Entry point for both parties. Use /project-continue to pick up any session.

---

## Claude Response — YYYY-MM-DD
### Summary
- [x] What was done

### Next Steps for Talbot
- [ ] Item 1
  1. Talbot's inline response  ← numbered list under the checkbox (primary method)
- [ ] Item 2

## Talbot Response
See inline responses above.   ← catch-all; leave blank or use for anything not fitting inline

---

Larger projects: Use the Complex structure above. Add design documents (e.g., DESIGN.md, api-design.md) for topics that need dedicated iteration cycles — they follow the same Claude/Talbot response pattern.

Dev projects: Use Superpowers for brainstorm→plan→execute. Implementation plans live in PLAN.md. Technical decisions go in DESIGN.md (not LESSONS.md).

STATUS.md — State-Only Handoff File

Every project has a STATUS.md. AI reads it at session start; updates checkboxes and the Current Phase block at session end. STATUS.md is state-only — it does not hold feedback, key decisions, or notes.

Feedback → goes in NEXT-STEPS.md as a Talbot Response
Key decisions → go in LESSONS.md (process) or DESIGN.md (technical, dev projects)

# [Project Name] — Status

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

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

---

## Phase 1: Foundation ✅
- [x] Set up project structure
- [x] Define data models

## Phase 2: Core Features 🟡 (Current)
- [x] Authentication flow
- [ ] Calculator logic
- [ ] i18n integration

## Phase 3: Polish ⬜
- [ ] Responsive design
- [ ] Accessibility audit

## Phase 4: Deploy ⬜
- [ ] Staging + production deploy
- [ ] Final log + close

---

## Key Files
[Most important files for this project]

AI session workflow:

Start: read Tasks/_active.md → read STATUS.md (Current Phase block) → verify phase names match ROADMAP.md → read NEXT-STEPS.md
Work through unchecked items in current phase
End: tick completed checkboxes, update Current Phase block, write log to logs/

ROADMAP.md

ROADMAP.md is the project Table of Contents (ToC) — the authoritative source for phase and task names. STATUS.md mirrors these names exactly; only checkboxes are edited by humans or AI. A PostToolUse hook fires on every Edit/Write to ROADMAP.md and syncs descriptions to STATUS.md automatically (see ROADMAP ↔ STATUS Synchronization below).

ROADMAP.md is a living document — update it freely when plans change. Significant pivots should also be noted in LESSONS.md.

Simple Format

# [Project Name] — Roadmap

**Summary:** One sentence — what this project delivers.
**Description:** 2-3 sentences of context, motivation, and scope.
**Type:** Simple

---

## Tasks
- Task-1: [description]
- Task-2: [description]
- Task-3: [description]

## Future Upgrades
- See [[UPGRADES]] for possible upgrade ideas

Complex Format

# [Project Name] — Roadmap

**Summary:** One sentence — what this project delivers when done.
**Description:** 2-3 sentences of context, motivation, and scope.
**Type:** Complex

---

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

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

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

## Future Upgrades
- See [[UPGRADES]] for possible upgrade ideas

NEXT-STEPS.md Phase-Start Template

When /project-task-complete closes a phase, it archives the current NEXT-STEPS.md to logs/ and resets it to this template:

# [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: [first task 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]
  1. Talbot responds here with a numbered list item  ← inline under the checkbox

## Talbot Response
See inline responses above.   ← or blank; catch-all only

---

Task File (Project Tasks)

A project task file (Task-N-[descrip].md) is the spec AND the delegation brief for any unit of work in a Complex project phase. It lives in the phase folder and serves as the single file for the task’s full lifecycle.

Filename: Task-N-[descrip].md — N matches the task number in ROADMAP.md
Frontmatter: includes assignee, prerequisites, risk, status, and other params (see Task Frontmatter Parameters above)
Context section: added by /task-prep — embeds resolved file paths, KB excerpts, constraints, and model recommendation
Agent used field: filled in on completion — tracks which model/tool executed the task
Agent Response section: summary appended by the executing agent on completion

Run /task-prep [Task-N-descrip.md] to prepare a project task for delegation. This sets status: ready and embeds all required context. No separate brief file needed.

Note: Task-Brief-N-[descrip].md (the old separate delegation file) is retired as of SMTM v5.0. Task-N-[descrip].md is the single file type — it becomes the brief once prepped.

---
title: Task N — [description]
date: YYYY-MM-DD
task-type: code
risk: low
status: ready
prerequisites: none
assignee: cursor
---

# Task [N]: [description]

**Project:** [name]
**Phase:** [N] — [phase name]
**Agent used:** [filled in on completion — e.g., claude-sonnet-4-6 via Cursor]

---

## Spec
[What needs to be built or done. Success criteria.]

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

## Hard Rules
- [Rule 1]

## 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.]

---

## Context (Auto-Prepared) — YYYY-MM-DD
[Added by /task-prep — resolved paths, KB context, constraints, model recommendation]

---

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

Layer 3: Logs

Logs are permanent — the record of what happened.

Naming

YYYY-MM-DD_Description.md

No TYPE prefix on completed logs. PLAN and ACTIVE files keep their prefix because they are process states. Completed logs are just date + description.

Examples:

2026-03-10_KB-Structure-Upgrade.md
2026-03-09_i18n-Paraglide-shadcn-Foundation.md

Log File Template

# [Short Title]

**Date:** YYYY-MM-DD
**Project/Task:** [name]
**Status:** ✅ Complete

---

## Summary
[2-3 sentences]

## Done
- Item 1
- Item 2

## Changes
- file1 — what changed
- file2 — what changed

## Results / Metrics
[test results, build output, etc.]

## Next Steps
- [ ] Suggested next step 1
- [ ] Suggested next step 2

## Feedback
<!-- Human fills in after review -->

Log Storage

Log type	Where it lives
Active project logs	`_WorkingOn/Projects/[name]/logs/`
Archived project logs	`09_Logs/Projects/[name]/` (at project closure)
System/config logs	`09_Logs/System/`
Architecture decisions	`09_Logs/Decisions/`
Business snapshots	`09_Logs/Snapshots/`

Communication Standard (Hard Rule for All AI Sessions)

When Claude Code creates any file (plan, log, STATUS.md, etc.), the closing message must include both paths:

📄 File written:
  WSL:     /mnt/d/FSS/KB/Business/_WorkingOn/Projects/monorepo/complete/2026-03-10_Description.md
  Windows: D:\FSS\KB\Business\_WorkingOn\Projects\monorepo\complete\2026-03-10_Description.md

Claude Code plans (generated in ~/.claude/plans/) should also be copied to the KB so they’re visible in Obsidian:

Copy to: D:\FSS\KB\Business\_WorkingOn\Plans\YYYY-MM-DD_PLAN_Description.md

File Naming Quick Reference

File	Prefix	Location
Completed log	(none)	`logs/` or `complete/`
Implementation plan	`PLAN_`	`plans/`
Work in progress	`ACTIVE_`	`active/`
Session handoff	`STATUS.md`	project root
Active task tracker	`_active.md`	`Tasks/`
Personal scratch	`_tmp.md`	`Tasks/`
Task Brief	`Task-Brief-N-[descrip].md`	phase folder or project root

Superpowers Decision Gate

Use Superpowers when ≥2 of these are true:

Architecture is unclear and needs structured refinement before coding
TDD enforcement matters (you tend to skip tests when moving fast)
Project will span multiple days
Multiple components interact in non-obvious ways

Otherwise: go direct with PLAN + STATUS.md.

Dev Projects Workflow

1. /superpowers:brainstorm    → clarify app spec, edge cases, API design
2. /superpowers:write-plan    → generates TASKS.md with TDD-style spec
3. Review TASKS.md            → adjust, approve
4. /superpowers:execute-plan  → builds with test-first approach
5. Session ends               → update STATUS.md, write log to logs/

The generated TASKS.md lives in Projects/[name]/plans/YYYY-MM-DD_PLAN_Superpowers-Spec.md

Non-Dev Projects (Writing, Research)

The same lifecycle applies. “Tasks” become chapter/section checkboxes in STATUS.md:

## Part 1: The Debt Myth ⬜
- [ ] Draft intro section
- [ ] Add case studies
- [ ] Edit + proofread

Useful Skills

Skill	What it does
`/task-prep [file]`	Prepares a task with full context; sets `status: ready`; use before `/task-start` for complex or delegated tasks
`/task-start [file]`	Executes a new task file, appends first Claude Response (first session only); reads frontmatter params
`/task-continue [file]`	Reads latest Talbot Response in task file, appends new Claude Response; warns if context is stale (>7 days)
`/task-complete [file]`	Closes a task: LESSONS.md candidates, purge, log/delete, commit offer; sets `status: complete`
`/project-start [name]`	Creates ROADMAP.md + STATUS.md + NEXT-STEPS.md + LESSONS.md; prompts Simple or Complex; creates `phases/` if Complex
`/project-continue [name]`	Reads Current Phase block first; verifies phase names match ROADMAP.md (flags mismatch); 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 promotion candidates; for simple project closure: marks ✅, removes from _active.md
`/write-task-brief`	Deprecated — use `/task-prep` instead
`/test-all`	Full test suite at session end

Tasks/_tmp.md vs Tasks/_active.md

Two files serve completely different purposes — never confuse them:

File	Owner	Purpose	AI access
`_tmp.md`	Human	Personal scratch + quick AI tasks	Reads/writes only via `/task-start _tmp.md`; never accessed otherwise
`_active.md`	AI	Active task tracker — list of open task files	Reads at session start; updates on task start/complete

Why the split? _active.md gives Claude a clean, predictable tracking file. _tmp.md is primarily human-owned space — Claude only touches it when explicitly invoked via /task-start _tmp.md.

LESSONS.md — Self-Improving System

Every project has a LESSONS.md. Captures insights that prevent wasted effort in future sessions. For dev projects, technical decisions go in DESIGN.md — LESSONS.md captures process decisions, workflow insights, and pivots.

# Lessons — [Project Name]

## Lessons
- **[Context]:** [What went wrong or surprisingly well] → [What to do differently]
- **[Context]:** [Pattern discovered] → [How to apply it]

## Escalation Candidates
<!-- Mark with [→ global CLAUDE.md] or [→ project CLAUDE.md] -->
- [ ] [Lesson] → [→ global CLAUDE.md]

When to update LESSONS.md:

When something takes significantly longer than expected — capture why
When a pattern emerges across multiple tasks — write it down
At the end of each session (before closing)
During project cleanup (before archiving) — review for CLAUDE.md/AGENTS.md promotion candidates

Escalation workflow:

AI marks a lesson with [→ global CLAUDE.md] or [→ project CLAUDE.md]
Human reviews and approves during next session
AI adds the approved lesson to the appropriate CLAUDE.md
Lesson is cleared from LESSONS.md

UPGRADES.md — Ideas Parking Lot

Every project has a UPGRADES.md. It captures ideas discovered during development or after the project is complete, that are interesting and might be implemented later.

# [Project Name] — Upgrades

> Ideas to consider for future upgrades
> Should maintain in order of most important first

---

## Ideas
- [idea discovered during work]
- [potential improvement spotted]

Linking in Core Project Doc

Add a ## Future Upgrades section at the bottom of ROADMAP.md. This is the standard location for all projects — Simple and Complex. For dev projects with a repo README.md, also add a brief link there.

## Future Upgrades
- See [[UPGRADES]] for possible upgrade ideas

DASHBOARD.md (Optional — Obsidian only)

Not a data source — a view layer over STATUS.md and task brief frontmatter. Only useful in Obsidian with Dataview or Bases. Markdown-only users ignore it.

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

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

Or with Obsidian Bases (newer, no plugin required):

filters:
  - property: status
    condition: is not
    value: complete
groupBy: phase
properties: [status, assignee, independent]

Dev Project Extras

For software/app development projects, two additional documents capture technical context:

File	Purpose
`ARCHITECTURE.md`	System design, tech stack, component boundaries — stable reference
`DESIGN.md`	Evolving technical/architectural 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. CLAUDE.md is updated from them — never independently.

ROADMAP ↔ STATUS Synchronization

ROADMAP.md is the authoritative source for phase and task names. STATUS.md mirrors those names exactly — only checkboxes are edited by humans or AI directly.

How sync works:

A Claude Code PostToolUse hook fires on every Edit/Write to ROADMAP.md
The hook reads the updated ROADMAP.md and syncs phase/task descriptions to STATUS.md automatically
Checkboxes in STATUS.md are never touched by the hook — only descriptions are updated
Skills do NOT enforce this sync — the hook handles it unconditionally
/project-continue verifies sync at session start as a sanity check; flags any mismatch for review

What this means in practice:

Edit ROADMAP.md freely — rename phases, reorder tasks, add/remove items
STATUS.md descriptions update automatically; human-managed checkboxes are preserved
If the hook hasn’t run (e.g., manual edits outside Claude Code), /project-continue will flag the drift

Ralph Loop (Overnight Autonomous Work)

Use when:

Well-defined TASKS.md exists with clear success criteria
Batch operations that don’t need interactive decisions
You want to wake up to completed work

claude -p "Read TASKS.md and complete all items" \
  --allowedTools "Edit,Read,Bash,Write,Glob,Grep" \
  --max-iterations 50

Project Archival

When a project is complete or in maintenance mode, move it out of _WorkingOn/Projects/ to its permanent KB home. Only active, in-progress projects stay in _WorkingOn/.

Permanent Homes by Project Type

Type	Permanent Location	Examples
Production apps (SD App, sites)	`06_Intellectual Property/Software/Apps/<name>/`	SD App, sdc.com
Reusable packages / libraries	`06_Intellectual Property/Software/Packages/<name>/`	asset-history, sd-math
Workflow automation scripts	`03_Processes/System Utils/<name>/`	backup scripts, deploy tools

When to Archive

Archive when the project:

Has no open tasks in STATUS.md
Enters “maintenance mode” (cron updates, dependency bumps, minor fixes only)
Has been signed off by Talbot

How to Archive

Confirm STATUS.md shows all phases ✅ complete
Move _WorkingOn/Projects/<name>/ → permanent home (see table above)

Add a ## Maintenance block at the top of STATUS.md:

## Maintenance Mode
**Archived:** YYYY-MM-DD
**Location:** D:\FSS\KB\Business\06_Intellectual Property\Software\...\<name>
**Next action:** [brief description of what would trigger reactivation]

Remove from Tasks/_active.md if listed there
Update any cross-references that pointed to the old _WorkingOn/ path

Reactivation

When a maintained project needs active work again:

Move back to _WorkingOn/Projects/<name>/
Remove the ## Maintenance block from STATUS.md
Add back to Tasks/_active.md
Start with /project-continue <name>

Version: 5.0 — Updated 2026-04-12 Replaces: SMTM_System.md v4.1 (2026-03-31)

Multi-KB Skill Synchronization

Claude skills (~/.claude/commands/) are global — they apply to all vaults automatically. Updating a skill in one session updates it for both Business KB and MBR KB. No sync script needed.

sync-vaults.sh (at _shared/sync-vaults.sh) handles Obsidian plugin config only
SMTM_System.md lives in the Business vault; MBR’s CLAUDE.md points here as the authoritative reference
When onboarding a new KB vault, add a .claude/CLAUDE.md that references this file

v5.0 Changes (2026-04-12)

Task frontmatter parameters — every task file can now carry self-describing metadata: date, model, model-type, task-type, risk, status, prerequisites, assignee
Status lifecycle — new ready status set by /task-prep; full flow: (blank) → ready → active → blocked → complete
New /task-prep skill — hydrates any task with full context before execution; stops and asks for clarification if objectives are ambiguous; both interactive and file-based clarification
Task-Brief-N-[descrip].md retired — replaced by Task-N-[descrip].md (a single file that becomes the brief once prepped by /task-prep)
/write-task-brief deprecated — use /task-prep instead
_tmp.md rule change — AI can read/write via /task-start _tmp.md; no longer fully AI-off-limits
File naming convention — task files use PascalCase.md (no date prefix); dates belong in frontmatter and log filenames
Tasks/DASHBOARD.md — new Obsidian Bases view over task frontmatter; shows active queue, ready tasks, risk groupings, blocked tasks
Skills updated — /task-start reads frontmatter params, checks risk gate, sets status: active; /task-continue warns on stale context; /task-complete sets status: complete
Tasks-Template.md updated — frontmatter schema included; Claude/Talbot response terminology (replaces AI/Human)
Future: /task-QA skill — automated QA gate before task close (Phase 4, pending dog-fooding)

v4.1 Changes (2026-03-31)

Talbot Response format: inline numbered list items under Next Steps checkboxes (primary); ## Talbot Response section is catch-all only
task-continue and project-continue now read from ## Claude Response (not ## Talbot Response) to capture inline responses
Multi-KB skill sync documented: global ~/.claude/commands/ applies to all vaults automatically

v4.0 Changes (2026-03-24)

Added ROADMAP.md as project TOC (living document, two formats: Simple/Complex)
Two-tier project structure: Simple (<~10 tasks) and Complex (multi-phase with phases/ folder)
STATUS.md is now state-only: added “Current Phase” block; removed Key Decisions, Feedback, Notes/Blockers
NEXT-STEPS.md is phase-scoped: resets to template at every phase boundary via project-task-complete
project-task-complete is required at every phase boundary (not just end-of-session)
LESSONS.md review added to all project closures: identify CLAUDE.md/AGENTS.md promotion candidates
Task Brief format added (Task-Brief-N-[descrip].md with Agent used field for model tracking)
New /write-task-brief skill for external agent task brief creation
ROADMAP sync hook: PostToolUse on ROADMAP.md updates STATUS.md descriptions automatically
Added UPGRADES.md: ideas parking lot for discovered-but-uncommitted improvements
Added DASHBOARD.md: optional Obsidian view layer (Dataview/Bases) over STATUS + task frontmatter
Added Dev Project Extras section: ARCHITECTURE.md + DESIGN.md responsibilities documented
Added Document Responsibilities table (single-responsibility per artifact)
Design spec (SMTM-v4-design.md) folded into this document and archived
Feedback moved from STATUS.md to NEXT-STEPS.md (Talbot Response)
Key Decisions moved from STATUS.md to LESSONS.md (process) or DESIGN.md (technical, dev projects)
LESSONS.md now captures process decisions and pivots (dev projects: DESIGN.md for technical decisions)
_active.md retained unchanged (cross-project task tracker, read at session start)

v3.4 Changes

Added NEXT-STEPS.md as the standard project conversation container (replaces ad-hoc task files for project-level dialogue)
Added archive/ subfolder to project structure for completed reference documents
Added /project-continue skill — mirrors /task-continue at the project level
Updated /project-start to create NEXT-STEPS.md and archive/ by default
Updated Project Lifecycle diagram to show NEXT-STEPS.md-driven cycle
Removed TASKS.md from required project files (use PLAN.md + task files instead)