Project Management

Workspace-level project management built on YAML frontmatter markdown files stored in each repo’s .teamide/ directory.

Overview

Each repo can opt in to PM by initializing a project.yml config. Once initialized, the system manages three categories of markdown files:

  • Plans — parent documents that group tasks into roadmaps or initiatives
  • Tasks — individual work items with status tracking
  • Notes — freeform documentation and meeting notes

File Structure

repo/
  .teamide/
    project.yml          # Project config
    plans/
      roadmap-v2.md
    tasks/
      fix-auth-bug.md
    notes/
      standup-2026-04.md

project.yml Schema

name: My Project
status: active              # active | paused | archived
team: []                    # team member identifiers
labels: []                  # custom labels for categorization
references: []              # external file references (see below)
board_columns:
  tasks:
    - backlog
    - todo
    - in-progress
    - review
    - done
  plans:
    - draft
    - active
    - complete
discovery_ignore:
  - node_modules
  - .git
  - dist
  - build

Frontmatter Conventions

Tasks

---
title: Fix authentication bug
status: in-progress
priority: high
labels: [bug, auth]
assignee: dcherrera
plan: q1-roadmap.md          # optional: links task to a plan
created: 2026-04-05
---
# Fix authentication bug

Description and notes here...

Plans

Plans act as containers for tasks. The tasks array lists the filenames of linked tasks.

---
title: Q1 Roadmap
status: active
tasks:                        # linked task filenames
  - implement-auth.md
  - design-dashboard.md
created: 2026-04-01
---
# Q1 Roadmap

Plan content...

The tasks and plan fields are kept in bidirectional sync by the backend. Linking a task to a plan adds the task filename to the plan’s tasks[] and sets plan: planFilename on the task.

Notes

---
title: Sprint Standup
created: 2026-04-05
---
# Sprint Standup

Notes content...

Reference System

The references array in project.yml allows including files from outside the .teamide/ directories:

references:
  - type: tasks
    path: docs/todo.md
  - type: plans
    path: ROADMAP.md

Referenced files appear alongside managed files in list endpoints with source: "referenced".

Portfolio

The portfolio endpoint scans all repos in ~/TeamIDE/{owner}/{repo}/ and returns which are PM-configured and which are not, along with task status counts for configured projects.

Projects Tab

Access the Projects tab from any workspace view. It shows a Kanban portfolio board of all repos in the pool.

Portfolio Board

  • Repos are grouped into columns by their status field: Active, Planned, Paused, Archived
  • Each card shows the repo name, project name (if different), and task count badges
  • Clicking a card navigates to the project detail view

Initializing Projects

Repos without a .teamide/project.yml appear in the Unconfigured Repos section below the board. Click Initialize to create a project config with a name and status. The repo then appears on the board in the appropriate column.

Project View

Click any project card on the portfolio board to drill into its detail view.

Shows the project name, status badge, and repo path. A back button returns to the portfolio board (or the plan list, if viewing a plan detail).

Task Board

A Kanban board showing all tasks from the project’s .teamide/tasks/ directory. Columns are defined by board_columns.tasks in project.yml (defaults: backlog, todo, in-progress, review, done). Each card shows:

  • Title (from frontmatter or filename)
  • Priority indicator (color dot: red=high, amber=medium, green=low)
  • Plan badge (if the task is linked to a plan)
  • Status badge
  • Assignee (if set)
  • Labels (as small chips)

Plan List

The Plans tab shows a vertical list of all plans in the project. Each row displays:

  • Plan title and status badge (draft/active/complete)
  • Task count (number of linked tasks)
  • Edit button (opens the plan in the File Editor)

Clicking a plan row drills into the Plan Detail View.

Plan Detail View

Shows a single plan as a task container:

  1. Header — back button (returns to plan list), plan title, status badge, “Edit” button
  2. Link task bar — dropdown of orphaned tasks (tasks not linked to any plan) + “Link” button
  3. Linked tasks Kanban — task columns (backlog → done) showing only the tasks linked to this plan
  4. Unlink — each card has a small unlink icon on hover to remove it from the plan

