Simple Markdown Task Management (SMTM)

[Project]: [Brief Title]

Date: YYYY-MM-DD Type: Feature / Bug Fix / Refactor Status: In Progress

Objective

[What needs to be done and why]

Acceptance Criteria

Criterion 1
Criterion 2
Criterion 3

Files to Modify

path/to/file.ts - [what changes]
path/to/file2.ts - [what changes]

Test Strategy

[How to verify it works]

Notes

[Working notes, blockers, decisions made during implementation]

---

### Large Projects (days/weeks)

**Examples:** New site features, major refactors, multi-phase work, architectural changes

**Workflow:**
1. **Create a PLAN:**
   - `Projects/[project-name]/plans/YYYY-MM-DD_PLAN_Description.md`
   - Break into phases with time estimates
   - Identify critical files
   - Define verification strategy

2. **Execute in phases:**
   - Each phase gets its own ACTIVE file in `active/`
   - Work through phase, commit frequently
   - When phase completes, move ACTIVE → `complete/` and rename to SESSION

3. **Document completion:**
   - PLAN file stays in `plans/` folder (don't move it to complete/)
   - SESSION reports reference the PLAN
   - Final SESSION report summarizes all phases

**PLAN file template:**
```markdown
# [Project]: [Brief Title]

**Date:** YYYY-MM-DD
**Scope:** [Estimate of effort, e.g., "3-5 days, 5 phases"]

## Context
[Why this change is needed, problem it solves, background]

## Approach
[High-level strategy, architectural decisions]

## Phases

### Phase 1: [Name] (X hours)
- Task 1
- Task 2
- **Verification:** [How to test this phase]

### Phase 2: [Name] (X hours)
- Task 1
- Task 2
- **Verification:** [How to test this phase]

## Files Affected
- Critical file 1 - [why it's critical]
- Critical file 2 - [why it's critical]

## Success Criteria
[How to verify end-to-end that the project is complete]

## Risks & Mitigations
[What could go wrong, how to handle it]

SESSION report template:

# [Project]: [Brief Title]

**Date:** YYYY-MM-DD
**Status:** Complete / In Progress / Blocked

## Summary
[2-3 sentences of what was accomplished]

## Changes Made

**Files Modified:**
- file1.ts - [what changed]
- file2.ts - [what changed]

**Files Created:**
- newfile.ts - [purpose]

**Commits:**
- abc1234 - [commit message]
- def5678 - [commit message]

## Test Results
[Pass/fail rates, metrics, verification steps completed]

## Known Issues
[Any remaining issues or technical debt]

## Next Steps (if applicable)
[What to work on next, or mark as "Complete - no further work needed"]

Decision Framework: When to Use Advanced Tools

Current System (Markdown + Claude Code)

Use for: 90% of your tasks

Strengths:

Zero setup overhead
Version controlled
Tool agnostic (works with any AI assistant)
Human-readable in Obsidian
No plugin dependencies

Ideal for:

All small tasks
Most medium tasks
Large projects with clear requirements

Superpowers Plugin

Use when:

Project needs TDD enforcement (you want test-first discipline)
Multi-phase work requires structured brainstorm → plan → execute
Complex architecture needs Socratic questioning before coding
You want two-stage review (spec compliance + code quality)

Cost:

10-20 min setup overhead per project
Higher token consumption (subagent dispatch + reviews)
Requires plugin installation

Benefit:

Prevents premature “done” (structural enforcement)
Forces test coverage
Breaks down complex features systematically

Skip for:

Small/medium tasks (overkill)
Simple fixes or refactors
Markdown/KB work

Installation:

# In Claude Code session:
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Workflow:

/superpowers:brainstorm  # Socratic refinement (skip for simple tasks)
/superpowers:write-plan  # Generate granular TASKS.md
/superpowers:execute-plan  # Execute with TDD + subagent review

Ralph Loop Plugin (Overnight Autonomous Work)

Use when:

Overnight autonomous work would help (e.g., migrate 50 files, bulk refactoring)
Well-defined TASKS.md exists with clear success criteria
Batch operations that don’t need interactive decisions

Cost:

Setup time + headless mode configuration
Risk of waking up to failed state (need good rollback plan)

Benefit:

Wake up to completed work
Good for repetitive, mechanical tasks

Skip for:

Interactive development
Exploratory work
Tasks requiring judgment calls

Installation:

# In Claude Code session:
/plugin install ralph-loop@claude-plugins-official

Usage:

# From terminal (not in CC session):
claude -p "Read TASKS.md and complete all items" \
  --allowedTools "Edit,Read,Bash,Write,Glob,Grep" \
  --max-iterations 50

TASKS.md Pattern (Per-Project Spec)

Use for:

Any project where detailed task tracking helps
Works with or without Superpowers
Good for projects using Ralph Loop
Version-controlled plan that survives /clear

Format: See TASKS_md_Template for 3 templates:

Feature Development (Superpowers-compatible)
Overnight Autonomous Run (Ralph Loop)
Simple Checklist (Lightweight)

Integration with _Now/_Next:

_Now.md becomes a lightweight dispatcher:

- Monorepo: see Projects/monorepo/active/YYYY-MM-DD_ACTIVE_*.md
- Python utils: see TASKS.md in utils repo
- KB: reorganize 04_AI/ (working directly)

The _Now/_Next Pattern

Verdict: KEEP IT (with improvements)

Why keep _Now/_Next:

Temporal state matters - “Now” vs “Next” describes what you’re doing vs what you learned
Works for small tasks - Don’t force every 10-minute task into a PROJECT folder
Cross-project dispatcher - _Now.md is perfect for “what am I working on today?”
Insight capture - _Next files capture workflow improvements, not task completion

Improvements to _Now/_Next Pattern

1. Date-stamp _Next files:

Old: _Next2.md, _Next3.md
New: _Next_2026-02-14_Testing-Workflow.md

2. Add source reference:

---
Source: _Now.md -- "Research spec-driven workflows"
---

## What Worked
...

## Friction Points
...

## Workflow Improvements
...

3. Keep _Now.md lightweight:

Don’t put task details in _Now.md
Point to project-specific ACTIVE files or TASKS.md
Think of it as “what am I working on?” not “detailed task spec”

4. Use _Next for insights, not logs:

Bad: “Completed tasks 1, 2, 3” (belongs in SESSION report)
Good: “Learned that Superpowers is overkill for markdown work” (cross-cutting insight)

Integration with Claude Code Slash Commands

Existing Commands

/now - Review tasks in _Now.md
/ptr - Proceed to implement tasks autonomously, test thoroughly, report when done
/nowcpw - Review _Now.md + confirm understanding + plan approach + wait for approval
/cpw - Confirm + plan (without /now)
/aic - Ask for clarification

Recommended Workflow Patterns

Small task pattern:

1. Update _Now.md with task
2. /now → /ptr
3. Work completes
4. (Optional) Document insights in _Next file

Medium task pattern:

1. Create ACTIVE file with spec
2. /ptr (points Claude to the ACTIVE file)
3. Work completes
4. Move ACTIVE → complete/ and rename to SESSION

Large project pattern:

1. Create PLAN file
2. Get user approval
3. Create ACTIVE file for Phase 1
4. /ptr for Phase 1
5. Move to SESSION, create ACTIVE for Phase 2
6. Repeat until all phases complete

Best Practices

Do’s

Match overhead to task size - Don’t create PROJECT folders for 10-minute tasks
Use templates - Consistent structure aids scanning and review
Date-stamp everything - YYYY-MM-DD prefix enables chronological sorting
Move, don’t copy - When work completes, move ACTIVE → complete/ (don’t duplicate)
Commit frequently - Atomic commits per logical change
Test before reporting done - See CLAUDE.md testing requirements
Document decisions - Future you will thank present you

Don’ts

Don’t over-engineer simple tasks - 5-minute fix doesn’t need a PLAN
Don’t put task details in _Now.md - Keep it lightweight, move details to ACTIVE/TASKS.md
Don’t use paired indices - (_ToAI2 → _FromAI2 forces 1:1 that doesn’t exist)
Don’t leave ACTIVE files in active/ - Move to complete/ when done
Don’t duplicate content - One source of truth per topic
Don’t skip testing - Especially for UI changes (see CLAUDE.md testing workflow)

Success Metrics

Track these after 2-4 weeks of using the new system:

Metric	How to Check	Target
Task completion clarity	How often do you know exactly what was done?	100%
Workflow friction	How often do you struggle to find where to document something?	Rare
Premature “done” incidents	How often does Claude claim done without testing?	<10%
Time to context switch	How long to remember what you were working on?	<2 min
Obsidian navigability	Can you find past work quickly?	Always

Examples

Scenario 1: Quick KB Edit (Small Task)

_Now.md:

KB: Fix typo in 04_AI-upgrade/01_Claude Code.md

Workflow:

Open Claude Code
/now → “Fix the typo”
Done, commit
No _Next file needed (trivial change)

Scenario 2: Component Creation (Medium Task)

_Now.md:

Project: monorepo - Add dark mode toggle component

Create ACTIVE file: Projects/monorepo/active/2026-02-16_ACTIVE_Dark-Mode-Toggle.md

Workflow:

Spec out component requirements in ACTIVE file
/ptr → Claude implements
Test (build, E2E, accessibility)
Move to complete/ and rename to SESSION
Document any insights in _Next file if architectural learnings

Scenario 3: Multi-Phase Feature (Large Project)

_Now.md:

Project: monorepo - Accessibility audit and remediation (see PLAN)

Create PLAN file: Projects/monorepo/plans/2026-02-14_PLAN_Accessibility-Audit.md

Phases:

Create 2026-02-14_ACTIVE_Phase-1-Audit.md → work → SESSION
Create 2026-02-15_ACTIVE_Phase-2-Color-Contrast.md → work → SESSION
Create 2026-02-15_ACTIVE_Phase-3-Responsive.md → work → SESSION
Create 2026-02-16_ACTIVE_Phase-4-Testing.md → work → SESSION
Final SESSION report summarizes all phases

PLAN stays in plans/, SESSION reports in complete/

Summary: The Layered Approach

Layer 1: Cross-Project Dispatcher

_Now.md - Lightweight “what am I working on?”

Layer 2: Per-Project Specs

YYYY-MM-DD_ACTIVE_*.md - Medium/large tasks
YYYY-MM-DD_PLAN_*.md - Large projects
TASKS.md (optional) - Detailed task breakdown

Layer 3: Session Outcomes

YYYY-MM-DD_SESSION_*.md - Completion reports
_Next_YYYY-MM-DD_*.md - Cross-cutting insights

Layer 4: Advanced Tools (optional)

Superpowers - For TDD-driven complex features
Ralph Loop - For overnight autonomous work

Bottom Line: Start simple (_Now + direct work), graduate to structured (ACTIVE → SESSION), adopt tools (Superpowers/Ralph) only when specific project justifies the setup cost.

Version: 2.0 Replaces: Previous Simple Task Management.md, Quick Reference, Research Report Status: Active system as of 2026-02-16