@prductr/carlos

AI-powered product roadmap generation and market fit assessment.

Target Audience

Software developers, product managers, and engineering teams who need structured product strategy documentation but don't have time to maintain it manually.

Problem Statement

Product teams waste hours manually writing and updating roadmaps, PMF assessments, and backlog priorities — documents that go stale the moment code changes. There's no single tool that reads your existing codebase and docs and generates all of them automatically.

Solution

Carlos analyzes your project's docs and codebase to generate actionable scopecraft documentation: phased roadmaps, PMF assessments, prioritized backlogs, and technical debt reports.

Value Proposition

Zero configuration, always up-to-date product intelligence. Point Carlos at any project and get a full product strategy document set in seconds — roadmap, market fit score, prioritized backlog, and technical health report.

Installation

npm install -g @prductr/carlos   # global CLI
npm install @prductr/carlos      # programmatic API

CLI

carlos roadmap              # Generate phased product roadmap
carlos market-fit           # Assess product-market fit (0–100 score)
carlos backlog              # Prioritize features from docs/FEATURES.md
carlos audit                # Technical debt audit
carlos full                 # Run all four analyses concurrently
carlos feedback             # How to report issues or request features
carlos --version            # Print version
carlos help                 # Show all commands and flags

Flags

| Flag | Description | |------|-------------| | --json | Output result as JSON (all commands) | | --features <json> | Feature list for backlog (JSON array, overrides FEATURES.md) | | --version, -v | Print version and exit |

# JSON output for scripting
carlos market-fit --json | jq '.productMarketFitScore'

# Inline feature list
carlos backlog --features '["Auth", "Dashboard", "Export"]'

# Analyze a specific directory
carlos roadmap ./path/to/project

Feature file

Carlos reads docs/FEATURES.md (or FEATURES.md at root) for the backlog command:

# Features

- User authentication
- Dashboard with real-time metrics
- Export to CSV
- Dark mode support

Config file

Create carlos.config.json in your project root to override defaults:

{
  "outputDir": "scopecraft",
  "docsDir": "docs",
  "includeMarketFit": true,
  "includeTechnicalAudit": true
}

Output

Carlos writes Markdown reports to scopecraft/ (configurable via outputDir):

scopecraft/
├── ROADMAP.md           # Phased roadmap with epics and milestones
├── METRICS_AND_PMF.md   # PMF score, differentiators, recommendations
├── PRODUCT_BACKLOG.md   # Now / Next / Later prioritized backlog
└── TECHNICAL_AUDIT.md   # Debt items by category with severity

PMF scoring

A project scores higher when its PRD or README includes:

| Section | Points | |---------|--------| | ## Target Audience | 20 | | ## Problem Statement | 20 | | ## Solution | 20 | | ## Value Proposition | 20 | | Differentiators present | 15 | | Low / no competition | up to 5 |

A blank project scores ≤ 20. A well-documented one scores ≥ 75.

Programmatic API

import {
  generateRoadmap,
  assessMarketFit,
  prioritizeFeatures,
  auditTechnical,
  readFeatures,
  loadConfig,
} from '@prductr/carlos';

// Load config from carlos.config.json (falls back to defaults)
const config = loadConfig('/path/to/project');

const roadmap    = await generateRoadmap(config);
const assessment = await assessMarketFit(config);
const features   = await readFeatures(config);        // reads FEATURES.md
const backlog    = await prioritizeFeatures(config, features);
const audit      = await auditTechnical(config);

// Or run all concurrently
const [roadmap, assessment, audit] = await Promise.all([
  generateRoadmap(config),
  assessMarketFit(config),
  auditTechnical(config),
]);

Exported utilities

| Export | Description | |--------|-------------| | generateRoadmap(config) | Generate phased roadmap | | assessMarketFit(config) | PMF assessment | | prioritizeFeatures(config, features) | RICE-scored backlog | | auditTechnical(config) | Technical debt audit | | readFeatures(config) | Read features from FEATURES.md | | parseFeaturesFlag(args) | Parse --features JSON from argv | | loadConfig(projectRoot) | Load + merge carlos.config.json | | getVersion() | Package version string | | hasJsonFlag(args) | Detect --json in argv |

Product stages

Carlos infers the current stage from package.json version:

| Version | Stage | |---------|-------| | 0.0.x | prototype | | 0.x.x | mvp | | 1.0.x | beta | | 2.x.x+ | growth | | No package.json + README | mvp | | No package.json, no README | idea |

Troubleshooting

See docs/RUNBOOK.md for common issues and fixes.

To report a bug or request a feature: carlos feedback

License

MIT