ProjectManager

Project Manager

An AI-native, file-based project management tool designed for developers who want to keep their project planning close to their code.

Overview

Project Manager is built on a simple but powerful philosophy: every epic and story is a JSON file in your repository. This approach gives you:

Features

📁 File-Based Storage

All project data is stored as JSON files in a hierarchical /pm directory:

/pm
  /[project-name]/
    /project.json              # Project metadata
    /[epic-name]/
      /epic.json               # Epic metadata
      /STORY-*.json            # Story files

This hierarchical structure makes it easy to:

🤖 AI-Powered

💼 Project Management

📊 Analytics & Metrics

The application includes a comprehensive analytics dashboard that provides real-time insights:

Key Metrics

Status Distribution

Epic Progress Tracking

Risk Analysis

Additional Metrics

Quick Start

Prerequisites

Installation

  1. Clone the repository 
    git clone <your-repo-url>
cd ProjectManager
  2. Install dependencies 
    npm install
  3. Run the development server 
    npm run dev
  4. Open your browser Navigate to http://localhost:3004

First-Time Setup

The application will create the /pm directory structure on first run with sample data to help you get started.

Usage

Accessing Analytics

From Header Navigation:

  1. Click “Analytics” in the header
  2. Select a project tab to view its metrics

From Project Page:

  1. Open any project
  2. Click the analytics icon (bar chart) next to the project title

The analytics dashboard provides real-time insights including:

Creating a Project

  1. Navigate to the Projects page
  2. Click “New Project”
  3. Fill in project details (name, description)
  4. Save to create /pm/{project-name}/project.json

Creating an Epic

  1. Open a project
  2. Click “New Epic”
  3. Provide epic title and description
  4. Optionally use AI to generate stories from the epic description
  5. Save to create /pm/{project-name}/{epic-name}/epic.json

Creating Stories

Manual Creation:

  1. Open an epic
  2. Click “New Story”
  3. Fill in story details, acceptance criteria, etc.
  4. Save to create /pm/{project-name}/{epic-name}/STORY-{id}.json

AI-Powered Creation:

  1. Open an epic
  2. Click “Generate Stories with AI”
  3. Provide context or let AI analyze the epic description
  4. Review and edit generated stories
  5. Save all stories at once

Editing Stories

  1. Click on any story to open the editor
  2. Edit metadata in the left panel
  3. Edit description and acceptance criteria in the center panel
  4. Changes are saved immediately to the JSON file
  5. Commit changes to Git like any other code change

Architecture

Tech Stack

File Structure

ProjectManager/
├── src/
│   ├── app/                 # Pages and API routes
│   ├── components/          # Reusable UI components
│   ├── lib/                 # Utilities and data layer
│   └── theme/               # Design tokens
├── scripts/                 # Automation scripts
├── pm/                      # Project management data
│   └── [project-name]/      # Hierarchical structure
│       ├── project.json
│       └── [epic-name]/
│           ├── epic.json
│           └── STORY-*.json
└── CLAUDE.md                # AI assistant context

Data Flow

  1. UI components call API routes (/api/projects, /api/epics, /api/stories)
  2. API routes use pmRepository to read/write JSON files
  3. All data validated with Zod schemas
  4. JSON files committed to Git for version control

Development

Available Scripts

# Development
npm run dev              # Start dev server (port 3004)

# Build
npm run build            # Production build
npm run start            # Start production server

# Quality
npm run lint             # Run ESLint
npm run type-check       # TypeScript type checking

# Automation
npm run update-claude    # Update CLAUDE.md files
npm run setup-git-hook   # Setup git hooks for CLAUDE.md

Project Structure

See CLAUDE.md for detailed documentation of the application architecture, including:

AI Integration with Cursor

This project is designed to work seamlessly with Cursor AI:

  1. CLAUDE.md Files: Each directory has a CLAUDE.md file that provides context to AI assistants
  2. Structured Data: JSON files can be read and understood by AI
  3. Type Definitions: TypeScript types help AI generate valid code
  4. Clear Patterns: Consistent patterns make it easy for AI to extend functionality

Example AI Prompts:

Configuration

Environment Variables

Copy env.example to .env.local:

cp env.example .env.local

Currently minimal configuration is needed. Future additions may include:

Customization

Theme Colors: Edit tailwind.config.js Data Location: Modify PM_DATA_DIR in src/lib/pm-repository.ts Status Options: Update project JSON defaultStatuses array Priority Levels: Update project JSON defaultPriorities array

Roadmap

Phase 1: Core Functionality ✅

Phase 2: Enhanced Features ✅

Phase 3: AI Integration

Phase 4: Advanced Features

Contributing

Contributions are welcome! Since this is a file-based system:

  1. Fork the repository
  2. Create your feature branch
  3. Make changes (code + JSON files)
  4. Commit both code and data files
  5. Push and create a Pull Request

License

MIT License - see LICENSE file for details

Support

For questions, issues, or suggestions:

Built with ❤️ for developers who want their project management to live with their code.