# Pm DB

> Project management database for tracking specs, phases, tasks, and execution runs. Use this skill whenever the user asks about project status, wants to track feature work, needs a dashboard of progress, wants to import specs from /spec-plan, or mentions tracking tasks, phases, or runs. Also use when the user says things like 'what's the status', 'how's the project going', 'track this work', 'show me progress', or 'import my specs'.

- Skill: `artsmc-claude-dev-agents/pm-db` (Agent Skill, multi-file: 28 files)
- Install (CLI): `npx skillmds@latest add artsmc-claude-dev-agents/pm-db`
- Raw SKILL.md: https://api.skillmd.com/api/skills/artsmc-claude-dev-agents/pm-db/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: artsmc (https://skillmd.com/u/artsmc-claude-dev-agents)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/artsmc-claude-dev-agents/pm-db

---


# PM-DB: Project Management Database

SQLite-based tracking for the full development lifecycle: specs → phases → tasks → runs.

## Core Concepts

PM-DB tracks work in a hierarchy:

```
Project (e.g., "acme")
  └─ Phase (e.g., "file-upload-feature")
       └─ Plan (approved task breakdown)
            └─ Tasks (atomic work items with waves/dependencies)
                 └─ Runs (execution attempts with timing/status)
```

**Why this matters:** When a user asks "what's the status?", you query projects → phases → tasks. When they say "track this feature", you create a phase with a plan and tasks.

## Commands & Import Walkthrough

Full command invocations (init, import, dashboard, migrate, export) and the step-by-step import walkthroughs (including manual Python-API import) live in `references/commands.md` — read it before running any pm-db script or importing specs.

## Cross-Skill Integration

PM-DB connects to other skills in the workflow:

```
/spec-plan → generates specs in job-queue/
     ↓
/pm-db import → imports specs into projects/phases
     ↓
/start-phase-plan → creates execution plan with tasks
     ↓
/pm-db tracks → phases, runs, task completions
     ↓
/pm-db dashboard → shows progress
```

**Key paths:**
- Spec-plan output: `/home/artsmc/applications/acme/job-queue/feature-*/docs/`
- PM-DB database: `~/.claude/projects.db`
- Python API: `~/.claude/lib/project_database.py`

## Python API (Quick Reference)

```python
from project_database import ProjectDatabase

with ProjectDatabase() as db:
    # Projects
    projects = db.list_projects()
    project = db.get_project_by_name("acme")

    # Phases
    phases = db.list_phases(project_id=1)
    phase = db.get_phase(phase_id=1)

    # Plans and tasks
    plans = db.list_phase_plans(phase_id=1)
    tasks = db.list_tasks(plan_id=1)

    # Runs
    run_id = db.create_phase_run(phase_id=1, plan_id=1)
    db.start_phase_run(run_id)
    db.complete_phase_run(run_id, status='completed')

    # Dashboard
    dashboard = db.generate_phase_dashboard(phase_id=1)
    metrics = db.get_phase_metrics(phase_id=1)
```

For the complete API, read `~/.claude/lib/project_database.py`.

## Database Schema (v5)

Core tables: `projects`, `phases`, `phase_plans`, `plan_documents`, `tasks`, `task_dependencies`, `phase_runs`, `task_runs`

Tracking tables: `task_updates`, `quality_gates`, `code_reviews`, `run_artifacts`, `phase_metrics`

Advanced: `agent_context_cache`, `agent_invocations`, `agent_file_reads`, `checklists`, `checklist_items`

## Troubleshooting

**"Database not found"** → Run `python3 ~/.claude/skills/pm-db/scripts/init_db.py`

**"No projects found"** → Run import: `python3 ~/.claude/skills/pm-db/scripts/import_specs.py --auto-confirm`

**"Import found nothing"** → Check the job-queue path. Default is `~/.claude/job-queue/`. For the monorepo, add `--job-queue-dir /home/artsmc/applications/acme/job-queue`

**"Which import script?"** → `import_specs.py` for spec files, `import_phases.py` for structured phases

**"Database locked"** → Check `lsof ~/.claude/projects.db`. WAL mode is enabled by default.

---

**Database:** `~/.claude/projects.db`
**API:** `~/.claude/lib/project_database.py`
**Version:** 2.0