prd-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nimrod Margalit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# Product OS Framework
+
+An AI-native product development lifecycle for [Cursor](https://cursor.com). From idea to production with quality gates, slash commands, and real-time visibility.
+
+## What It Does
+
+Product OS gives your team a structured workflow for building features:
+
+```
+PM creates & verifies PRD → Dev builds & tests → Team releases & documents
+```
+
+**Four slash commands in Cursor:**
+
+| Command | Owner | What Happens |
+|---------|-------|--------------|
+| `/create` | PM | Define → Verify → Extract Features → PRD approved |
+| `/verify` | PM | Quality check any PRD |
+| `/dev` | Developer | Kickoff → Code → Test → PR ready |
+| `/release` | Team | Review → Merge → Deploy → Document |
+
+**Plus a CLI dashboard:**
+
+```
+$ prd
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📊 PRODUCT STORIES DASHBOARD
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Summary:
+  Total Stories:     5
+  Average Progress:  30%
+  Blocked:           0
+
+delivery-api (4 stories)
+  US-001  ✅ Done  P0
+    Real-time order tracking
+    ████████████ 100%
+
+  US-002  🔨 In Dev  P1
+    Restaurant menu management
+    ██████░░░░░░ 50%
+```
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g prd-cli
+```
+
+### 2. Create Your Workspace
+
+```bash
+prd init
+```
+
+Answer the prompts:
+- Workspace name (e.g., `product-docs`)
+- First project name (e.g., `my-app`)
+- Path to dev repo (optional)
+
+This creates your product docs folder, templates, and a `.code-workspace` file.
+
+### 3. Open in Cursor
+
+```bash
+cursor your-workspace.code-workspace
+```
+
+Both your product docs and dev repo are connected automatically.
+
+### 4. Create Your First Story
+
+In Cursor chat:
+```
+/create "User authentication with OAuth" @my-app/backlog.md
+```
+
+The AI agent walks you through defining requirements, verifying quality, and extracting features.
+
+### 5. View Dashboard
+
+```bash
+prd
+```
+
+## How It Works
+
+### For Product Managers
+
+1. **`/create`** - Interactive PRD creation with AI-powered refinement
+2. **`/verify`** - Automated quality checks for your PRD
+3. **`prd dashboard`** - See all stories across all projects
+
+### For Developers
+
+1. **`/dev US-001`** - AI reads the PRD + RULES.md, generates tasks, builds iteratively
+2. **`/release US-001`** - Merge, deploy, document
+
+### Workspace Structure
+
+```
+your-product-docs/
+├── .prd.config.json          # Workspace config
+├── PROCESS.md                # The methodology
+├── README.md                 # Project registry
+└── my-app/                   # Project folder
+    ├── backlog.md            # Story tracking
+    ├── RULES.md              # Technical standards
+    ├── US-001.md             # Story files
+    └── US-002.md
+```
+
+Each project folder contains stories (`US-*.md`) with YAML frontmatter that powers the dashboard and slash commands.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `prd init` | Create a new product workspace |
+| `prd add-project` | Add another project |
+| `prd` or `prd dashboard` | Full stories dashboard |
+| `prd list` | Compact list view |
+| `prd stats` | Quick statistics |
+| `prd dashboard --status done` | Filter by status |
+| `prd dashboard --phase dev` | Filter by phase |
+
+## Key Concepts
+
+### Quality Gates
+Every PRD goes through automated verification before development starts. Gaps are identified and suggested fixes offered.
+
+### RULES.md
+Each project has a `RULES.md` defining technical standards (tech stack, patterns, testing). AI agents read this during `/dev` to ensure consistent implementation.
+
+### YAML Frontmatter
+Stories include metadata that powers the dashboard:
+
+```yaml
+---
+id: US-001
+project: my-app
+status: dev
+phase: development
+progress: 50
+priority: P0
+---
+```
+
+### Global Story IDs
+Stories use globally unique IDs (`US-001`, `US-002`, ...) across all projects. No conflicts, easy cross-referencing.
+
+## Built For
+
+- **Cursor IDE** - Slash commands powered by AI agents
+- **Small teams** - PMs + Developers working together
+- **Multiple projects** - One workspace, many products
+- **AI-native development** - Quality gates designed for LLM-assisted workflows
+
+## Industry Alignment
+
+| Product OS | Maps To |
+|------------|---------|
+| `/create` + `/verify` | **Dual-Track Agile** Discovery / **Shape Up** Shaping |
+| `/dev` | **Dual-Track Agile** Delivery / **Shape Up** Building |
+| `/release` | **Lean** Measure / **Shape Up** Shipping |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+**Product OS Framework** - Built by [Nimrod Margalit](https://github.com/nimidev)

package/bin/prd.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * Product OS Framework CLI
+ * AI-native product development lifecycle for Cursor
+ */
+
+const { Command } = require('commander');
+const path = require('path');
+const { findWorkspaceRoot, loadConfig } = require('../lib/config');
+const { dashboard } = require('../lib/commands/dashboard');
+
+const program = new Command();
+
+program
+  .name('prd')
+  .description('Product OS Framework - AI-native product development lifecycle for Cursor')
+  .version('1.0.0');
+
+// --- prd init ---
+program
+  .command('init')
+  .description('Create a new product workspace')
+  .action(async () => {
+    const { init } = require('../lib/commands/init');
+    await init();
+  });
+
+// --- prd add-project ---
+program
+  .command('add-project')
+  .description('Add a new project to the workspace')
+  .action(async () => {
+    const { addProject } = require('../lib/commands/add-project');
+    await addProject();
+  });
+
+// --- prd dashboard ---
+program
+  .command('dashboard')
+  .description('Display product stories dashboard')
+  .option('-p, --path <path>', 'Path to product-docs workspace')
+  .option('-s, --status <status>', 'Filter by status (backlog, dev, done, etc.)')
+  .option('--phase <phase>', 'Filter by phase (create, dev, release)')
+  .option('-c, --compact', 'Compact output')
+  .action((options) => {
+    const docsPath = resolveDocsPath(options.path);
+    dashboard(docsPath, options);
+  });
+
+// --- prd list ---
+program
+  .command('list')
+  .description('List all stories (compact view)')
+  .option('-p, --path <path>', 'Path to product-docs workspace')
+  .action((options) => {
+    const docsPath = resolveDocsPath(options.path);
+    dashboard(docsPath, { ...options, compact: true });
+  });
+
+// --- prd stats ---
+program
+  .command('stats')
+  .description('Show statistics summary')
+  .option('-p, --path <path>', 'Path to product-docs workspace')
+  .action((options) => {
+    const chalk = require('chalk');
+    const { scanAllStories, getStats } = require('../lib/parser');
+
+    const docsPath = resolveDocsPath(options.path);
+    try {
+      const data = scanAllStories(docsPath);
+      const stats = getStats(data.stories);
+
+      console.log('\n' + chalk.bold.cyan('📊 Statistics'));
+      console.log(chalk.gray('─'.repeat(40)));
+      console.log(`Total:      ${chalk.green.bold(stats.total)}`);
+      console.log(`Progress:   ${chalk.yellow.bold(stats.avgProgress + '%')}`);
+      console.log(`Blocked:    ${stats.blocked > 0 ? chalk.red.bold(stats.blocked) : chalk.gray('0')}`);
+      console.log('');
+    } catch (err) {
+      console.error(chalk.red('Error:'), err.message);
+      process.exit(1);
+    }
+  });
+
+// --- Default: show dashboard if no command given ---
+if (process.argv.length === 2) {
+  const docsPath = resolveDocsPath();
+  if (docsPath) {
+    dashboard(docsPath);
+  } else {
+    const chalk = require('chalk');
+    console.log('\n' + chalk.bold.cyan('Product OS Framework'));
+    console.log(chalk.gray('─'.repeat(40)));
+    console.log(chalk.white('No product workspace found.\n'));
+    console.log(chalk.white('Get started:'));
+    console.log(chalk.cyan('  prd init') + chalk.gray('           Create a new workspace'));
+    console.log(chalk.cyan('  prd dashboard') + chalk.gray('      View stories dashboard'));
+    console.log(chalk.cyan('  prd --help') + chalk.gray('         See all commands\n'));
+  }
+} else {
+  program.parse();
+}
+
+/**
+ * Resolve the product-docs workspace path
+ * Priority: explicit --path > auto-detect via config > cwd
+ */
+function resolveDocsPath(explicitPath) {
+  if (explicitPath) return path.resolve(explicitPath);
+
+  const root = findWorkspaceRoot(process.cwd());
+  if (root) return root;
+
+  // Fallback: current directory
+  return process.cwd();
+}

package/lib/commands/add-project.js

@@ -0,0 +1,163 @@
+/**
+ * prd add-project - Add a new project to the workspace
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const { loadConfig, saveConfig, CONFIG_FILENAME } = require('../config');
+
+/**
+ * Update .code-workspace file to include new project's dev repo
+ */
+function updateWorkspaceFile(workspaceRoot, projects) {
+  // Find .code-workspace files in parent directory
+  const parentDir = path.dirname(workspaceRoot);
+  const wsFiles = fs.readdirSync(parentDir).filter(f => f.endsWith('.code-workspace'));
+
+  for (const wsFile of wsFiles) {
+    const wsPath = path.join(parentDir, wsFile);
+    try {
+      const ws = JSON.parse(fs.readFileSync(wsPath, 'utf-8'));
+
+      // Add any new project repos that aren't already in the workspace
+      for (const [name, proj] of Object.entries(projects)) {
+        if (!proj.repoPath) continue;
+        const relPath = path.relative(parentDir, proj.repoPath);
+        const alreadyIncluded = ws.folders.some(f => f.path === relPath || f.name === name);
+        if (!alreadyIncluded) {
+          ws.folders.push({ name, path: relPath });
+        }
+      }
+
+      fs.writeFileSync(wsPath, JSON.stringify(ws, null, 2) + '\n', 'utf-8');
+      return wsPath;
+    } catch (err) {
+      // Skip malformed workspace files
+    }
+  }
+  return null;
+}
+
+/**
+ * Main add-project command
+ */
+async function addProject(options = {}) {
+  const config = loadConfig();
+  if (!config) {
+    console.log(chalk.red('\nNo Product OS workspace found.'));
+    console.log(chalk.gray(`Run ${chalk.cyan('prd init')} to create one.\n`));
+    return;
+  }
+
+  const workspaceRoot = config._root;
+  const templatesDir = path.join(__dirname, '..', '..', 'templates');
+
+  console.log(chalk.gray('\nAdding a new project to your workspace.\n'));
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Project name:',
+      validate: (v) => {
+        if (!v.trim()) return 'Project name is required';
+        if (/[^a-zA-Z0-9_-]/.test(v.trim())) return 'Use only letters, numbers, hyphens, underscores';
+        if (config.projects[v.trim()]) return 'Project already exists';
+        return true;
+      }
+    },
+    {
+      type: 'input',
+      name: 'description',
+      message: 'Project description (optional):',
+      default: ''
+    },
+    {
+      type: 'confirm',
+      name: 'hasRepo',
+      message: 'Do you have an existing dev repo for this project?',
+      default: false
+    },
+    {
+      type: 'input',
+      name: 'repoPath',
+      message: 'Path to the dev repo:',
+      when: (a) => a.hasRepo,
+      validate: (v) => {
+        const resolved = path.resolve(v);
+        if (!fs.existsSync(resolved)) return `Path not found: ${resolved}`;
+        return true;
+      }
+    }
+  ]);
+
+  const projName = answers.projectName.trim();
+  const projDesc = answers.description.trim();
+  const repoPath = answers.repoPath ? path.resolve(answers.repoPath) : null;
+
+  // Create project directory
+  const projDir = path.join(workspaceRoot, projName);
+  fs.mkdirSync(projDir, { recursive: true });
+
+  // Create backlog
+  const backlogTmpl = path.join(templatesDir, 'backlog.md.tmpl');
+  if (fs.existsSync(backlogTmpl)) {
+    let content = fs.readFileSync(backlogTmpl, 'utf-8');
+    content = content.replace(/\{\{projectName\}\}/g, projName);
+    fs.writeFileSync(path.join(projDir, 'backlog.md'), content, 'utf-8');
+  } else {
+    fs.writeFileSync(path.join(projDir, 'backlog.md'),
+      `# ${projName} - Backlog\n\n| ID | Title | Status | Priority |\n|----|-------|--------|----------|\n`, 'utf-8');
+  }
+  console.log(chalk.green('  ✅ Created ') + chalk.white(`${projName}/backlog.md`));
+
+  // Create RULES.md
+  const rulesTmpl = path.join(templatesDir, 'RULES.md.tmpl');
+  if (fs.existsSync(rulesTmpl)) {
+    let content = fs.readFileSync(rulesTmpl, 'utf-8');
+    content = content.replace(/\{\{projectName\}\}/g, projName);
+    fs.writeFileSync(path.join(projDir, 'RULES.md'), content, 'utf-8');
+  } else {
+    fs.writeFileSync(path.join(projDir, 'RULES.md'),
+      `# ${projName} - Technical Standards\n\nDocument your project's tech stack, patterns, and conventions here.\n`, 'utf-8');
+  }
+  console.log(chalk.green('  ✅ Created ') + chalk.white(`${projName}/RULES.md`));
+
+  // Update config
+  config.projects[projName] = {
+    description: projDesc,
+    repoPath
+  };
+  saveConfig(config);
+  console.log(chalk.green('  ✅ Updated ') + chalk.white(CONFIG_FILENAME));
+
+  // Update README project table
+  const readmePath = path.join(workspaceRoot, 'README.md');
+  if (fs.existsSync(readmePath)) {
+    let readme = fs.readFileSync(readmePath, 'utf-8');
+    const tableRow = `| [${projName}](./${projName}/) | ${projDesc || ''} |`;
+    // Insert before the empty line after the last table row
+    readme = readme.replace(
+      /(## Projects\n\n\|[^\n]+\n\|[^\n]+\n)([\s\S]*?)(\n\n)/,
+      (match, header, rows, gap) => `${header}${rows}\n${tableRow}${gap}`
+    );
+    fs.writeFileSync(readmePath, readme, 'utf-8');
+    console.log(chalk.green('  ✅ Updated ') + chalk.white('README.md'));
+  }
+
+  // Update workspace file
+  if (repoPath) {
+    const wsFile = updateWorkspaceFile(workspaceRoot, config.projects);
+    if (wsFile) {
+      console.log(chalk.green('  ✅ Updated ') + chalk.white(path.basename(wsFile)));
+    }
+  }
+
+  console.log('\n' + chalk.bold.green(`🎉 Project "${projName}" added!\n`));
+  console.log(chalk.white('Create stories in Cursor:'));
+  console.log(chalk.cyan(`  /create "feature" @${projName}/backlog.md\n`));
+}
+
+module.exports = { addProject };