Creating a task from within the plan detail view pre-links it to the current plan.

Notes List

A simple list (not a Kanban board) of notes from .teamide/notes/. Each row shows the note title, filename, and tag chips if present.

Managing Work

Creating Items

Click the + New button next to the sub-tabs in any project view to create a new task, plan, or note (depending on the active tab). When viewing a plan detail, the button creates a new task pre-linked to the current plan.

Enter a title and optional fields (status, priority, labels, etc.). The filename is auto-generated from the title as a slugified .md file.

Editing Items

Click any card on a Kanban board or any note in the notes list to open the File Editor slide-over panel on the right side. The editor shows:

  • Structured frontmatter fields (title, status, priority, assignee, labels, due date, tags — varies by type)
  • For tasks: a plan link field showing the linked plan (with unlink option) or a dropdown to link to a plan
  • A markdown textarea for the body content

Click Save to write changes back to the file. Click Delete to permanently remove the file from disk.

Drag-Drop Status Changes

Cards on Kanban boards support drag-and-drop between columns:

  • Portfolio board: Drag a project card to change its status in project.yml
  • Task board: Drag a task card to update its status frontmatter field
  • Plan detail board: Drag a linked task to update its status

The drop target column highlights with an orange border during drag. Changes are written to disk immediately.

Deleting Items

Open the File Editor for any item and click the Delete button. A confirmation dialog appears before the file is permanently removed.

All Tasks Board

The All Tasks view aggregates tasks from every configured workspace repo into a single Kanban board.

Accessing

Toggle between Portfolio and All Tasks using the view switcher at the top of the Projects tab. The toggle is hidden when drilled into a project detail view.

Columns

Fixed default columns: Backlog, Todo, In Progress, Review, Done. Tasks with a status that doesn’t match any column appear in an Uncategorized column.

Cross-Project Cards

Each card shows an amber project badge indicating which repo it belongs to. Cards also display a plan badge if the task is linked to a plan.

Filtering

Client-side filters at the top of the board:

  • Project — filter to specific repos
  • Assignee — filter by task assignee
  • Priority — filter by priority level (high, medium, low)
  • Plan — filter by plan name or “Unplanned” for tasks not linked to any plan

Drag-Drop

Drag any card between columns to update its status. The change is written to the correct repo’s markdown file on disk.

Editing

Click any card to open the File Editor in a right-side drawer. Save and delete operations target the correct repo.

When navigating from All Tasks into a project detail view, the back button returns to All Tasks (not Portfolio). The system remembers which view you came from.

Discovering Existing Files

The discovery system scans repos for legacy markdown files (TODO.md, ROADMAP.md, etc.) that aren’t already managed by the PM system.

How It Works

When a project is loaded, the backend recursively walks the repo looking for markdown files matching known patterns:

Pattern Detected Type
build_plan.md, BUILD_PLAN.md plan
PLAN-*.md, plan-*.md plan
ROADMAP.md plan
TODO.md, todo.md tasks
Ideas.md, ideas.md note
notes.md, NOTES.md note
important_notes.md note

Files inside .teamide/, node_modules, .git, and other directories listed in discovery_ignore are skipped. Files already in the references[] array are excluded.

Discovered Files Section

A collapsible “Discovered Files” section appears below the tab panels in the project view when files are found. Each entry shows:

  • Relative file path
  • Detected type badge (plan/tasks/notes)
  • Title (from frontmatter or first heading)
  • Snippet preview (~200 chars)

Actions

  • Add to Project — Adds the file path to project.yml references[]. The file then appears in the corresponding tab (plans/tasks/notes) as a referenced file.
  • Ignore — Adds the file path to project.yml discovery_ignore[]. The file no longer appears in discovery results.

Files stay where they are — no moves or copies are made.