Markdown Project Management System

VS Code extension for managing the project database workspace.

✨ Works everywhere: Desktop VS Code, Codespaces, and vscode.dev!

Features

• List Active Projects: Displays all active projects from the db/projects/ directory in a fullscreen webview
• List All Tasks: Shows all tasks from all projects in a card-based layout with filtering
• Task Completion: Smart completion that converts markdown list items into formatted tasks (only in db/projects/*/README.md files within ## Tasks sections)
• Task Work Files: Ctrl+Click any task title to open or create a dedicated markdown file for working on that task
• Fuzzy Search: Real-time filtering as you type - searches across project names, tags, folders, task titles, and descriptions
• React-powered UI: Modern, responsive interface built with React
• Beautiful Design: Clean layouts with search bar, icons, and VS Code theme integration
• Cross-platform compatible: Works in Desktop VS Code, Codespaces, and vscode.dev
• Auto-refresh: Both views automatically update when README files change

Commands

• Projects: List Active Projects - Opens a fullscreen webview showing all projects with Status: active
• Projects: List All Tasks - Opens a fullscreen webview showing all tasks from all projects
• Create Task Work File - Creates a dedicated markdown file for working on a task (available via right-click menu on task lines)

Usage

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type "Projects: List Active Projects"
3. A fullscreen webview opens with:
   • Search bar at the top (fuzzy search, filters as you type)
   • Table with two columns: Project Name and Tags
   • Project count showing filtered/total results
   • Clear button (X) to reset search

Development

This extension is designed to be developed and used within this workspace.

Setup

cd tools/MarkdownProjectManagementSystem
npm install
npm run build

Running the Extension

1. Open this folder in VS Code
2. Run npm run watch to build the React app in watch mode
3. Press F5 to open Extension Development Host
4. Run the command from the Command Palette
5. Make changes and reload (Ctrl+R) to see updates

Project Structure

MarkdownProjectManagementSystem/
├── src/                      # Source code (all .js/.jsx files)
│   ├── extension.js         # Main extension entry point
│   ├── taskParser.js        # Task parsing utilities
│   ├── watcherManager.js    # File watcher management
│   ├── migrate-tasks.js     # Task migration script
│   ├── esbuild.js          # Build configuration
│   └── webview/            # React components
│       ├── index.jsx       # Projects view entry
│       ├── ProjectsList.jsx # Projects list component
│       ├── tasks-index.jsx # Tasks view entry
│       ├── TasksList.jsx   # Tasks list component
│       └── styles.css      # Webview styles
├── docs/                    # Permanent documentation
│   ├── WEBVIEW-GUIDE.md    # Maintained guides
│   ├── USAGE-GUIDE.md
│   ├── DEVELOPMENT.md
│   └── temp/               # Temporary/generated docs
│       └── *.md            # Feature summaries, implementation details
├── dist/                    # Build output (generated)
├── resources/               # Static resources
└── package.json            # Extension manifest

Directory Guidelines:

• src/ - All source code must go here
• docs/ - Long-standing documentation that should be maintained
• docs/temp/ - Temporary summaries and implementation notes (can be deleted anytime)

Build Commands

• npm run build - Production build
• npm run watch - Development build with auto-rebuild
• npm run vscode:prepublish - Pre-package build

Technology Stack

• React 18 - UI framework
• esbuild - Fast bundler
• VS Code FileSystem API - Cross-platform file access
• Fuzzy search - Custom implementation

Works everywhere:

• ✅ Desktop VS Code (Windows, macOS, Linux)
• ✅ GitHub Codespaces
• ✅ vscode.dev (web-based VS Code)

Active Project Definition

A project is considered active when:

• It is located in /db/projects/ directory
• Its README.md contains **Status:** active

Projects with Status: paused or Status: archived are not included.

Output

The extension displays a fullscreen webview with:

• Two-column table layout
  • Column 1: Project Name
  • Column 2: Tags
• Clean, modern design using VS Code theme colors
• Sticky header for easy navigation
• Hover effects for better UX

Projects are sorted by focus priority: now → this-week → someday

Task Format

Tasks are extracted from project README.md files under the ## Tasks section. The format supports optional metadata including tags, creation date, and due date.

New Canonical Format

## Tasks
- [ ] **Task title** — Optional description (tags: tag1, tag2; created: 2025-01-06; due: 2025-01-15)
- [ ] **Another task** (created: 2025-01-05)
- [ ] **Task with work file** (created: 2025-01-07; content: tasks/a3b5c7d9.md)
- [ ] **Simple task**
- [x] **Completed task** — Done (created: 2025-01-01)

Format Rules

• Title (required): Inside **...** bold markers
• Description (optional): After — (em dash), before metadata
• Metadata (optional): Final parenthesized block with semicolon-separated key-value pairs
  • tags: comma-separated list
  • created: ISO date (YYYY-MM-DD)
  • due: ISO date (YYYY-MM-DD)
  • content: path to task work file (e.g., tasks/a3b5c7d9.md)
• Checkbox: [ ] for incomplete, [x] for complete

Examples

- [ ] **Implement auth** — JWT-based authentication (tags: backend, security; created: 2025-01-06; due: 2025-01-15)
- [ ] **Design homepage** (tags: frontend, ui; created: 2025-01-05; content: tasks/x7y2z4a1.md)
- [ ] **Write tests** — Unit tests for API (created: 2025-01-04)
- [ ] **Quick fix**

Legacy Format Support

The extension also supports legacy formats for backward compatibility:

• - [ ] **Title** — Description (2025-01-06) (date treated as created date)
• - [ ] **Title** — Description
• - [ ] **Title**

Use the migration script to convert legacy tasks: npm run migrate-tasks

The tasks view displays project name, task title, description, tags, creation date, and due date. Tasks are sorted by creation date (newest first) and can be filtered by any field.

Task Completion Feature

The extension includes an intelligent completion provider that automatically converts simple markdown list items into the full task format with metadata support.

Usage:

1. Open a project README at db/projects/<project-name>/README.md
2. Navigate to the ## Tasks section
3. Type a list item: - Implement user authentication
4. Trigger completion (Ctrl+Space) or wait for auto-complete
5. Select "Convert to project task"
6. Result: - [ ] **Implement user authentication** — description (tags: tag1, tag2; created: 2025-01-06; due: YYYY-MM-DD)
7. Tab through fields to fill or delete unwanted parts

Features:

• Only activates in project README files (db/projects/*/README.md)
• Only works inside ## Tasks sections (not ### Tasks)
• Automatically inserts today's date as created date
• Tab stops for description, tags, and due date
• Easy to delete unwanted metadata fields
• Ignores headings inside code blocks
• Cross-platform compatible