package/lib/commands/dashboard.js

@@ -0,0 +1,173 @@
+/**
+ * Dashboard command - Rich terminal output
+ */
+
+const chalk = require('chalk');
+const { scanAllStories, getStats } = require('../parser');
+
+const STATUS_CONFIG = {
+  backlog: { icon: '📋', color: 'gray', label: 'Backlog' },
+  create: { icon: '✏️', color: 'blue', label: 'Creating' },
+  approved: { icon: '✅', color: 'green', label: 'Approved' },
+  dev: { icon: '🔨', color: 'yellow', label: 'In Dev' },
+  in_progress: { icon: '🔄', color: 'yellow', label: 'In Progress' },
+  testing: { icon: '🧪', color: 'cyan', label: 'Testing' },
+  review: { icon: '👀', color: 'magenta', label: 'Review' },
+  release: { icon: '🚀', color: 'green', label: 'Release' },
+  done: { icon: '✅', color: 'green', label: 'Done' },
+  blocked: { icon: '🚫', color: 'red', label: 'Blocked' }
+};
+
+const PRIORITY_COLORS = {
+  P0: 'red',
+  P1: 'yellow',
+  P2: 'blue',
+  P3: 'gray'
+};
+
+function formatProgressBar(progress) {
+  const [completed, total] = progress.split('/').map(Number);
+  if (total === 0) return chalk.gray('N/A');
+
+  const percentage = Math.round((completed / total) * 100);
+  const barLength = 12;
+  const filledLength = Math.round((completed / total) * barLength);
+  const emptyLength = barLength - filledLength;
+
+  const filled = '█'.repeat(filledLength);
+  const empty = '░'.repeat(emptyLength);
+
+  let color = 'red';
+  if (percentage >= 80) color = 'green';
+  else if (percentage >= 50) color = 'yellow';
+
+  return chalk[color](filled) + chalk.gray(empty) + chalk.white(` ${percentage}%`);
+}
+
+function formatStatus(status) {
+  const config = STATUS_CONFIG[status] || { icon: '❓', color: 'gray', label: status };
+  return config.icon + ' ' + chalk[config.color](config.label);
+}
+
+function formatPriority(priority) {
+  const color = PRIORITY_COLORS[priority] || 'gray';
+  return chalk[color].bold(priority);
+}
+
+function displaySummary(stats) {
+  console.log('\n' + chalk.bold.cyan('━'.repeat(60)));
+  console.log(chalk.bold.cyan('  📊 PRODUCT STORIES DASHBOARD'));
+  console.log(chalk.bold.cyan('━'.repeat(60)) + '\n');
+
+  console.log(chalk.white.bold('Summary:'));
+  console.log(`  Total Stories:     ${chalk.green.bold(stats.total)}`);
+  console.log(`  Average Progress:  ${chalk.yellow.bold(stats.avgProgress + '%')}`);
+  console.log(`  Blocked:           ${stats.blocked > 0 ? chalk.red.bold(stats.blocked) : chalk.gray('0')}`);
+
+  console.log('\n' + chalk.white.bold('By Status:'));
+  Object.entries(stats.byStatus).forEach(([status, count]) => {
+    const config = STATUS_CONFIG[status] || { icon: '❓', color: 'gray' };
+    console.log(`  ${config.icon}  ${chalk[config.color](status.padEnd(12))} ${count}`);
+  });
+
+  console.log('\n' + chalk.white.bold('By Priority:'));
+  Object.entries(stats.byPriority).forEach(([priority, count]) => {
+    console.log(`  ${formatPriority(priority)}  ${count}`);
+  });
+
+  console.log('\n' + chalk.gray('─'.repeat(60)) + '\n');
+}
+
+function displayProjects(projects, options = {}) {
+  for (const project of projects) {
+    console.log(chalk.bold.white(`\n${project.name}`) + chalk.gray(` (${project.storyCount} stories)`));
+    console.log(chalk.gray('─'.repeat(60)));
+
+    const stories = project.stories.sort((a, b) => a.id.localeCompare(b.id));
+
+    let filtered = stories;
+    if (options.status) {
+      filtered = filtered.filter(s => s.status === options.status);
+    }
+    if (options.phase) {
+      filtered = filtered.filter(s => s.phase === options.phase);
+    }
+
+    if (filtered.length === 0) {
+      console.log(chalk.gray('  No stories match filters\n'));
+      continue;
+    }
+
+    for (const story of filtered) {
+      const statusDisplay = formatStatus(story.status);
+      const priorityDisplay = formatPriority(story.priority);
+      const progressBar = formatProgressBar(story.progress);
+      const blockerIndicator = story.blockers.length > 0 ? chalk.red.bold(' 🚫') : '';
+
+      console.log(`  ${chalk.cyan.bold(story.id)}  ${statusDisplay}  ${priorityDisplay}${blockerIndicator}`);
+      console.log(`    ${chalk.white(story.title)}`);
+      console.log(`    ${progressBar}  ${chalk.gray(story.progress + ' AC')}`);
+
+      if (story.blockers.length > 0) {
+        console.log(`    ${chalk.red('Blocked by:')} ${story.blockers.join(', ')}`);
+      }
+
+      console.log('');
+    }
+  }
+}
+
+function displayCompact(projects) {
+  for (const project of projects) {
+    console.log(chalk.bold.white(`\n${project.name}`));
+
+    const stories = project.stories.sort((a, b) => a.id.localeCompare(b.id));
+
+    for (const story of stories) {
+      const config = STATUS_CONFIG[story.status] || { icon: '❓' };
+      const [completed, total] = story.progress.split('/').map(Number);
+      const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
+      const blockerIndicator = story.blockers.length > 0 ? chalk.red(' 🚫') : '';
+
+      console.log(`  ${config.icon} ${chalk.cyan(story.id)} ${chalk.gray(story.title)} ${chalk.yellow(percentage + '%')}${blockerIndicator}`);
+    }
+  }
+  console.log('');
+}
+
+/**
+ * Main dashboard command
+ * @param {string} docsPath - Path to product-docs workspace
+ * @param {Object} options
+ */
+function dashboard(docsPath, options = {}) {
+  try {
+    const data = scanAllStories(docsPath);
+    const stats = getStats(data.stories);
+
+    if (data.stories.length === 0) {
+      console.log(chalk.yellow('\nNo stories found in ' + docsPath));
+      console.log(chalk.gray('Create your first story in Cursor: /create "feature" @project/backlog.md\n'));
+      return;
+    }
+
+    if (!options.compact) {
+      displaySummary(stats);
+    }
+
+    if (options.compact) {
+      displayCompact(data.projects);
+    } else {
+      displayProjects(data.projects, options);
+    }
+
+    console.log(chalk.gray(`Last updated: ${data.lastUpdated.toLocaleString()}`));
+    console.log('');
+
+  } catch (err) {
+    console.error(chalk.red('Error:'), err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { dashboard };