project-roadmap-tracking

v0.2.7

Published

4 days ago

CLI based project task tracking

0High
0Medium
0Low

zacharyeggert

oclif cli project roadmap tracking tasks productivity management prt

project-roadmap-tracking

A modern, production-ready CLI tool for managing project tasks and roadmaps with advanced features like dependency tracking, validation, and comprehensive test coverage.

Features

📝 Task Management: Create, update, and track bugs, features, improvements, planning tasks, and research items
🔗 Dependency Tracking: Define task dependencies and detect circular dependencies
🎯 Priority & Status: Organize tasks by priority (high/medium/low) and status (not-started/in-progress/completed)
✅ Test Tracking: Mark tasks as passing tests to maintain quality
🔍 Powerful Filtering: Filter and sort tasks by multiple criteria
📊 Validation: Comprehensive roadmap validation with detailed error reporting
⚡ Performance: LRU caching and file watching for optimal performance
🏗️ Modern Architecture: Service layer, repository pattern, and 96.81% test coverage
📦 Configuration: Multi-level config inheritance (project → user → global)
🔄 Backward Compatible: Legacy mode via --no-repo flag

Quick Start

Installation

npm install -g project-roadmap-tracking

Initialize a Project

# Initialize with sample tasks
prt init --name "My Project" --withSampleTasks

# Or create an empty roadmap
prt init --name "My Project"

Basic Usage

# Add a new feature
prt add "User authentication" -t feature -d "Implement JWT auth" -p high

# List all high-priority tasks
prt list -p high

# Show task details
prt show F-001

# Show task details with dependencies
prt show F-001 -d

# Update task status
prt update F-001 --status=in-progress

# Complete a task
prt complete F-001 --tests

# Validate roadmap integrity
prt validate

Architecture

PRT follows a modern layered architecture:

CLI Layer: Thin command handlers using oclif
Service Layer: Business logic (TaskService, RoadmapService, etc.)
Repository Layer: Data access with caching and file watching
Error Handling: Custom error hierarchy with error codes

For detailed architecture documentation, see ARCHITECTURE.md.

Data Format

PRT uses two JSON files to manage your project:

`.prtrc.json` (Configuration)

Project configuration with optional caching settings:

{
  "$schema": "https://raw.githubusercontent.com/ZacharyEggert/project-roadmap-tracking/master/schemas/config/v1.1.json",
  "name": "My Project",
  "description": "Project description",
  "path": "./prt.json",
  "cache": {
    "enabled": true,
    "maxSize": 10
  }
}

`prt.json` (Roadmap)

Your tasks and project data:

{
  "$schema": "https://raw.githubusercontent.com/ZacharyEggert/project-roadmap-tracking/master/schemas/roadmap/v1.json",
  "metadata": {
    "name": "My Project",
    "createdAt": "2026-01-22T10:00:00.000Z"
  },
  "tasks": [
    {
      "id": "F-001",
      "title": "User authentication",
      "type": "feature",
      "status": "in-progress",
      "priority": "high",
      "details": "Implement JWT authentication",
      "tags": ["auth", "security"],
      "depends-on": [],
      "blocks": [],
      "passes-tests": false,
      "createdAt": "2026-01-22T10:00:00.000Z",
      "updatedAt": "2026-01-22T10:00:00.000Z"
    }
  ]
}

Task ID Format

Task IDs follow the pattern {TYPE}-{NUMBER}:

B-001: Bug
F-001: Feature
I-001: Improvement
P-001: Planning
R-001: Research

IDs are auto-generated sequentially per task type.

Usage

$ npm install -g project-roadmap-tracking
$ prt COMMAND
running command...
$ prt (--version)
project-roadmap-tracking/0.2.7 linux-x64 node-v25.4.0
$ prt --help [COMMAND]
USAGE
  $ prt COMMAND
...

Commands

`prt add TITLE`

add a new task to the roadmap

USAGE
  $ prt add TITLE -d <value> -t bug|feature|improvement|planning|research [--no-repo] [-p
    high|medium|low] [-s not-started|in-progress|completed] [-g <value>] [-v]