Snippet Fields:

• Tab 1: Description (optional, delete " — description" if not needed)
• Tab 2: Tags (optional, delete "tags: tag1, tag2; " if not needed)
• Tab 3: Due date (optional, delete "due: YYYY-MM-DD" if not needed)

Task Work Files

Create dedicated work files for tasks to keep your work organized and separate from the project README.

Usage:

Method 1: Ctrl+Click (Recommended)

1. Open a project README at db/projects/<project-name>/README.md
2. Hold Ctrl (or Cmd on Mac) and click on any task title in the ## Tasks section
3. The work file opens or is created automatically

Method 2: Context Menu

1. Open a project README at db/projects/<project-name>/README.md
2. Right-click on any task line in the ## Tasks section
3. Select "Create Task Work File" from the context menu
4. A new markdown file is created in db/projects/<project-name>/tasks/ with a random ID
5. The task line is updated with a content: tasks/<filename>.md attribute
6. The work file opens automatically with the task title, description, and a Work section

Work File Format:

# Task Title

## Description

Task description from the README

## Work

(Your work notes go here)

Features:

• Automatically creates the tasks/ folder if it doesn't exist
• Generates a random 8-character ID for each file (e.g., a3b5c7d9.md)
• Preserves task metadata (tags, dates, etc.)
• Opens the file with cursor positioned in the Work section
• Updates the task line with the content attribute for easy reference
• Ctrl+Click navigation: Hold Ctrl (or Cmd on Mac) and click on any task title to open or create its work file
  • No work file yet → Creates a new one with a random ID
  • Work file referenced but missing → Recreates it with the same ID
  • Work file exists → Opens it directly

Example:

## Tasks
- [ ] **Implement authentication** — JWT-based auth (tags: backend; created: 2025-01-07; content: tasks/a3b5c7d9.md)

The work file allows you to keep detailed notes, code snippets, and progress updates without cluttering the main project README.

Quick Navigation: Navigate to task work files by holding Ctrl (or Cmd on Mac) and clicking on the task title. The title will appear underlined when you hover over it with Ctrl held. This works for all tasks:

• Task without work file: Creates a new work file automatically
• Task with missing file: Recreates the file with the existing ID from the task metadata
• Task with existing file: Opens the file directly

This provides a seamless workflow - just Ctrl+Click any task title to start working on it!

Task Migration

To migrate existing tasks from legacy format to the new canonical format:

npm run migrate-tasks

Or specify a directory:

node src/migrate-tasks.js ./db/projects

The script:

• Scans all .md files recursively
• Converts legacy date format (YYYY-MM-DD) to (created: YYYY-MM-DD)
• Normalizes spacing and metadata order
• Is idempotent (safe to run multiple times)
• Reports which files were modified