plainpm — Conventions & Configuration

Data Directory

All user data (projects, team, meetings, reports) lives in the data/ subdirectory. This separation keeps framework files (scripts, templates, prompts, agent configs) apart from personal data, so the framework repo can be shared on GitHub without exposing private information.

Setup options:

• Gitignore (default) — data/ is listed in .gitignore, so it won't be pushed to the shared repo. Use a separate backup method for your data.
• Private repo — Clone a private repo into data/ manually: git clone <your-private-repo-url> data. Since data/ is gitignored, the URL is never exposed in the public repo. Do not use git submodule — that would leak the private repo URL in .gitmodules.

If data/ doesn't exist when a command runs, the agent will offer to create the directory structure for you.

Solo vs. Team Use

plainpm works for both individual users and team managers.

• Solo mode: only one data/team/*.md file exists (yours). When you say "me", "my task", or "assign to me", the agent assigns ownership to your first_name. The /my-team dashboard shows your personal workload. Meeting attendees who aren't you are external — no task files are created for them.
• Team mode: multiple data/team/*.md files exist. Owner matching works by first_name across the roster. /my-team shows everyone's workload.

The agent detects the mode automatically by counting files in data/team/. No configuration needed.

Team Roster

Team members are defined in data/team/*.md files (template: templates/team-member.md). Each has full_name, first_name, and role in YAML front matter. Use first names for natural language matching. Include yourself — create a file for the main user with self: true in the front matter.

Below the front matter, a ## Notes section holds freeform comments about the person — working style, preferences, context, or anything useful to remember.

Self-references: phrases like "me", "my", "myself", "I" in owner context should resolve to the current user. In solo mode, that's the only team member. In team mode, the agent looks for the team member with self: true in their front matter. If no member has self: true, ask the user to clarify.

External people (clients, vendors, stakeholders not in data/team/) are NOT tracked as task owners. Their action items appear in meeting notes only — never create task files for them.

Tag Taxonomy

Tags are freeform strings in the tags array. Common categories:

• planning, research, design, development, testing, deployment
• bug, feature, improvement, documentation
• stakeholder, customer, internal

Status Values

Task statuses: todo | in-progress | blocked | done Project/stream statuses: active | on-hold | completed

Priority Values

Always display priority as icon + string (e.g., "🟠 high").

Task ID Convention

• Stream-level tasks: PROJECT-STREAM-NNN (e.g., ALPHA-BE-001)
• Project-level tasks: PROJECT-NNN (e.g., ALPHA-001)
• Standalone tasks: TASK-NNN (e.g., TASK-001) — tasks not tied to any project
• IDs use uppercase. Stream abbreviations are short (2-4 chars) derived from the stream folder name.
• NNN is zero-padded to 3 digits, auto-incremented per scope.

Links

Projects, streams, tasks, and meeting notes all support a links array in front matter. Each link stores both display text and URL:

links: [{label: "Jira ticket", url: "https://jira.example.com/ALPHA-123"}, {label: "Design doc", url: "https://docs.example.com/design"}]

• label: the text displayed in reports and dashboards (used as hyperlink text)
• url: the full URL

When rendering links in reports or dashboards, output them as markdown hyperlinks: [label](url).

Multi-Owner Tasks

Tasks can be assigned to multiple team members at once using the owners array (replaces the old owner field):

owners: [Alice, Bob, Carlos]
completion_mode: any

• owners: list of first_name values from data/team/*.md. Use an empty list [] for unassigned. Single-owner tasks are still expressed as a one-element array: owners: [Alice].
• completion_mode: controls how the task is considered done:
  • any (default) — the task is done when any one of the assigned members marks it complete. E.g., a task assigned to several people where only one needs to do it.
  • all — the task is done only when every assigned member has independently completed it. Partial completion is tracked in a completions map in the front matter (see below).

completion_mode: all — partial completion tracking

When completion_mode: all, the front matter includes a completions map that tracks which members have completed their part:

owners: [Alice, Bob]
completion_mode: all
completions: {Alice: 2026-04-08, Bob: null}

• Each key is a member first_name; value is the completed_date (YYYY-MM-DD) or null if not yet done.
• The task's status becomes done and completed_date is set only when all values in completions are non-null.
• When a member marks their part done, their entry in completions is updated but status stays in-progress until everyone is done.
• When the agent runs /done, if the task has completion_mode: all and multiple owners, it asks: "Who is marking this done?" (unless the user specifies a name).

Displaying multi-owner tasks

• All dashboards: the Owner column shows the owners joined with / (e.g., Alice / Bob).
• For completion_mode: all tasks, the Owner column shows completion state: Alice ✅ / Bob ⬚.
• Team dashboard (my_team): a multi-owner task appears in each assigned member's section.

When completion_mode is unclear, ask the user

If the user assigns a task to multiple people and does not specify completion_mode, ask:

"Should this task be done when any one person completes it (any), or does each person need to complete it independently (all)?"

Project & Stream Ownership

Projects and streams can have owners, and co-ownership is supported. Ownership is expressed with an owners array in the project.md / stream.md front matter — the same convention as tasks:

owners: [Alice, Bob]

• owners: list of first_name values from data/team/*.md. Use an empty list [] for unassigned. A single owner is a one-element array: owners: [Alice]. Two or more entries mean co-ownership.
• Owner names must match a team member's first_name. Self-references ("me", "my", "I", "myself") resolve to the current user (the member with self: true, or the only member in solo mode).
• Project/stream ownership is independent of task ownership. Owning a project does not imply owning its tasks, and vice versa.
• Unlike tasks, projects and streams have no completion_mode — co-owners simply share responsibility; there is no per-owner completion tracking.

Displaying project/stream owners

• The team dashboard (my_team) and weekly report (weekly_report) show an Owner column in their Project Status and Stream Status tables. Co-owners are joined with / (e.g., Alice / Bob); an unassigned project/stream shows Unassigned.
• The /status report shows the owner(s) for the project and for each stream.

Dependencies

Tasks can declare dependencies via a blocked_by array of task IDs:

blocked_by: [ALPHA-BE-001, ALPHA-003]

• When all tasks in blocked_by are done, the dependency is resolved.
• Setting blocked_by on a task does not automatically set its status to blocked — that's still a manual decision.
• When /done completes a task, it checks if any other open tasks have that ID in blocked_by. If a dependency is now fully resolved (all blocked_by IDs are done), the agent notifies the user and suggests unblocking.
• Dashboards show blocked_by IDs next to blocked tasks for visibility.

Dates

• Format: YYYY-MM-DD
• due_date: optional — tasks can have no due date
• completed_date: set automatically when status changes to done
• created: set when task/project/stream is created

Same-Day Updates

When adding an update to ### Updates and an entry for the same date already exists, do not add a duplicate date line. Instead, convert to a grouped format with sub-bullets:

Single update on a date (standard):

- 2026-04-06: Completed API integration (source: [standup](path))

Multiple updates on the same date (grouped):

- 2026-04-06:
  - Completed API integration (source: [standup](path))
  - Decided to switch to REST instead of GraphQL (source: [architecture review](path))

Rules:

• When adding an update and the latest entry has the same date as a single-line entry, convert it to the grouped format and add the new sub-bullet.
• When adding an update and a grouped entry for that date already exists, append a new sub-bullet.
• Different dates always get their own top-level bullet (- YYYY-MM-DD:).
• Dashboards display the latest sub-bullet from the most recent date, with (+N more) appended when there are additional entries for that date.

Working Days Calculation

Working days = Mon–Fri only. Exclude weekends (Sat, Sun). No holiday calendar — just weekdays. Used in /my-team to calculate "days open" for each task.

Meeting Processing Rules

• .vtt files in data/meetings/transcripts/ → parse transcript, generate structured notes
• .md files → process existing manual notes
• Cross-reference attendees with team roster (data/team/*.md)
• Action items: all listed in a single "Action Items" section (notes are shared with everyone, no team/external split)
• Task creation: only create task files for team members' action items — never for external attendees
• Solo mode: the user is the only team member; all other meeting attendees are external
• If uncertain whether someone is team or external (team mode only): ask the user before proceeding
• Completeness over brevity: meeting notes are the permanent record. Capture all topics discussed, all decisions (with context), all concerns raised, and all open questions. A longer note that misses nothing is always better than a concise one that drops details.
• Cross-reference updates: after extracting action items, meeting processing identifies projects, streams, and existing tasks that were meaningfully discussed and proposes dated summary notes for their ### Updates sections. The agent shows each proposed update alongside the entity's existing latest update, then asks the user to approve, edit, replace, or skip each one. This ensures the user stays in control — the existing update may be more important, or the user may want to merge both into a single entry. Format: - YYYY-MM-DD: <summary> (source: [meeting title](path)). Skip passing mentions with no substance. See Same-Day Updates below for handling multiple updates on the same date.

Notes

Notes are the general-purpose content type for capturing information outside of meetings — decisions, processes, observations, team management topics, or anything worth recording. Notes can live in areas, projects, or streams.

• Notes use templates/note.md and have type: note in front matter (vs type: meeting for meeting notes).
• Notes and meeting notes share the same notes/YYYY/MM/ folders — the type field distinguishes them.
• Create notes with /new-note or manually.
• Notes can optionally trigger cross-reference updates and task creation, just like meeting notes.

Note locations

• Area note: data/meetings/areas/<area-slug>/notes/YYYY/MM/YYYY-MM-DD-title.md
• Project note: data/projects/<slug>/meetings/YYYY/MM/YYYY-MM-DD-title.md
• Stream note: data/projects/<slug>/streams/<stream-slug>/notes/YYYY/MM/YYYY-MM-DD-title.md

Stream notes are a new location — create the notes/YYYY/MM/ subfolder inside the stream directory as needed.

Meeting Areas

Meeting areas are named groupings for recurring meetings that don't belong to a specific project — e.g., team syncs, partner engagements, 1:1s, all-hands, vendor calls. Areas also hold manually created notes on the same topics.

• Each area is a folder under data/meetings/areas/<area-slug>/
• Each area has an area.md definition file (metadata + description)
• Notes go in data/meetings/areas/<area-slug>/notes/YYYY/MM/
• Area slugs use lowercase-kebab-case (e.g., team-syncs, partner-engagements)
• To create a new area: create the folder, add area.md (from templates/area.md), and start dropping notes in.
• The area field in note front matter references the area slug (leave blank for project notes or unstructured general notes).
• Areas are independent of projects — no project file or task ID prefix is needed.
• Area folders only contain area.md and notes/ — never put task files inside an area folder.
• Task creation rules from meeting processing still apply: only team members' action items become tasks. Tasks go to the relevant project/stream, or to data/tasks/YYYY/ as standalone tasks (TASK-NNN) if no project context applies.

Date-Based Organization

Tasks are organized into year subfolders. Meeting notes, transcripts, and reports are organized into year/month subfolders. This keeps folders manageable as volume grows.

• Project/stream tasks: tasks/YYYY/TASK-ID.md
• Standalone tasks: data/tasks/YYYY/TASK-ID.md
• Meeting transcripts: data/meetings/transcripts/YYYY/MM/
• Meeting notes (general): data/meetings/notes/YYYY/MM/
• Meeting notes (area): data/meetings/areas/<area-slug>/notes/YYYY/MM/
• Meeting notes (project): data/projects/<slug>/meetings/YYYY/MM/
• Reports: data/reports/<type>/YYYY/MM/

When creating new files, always place them in the correct subfolder matching the current date. Dashboard scripts use rglob and scan all subfolders automatically.

File Locations

Project Slugs

Use lowercase-kebab-case for all folder names (e.g., project-alpha, backend-api).

Dashboard Scripts

The read-only dashboards are powered by scripts/dashboard.py (Python, stdlib only). This ensures speed, determinism, and no token cost for scanning tasks.

python scripts/dashboard.py today          # Daily dashboard
python scripts/dashboard.py this_week      # Weekly dashboard
python scripts/dashboard.py my_team        # Team workload + days open
python scripts/dashboard.py weekly_report  # Week summary
python scripts/dashboard.py owner <name>   # Projects/streams owned by a person

The slash commands for these dashboards invoke the script and display its output.

Every run automatically saves a snapshot to data/reports/:

Running the same command twice on the same day overwrites the previous snapshot for that date.

Commands

Command prompts live in prompts/commands/. Each file contains the full instructions for one command.

In Claude Code these are wired as slash commands via .claude/commands/. Seven of them — new-task, update, done, process-meeting, archive, status, and new-note — are also exposed as skills under .claude/skills/, so they auto-load when the user describes the action in natural language (e.g., "Ana needs to fix the login bug by Friday" → new-task). Slash commands and skills coexist and share the same source-of-truth prompt files in prompts/commands/. The four dashboards (today, this_week, my_team, weekly_report) and agenda remain slash-only since they're deliberate, explicit invocations.

Commands can be invoked either explicitly (e.g., /owner-report) or by natural language — every agent routes plain-language requests to the right prompt via its own request→prompt table (AGENTS.md, .github/copilot-instructions.md, .cursor/rules/plainpm.mdc, .windsurf/rules/plainpm.md) and the Commands table above. This keeps the behavior agent-agnostic; a single prompts/commands/*.md file is the source of truth for each command. Do not add Claude-only .claude/skills/ entries for these — that would work only in Claude Code and duplicate the prompt.

Multi-Agent Support

This project is configured to work with multiple AI coding agents:

All agent configs point to the same source of truth: CLAUDE.md for conventions, prompts/commands/ for command prompts.