ARGUMENTS
  TITLE  title of the task to add

FLAGS
  -d, --details=<value>    (required) description of the task to add
  -g, --tags=<value>       comma-separated list of tags to add to the task
  -p, --priority=<option>  [default: medium] priority of the task to add
                           <options: high|medium|low>
  -s, --status=<option>    [default: not-started] status of the task to add
                           <options: not-started|in-progress|completed>
  -t, --type=<option>      (required) type of the task to add
                           <options: bug|feature|improvement|planning|research>
  -v, --verbose            show detailed error information including stack traces
      --no-repo            use legacy direct file I/O instead of repository pattern

DESCRIPTION
  add a new task to the roadmap

EXAMPLES
  $ prt add

See code: src/commands/add.ts

`prt complete TASKID`

Mark a task as completed

USAGE
  $ prt complete TASKID [--no-repo] [-t] [-v]

ARGUMENTS
  TASKID  ID of the task to complete

FLAGS
  -t, --tests    mark task as passes-tests
  -v, --verbose  show detailed error information including stack traces
      --no-repo  use legacy direct file I/O instead of repository pattern

DESCRIPTION
  Mark a task as completed

EXAMPLES
  $ prt complete F-001 --tests

See code: src/commands/complete.ts

`prt help [COMMAND]`

Display help for prt.

USAGE
  $ prt help [COMMAND...] [-n]

ARGUMENTS
  [COMMAND...]  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for prt.

See code: @oclif/plugin-help

`prt init [FOLDER]`

initialize a new project roadmap (prt.json and prt.config.json)

USAGE
  $ prt init [FOLDER] [-d <value>] [-f] [-n <value>] [-v] [--withSampleTasks]

ARGUMENTS
  [FOLDER]  folder to initialize the project roadmap in

FLAGS
  -d, --description=<value>  description to print
  -f, --force                force initialization even if files already exist
  -n, --name=<value>         name to print
  -v, --verbose              show detailed error information including stack traces
      --withSampleTasks      include sample tasks in the initialized roadmap

DESCRIPTION
  initialize a new project roadmap (prt.json and prt.config.json)

EXAMPLES
  $ prt init [path/to/directory]

See code: src/commands/init.ts

`prt list`

list tasks in the project roadmap

USAGE
  $ prt list [-i] [--no-repo] [-p high|medium|low|h|m|l] [-o dueDate|priority|createdAt] [-s
    completed|in-progress|not-started] [-v]

FLAGS
  -i, --incomplete         filter tasks to show in-progress and not-started only
  -o, --sort=<option>      sort tasks by field (dueDate, priority, createdAt)
                           <options: dueDate|priority|createdAt>
  -p, --priority=<option>  filter tasks by priority (high, medium, low)
                           <options: high|medium|low|h|m|l>
  -s, --status=<option>    filter tasks by status (completed, in-progress, not-started)
                           <options: completed|in-progress|not-started>
  -v, --verbose            show detailed error information including stack traces
      --no-repo            use legacy direct file I/O instead of repository pattern

DESCRIPTION
  list tasks in the project roadmap

EXAMPLES
  $ prt list -p=h --incomplete --sort=createdAt

See code: src/commands/list.ts

`prt pass-test TASKID`

Mark a task as passes-tests

USAGE
  $ prt pass-test TASKID [--no-repo] [-v]

ARGUMENTS
  TASKID  ID of the task to mark as passing tests

FLAGS
  -v, --verbose  show detailed error information including stack traces
      --no-repo  use legacy direct file I/O instead of repository pattern

DESCRIPTION
  Mark a task as passes-tests

EXAMPLES
  $ prt pass-test F-001

See code: src/commands/pass-test.ts

`prt plugins`

List installed plugins.

USAGE
  $ prt plugins [--json] [--core]

FLAGS
  --core  Show core plugins.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  List installed plugins.

EXAMPLES
  $ prt plugins

See code: @oclif/plugin-plugins

`prt plugins add PLUGIN`

Installs a plugin into prt.

