npm package: @prductr/carlos
Description: AI-powered product roadmap generation and market fit assessment
Author: prductr
Latest version: 1.0.3

# @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

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

## CLI

```bash
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 |

```bash
# 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:

```markdown
# Features

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

## Configuration

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

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

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `outputDir` | string | `"scopecraft"` | Directory where report files are written |
| `docsDir` | string | `"docs"` | Directory where Carlos looks for `PRD.md` and other docs |
| `includeMarketFit` | boolean | `true` | Run PMF assessment as part of `full` command |
| `includeTechnicalAudit` | boolean | `true` | Run technical audit as part of `full` command |

> CLI flags and arguments always take priority over values in `carlos.config.json`.

## 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

```typescript
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](docs/RUNBOOK.md) for common issues and fixes.

To report a bug or request a feature: `carlos feedback`

## License

MIT