USAGE
  $ prt plugins add PLUGIN... [--json] [-f] [-h] [-s | -v]

ARGUMENTS
  PLUGIN...  Plugin to install.

FLAGS
  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
  -h, --help     Show CLI help.
  -s, --silent   Silences npm output.
  -v, --verbose  Show verbose npm output.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Installs a plugin into prt.

  Uses npm to install plugins.

  Installation of a user-installed plugin will override a core plugin.

  Use the PRT_NPM_LOG_LEVEL environment variable to set the npm loglevel.
  Use the PRT_NPM_REGISTRY environment variable to set the npm registry.

ALIASES
  $ prt plugins add

EXAMPLES
  Install a plugin from npm registry.

    $ prt plugins add myplugin

  Install a plugin from a github url.

    $ prt plugins add https://github.com/someuser/someplugin

  Install a plugin from a github slug.

    $ prt plugins add someuser/someplugin

`prt plugins:inspect PLUGIN...`

Displays installation properties of a plugin.

USAGE
  $ prt plugins inspect PLUGIN...

ARGUMENTS
  PLUGIN...  [default: .] Plugin to inspect.

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Displays installation properties of a plugin.

EXAMPLES
  $ prt plugins inspect myplugin

See code: @oclif/plugin-plugins

`prt plugins install PLUGIN`

Installs a plugin into prt.

USAGE
  $ prt plugins install PLUGIN... [--json] [-f] [-h] [-s | -v]

ARGUMENTS
  PLUGIN...  Plugin to install.

FLAGS
  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
  -h, --help     Show CLI help.
  -s, --silent   Silences npm output.
  -v, --verbose  Show verbose npm output.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Installs a plugin into prt.

  Uses npm to install plugins.

  Installation of a user-installed plugin will override a core plugin.

  Use the PRT_NPM_LOG_LEVEL environment variable to set the npm loglevel.
  Use the PRT_NPM_REGISTRY environment variable to set the npm registry.

ALIASES
  $ prt plugins add

EXAMPLES
  Install a plugin from npm registry.

    $ prt plugins install myplugin

  Install a plugin from a github url.

    $ prt plugins install https://github.com/someuser/someplugin

  Install a plugin from a github slug.

    $ prt plugins install someuser/someplugin

See code: @oclif/plugin-plugins

`prt plugins link PATH`

Links a plugin into the CLI for development.

USAGE
  $ prt plugins link PATH [-h] [--install] [-v]

ARGUMENTS
  PATH  [default: .] path to plugin

FLAGS
  -h, --help          Show CLI help.
  -v, --verbose
      --[no-]install  Install dependencies after linking the plugin.

DESCRIPTION
  Links a plugin into the CLI for development.

  Installation of a linked plugin will override a user-installed or core plugin.

  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
  command will override the user-installed or core plugin implementation. This is useful for development work.


EXAMPLES
  $ prt plugins link myplugin

See code: @oclif/plugin-plugins

`prt plugins remove [PLUGIN]`

Removes a plugin from the CLI.

USAGE
  $ prt plugins remove [PLUGIN...] [-h] [-v]

ARGUMENTS
  [PLUGIN...]  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ prt plugins unlink
  $ prt plugins remove

EXAMPLES
  $ prt plugins remove myplugin

`prt plugins reset`

Remove all user-installed and linked plugins.

USAGE
  $ prt plugins reset [--hard] [--reinstall]

FLAGS
  --hard       Delete node_modules and package manager related files in addition to uninstalling plugins.
  --reinstall  Reinstall all plugins after uninstalling.

See code: @oclif/plugin-plugins

`prt plugins uninstall [PLUGIN]`

Removes a plugin from the CLI.

USAGE
  $ prt plugins uninstall [PLUGIN...] [-h] [-v]

ARGUMENTS
  [PLUGIN...]  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ prt plugins unlink
  $ prt plugins remove

EXAMPLES
  $ prt plugins uninstall myplugin

See code: @oclif/plugin-plugins

`prt plugins unlink [PLUGIN]`

Removes a plugin from the CLI.

USAGE
  $ prt plugins unlink [PLUGIN...] [-h] [-v]

ARGUMENTS
  [PLUGIN...]  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ prt plugins unlink
  $ prt plugins remove

EXAMPLES
  $ prt plugins unlink myplugin

`prt plugins update`

Update installed plugins.

USAGE
  $ prt plugins update [-h] [-v]

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Update installed plugins.

See code: @oclif/plugin-plugins

`prt show TASK`

show details of a specific task in the project roadmap

USAGE
  $ prt show TASK [--no-repo] [-d] [-v]

ARGUMENTS
  TASK  task ID to show

FLAGS
  -d, --show-dependencies  show task dependencies
  -v, --verbose            show detailed error information including stack traces
      --no-repo            use legacy direct file I/O instead of repository pattern

DESCRIPTION
  show details of a specific task in the project roadmap

EXAMPLES
  $ prt show F-001

See code: src/commands/show.ts

`prt update TASKID`

Update a task in place

USAGE
  $ prt update TASKID [--clear-notes] [-d <value>] [--no-repo] [-n <value>] [-s
    completed|in-progress|not-started] [-t true|false] [--type bug|feature|improvement|planning|research] [-v]

ARGUMENTS
  TASKID  ID of the task to update

FLAGS
  -d, --deps=<value>     update the dependencies of the task (comma-separated list of task IDs)
  -n, --notes=<value>    append notes to the task
  -s, --status=<option>  set the status of the task (completed, in-progress, not-started)
                         <options: completed|in-progress|not-started>
  -t, --tested=<option>  update whether the task passes tests
                         <options: true|false>
  -v, --verbose          show detailed error information including stack traces
      --clear-notes      clear all notes from the task
      --no-repo          use legacy direct file I/O instead of repository pattern
      --type=<option>    update the task type (reassigns task ID and cascades to all references)
                         <options: bug|feature|improvement|planning|research>

DESCRIPTION
  Update a task in place

EXAMPLES
  $ prt update F-001 --status=completed --tested=true --notes="Fixed all bugs"

  $ prt update F-002 --deps="F-001" --clear-notes

See code: src/commands/update.ts

`prt validate`

Validate roadmap structure, task data, and check for circular dependencies

USAGE
  $ prt validate [--no-repo] [-v]

FLAGS
  -v, --verbose  show detailed error information including stack traces
      --no-repo  use legacy direct file I/O instead of repository pattern

DESCRIPTION
  Validate roadmap structure, task data, and check for circular dependencies

EXAMPLES
  $ prt validate

See code: src/commands/validate.ts

Development

Setup

# Clone the repository
git clone https://github.com/ZacharyEggert/project-roadmap-tracking.git
cd project-roadmap-tracking

# Install dependencies
yarn install

# Build the project
yarn build

Development Commands

# Run tests
yarn test

# Run tests with coverage
yarn test:coverage:summary

# Run linter
yarn lint

# Auto-fix linting issues
yarn lint:fix

# Format code
yarn format

# Run CLI locally without installing
./bin/dev.js COMMAND

# Link for global development testing
yarn link
prt COMMAND

Testing

PRT has comprehensive test coverage (96.81%):

Unit tests: Services, repositories, utilities, errors
Command tests: All CLI commands
Test runner: Mocha + Chai
Coverage: c8

# Run all tests
yarn test

# Run a specific test file
yarn mocha --loader=tsx/esm "test/path/to/file.test.ts"

# Generate coverage report
yarn test:coverage

# View coverage summary
yarn test:coverage:summary

Architecture

For detailed architecture documentation, including design patterns, service layer architecture, repository pattern, and migration path, see ARCHITECTURE.md.

Key architectural features:

✓ Service layer for business logic (97.43% coverage)
✓ Repository pattern with caching and file watching (94.7% coverage)
✓ Custom error hierarchy with error codes (100% coverage)
✓ Comprehensive test suite (96.81% overall coverage)
✓ Backward compatible legacy mode

Contributing

See CONTRIBUTING.md for contribution guidelines.

Release Process

PRT uses a fully automated CI/CD pipeline powered by GitHub Actions. Releases are created automatically when code is pushed to the master branch.

Automated Release (Standard Process)

Update version in package.json:

# Example: 0.2.6 → 0.2.7
npm version patch  # or minor, or major

Commit and push to master:

git add package.json
git commit -m "chore: bump version to 0.2.7"
git push origin master

GitHub Actions automatically:
- ✅ Runs test suite (944 tests must pass)
- ✅ Validates build and linting
- ✅ Creates GitHub release (only if tests pass)
- ✅ Publishes to npm registry
- ⏱️ Total time: ~4-6 minutes

Quality Gate: If tests fail, no release is created. Fix the issues and push again.

Manual Release (Fallback)

For emergency releases or when automation is unavailable:

# 1. Update version
npm version patch

# 2. Build and package
yarn prepack  # generates manifest, updates README
yarn pack     # creates tarball

# 3. Publish to npm
npm publish

# 4. Create GitHub release
gh release create v$(node -p "require('./package.json').version") --generate-notes

Required GitHub Secrets

For automated releases, configure these secrets in your GitHub repository:

| Secret | Purpose | |--------|---------| | GH_TOKEN | GitHub API access (repo + workflow scopes) | | GH_EMAIL | Git commit author email | | GH_USERNAME | Git commit author name | | NPM_TOKEN | npm authentication (optional with Trusted Publishing) |

npm Authentication

Option A: Trusted Publishing (Recommended)

More secure (OIDC-based, no long-lived tokens)
Configure at: https://www.npmjs.com/settings/project-roadmap-tracking/packages/project-roadmap-tracking/access
No NPM_TOKEN secret needed

Option B: Granular Access Token

Generate at: https://www.npmjs.com/settings/~/tokens
Permissions: Read and write for project-roadmap-tracking package
Store as NPM_TOKEN GitHub secret

CI/CD Workflows

The project uses three GitHub Actions workflows:

test.yml - Runs on feature branches
- Tests across Ubuntu/Windows
- Tests across Node LTS versions
- Fast feedback during development
onPushToMaster.yml - Runs on master push
- Test job (build + tests + lint) ← Quality gate
- Release job (create GitHub release) ← Only runs if tests pass
onRelease.yml - Runs when release created
- Builds package
- Publishes to npm with provenance

For detailed CI/CD architecture, see ARCHITECTURE.md - CI/CD Pipeline

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

project-roadmap-tracking

Features

Quick Start

Installation

Initialize a Project

Basic Usage

Architecture

Data Format

.prtrc.json (Configuration)

prt.json (Roadmap)

Task ID Format

Usage

Commands

prt add TITLE

prt complete TASKID

prt help [COMMAND]

prt init [FOLDER]

prt list

prt pass-test TASKID

prt plugins

prt plugins add PLUGIN

prt plugins:inspect PLUGIN...

prt plugins install PLUGIN

prt plugins link PATH

prt plugins remove [PLUGIN]

prt plugins reset

prt plugins uninstall [PLUGIN]

prt plugins unlink [PLUGIN]

prt plugins update

prt show TASK

prt update TASKID

prt validate

Development

Setup

Development Commands

Testing

Architecture

Contributing

Release Process

Automated Release (Standard Process)

Manual Release (Fallback)

Required GitHub Secrets

npm Authentication

CI/CD Workflows

License

Links

`.prtrc.json` (Configuration)

`prt.json` (Roadmap)

`prt add TITLE`

`prt complete TASKID`

`prt help [COMMAND]`

`prt init [FOLDER]`

`prt list`

`prt pass-test TASKID`

`prt plugins`

`prt plugins add PLUGIN`

`prt plugins:inspect PLUGIN...`

`prt plugins install PLUGIN`

`prt plugins link PATH`

`prt plugins remove [PLUGIN]`

`prt plugins reset`

`prt plugins uninstall [PLUGIN]`

`prt plugins unlink [PLUGIN]`

`prt plugins update`

`prt show TASK`

`prt update TASKID`

`prt validate`