@shahmarasy/prodo 0.1.3 → 0.1.5

package/README.md

@@ -1,157 +1,261 @@
 <div align="center">
-  <h1>Prodo</h1>
-  <h3><em>Product Artifact Toolkit</em></h3>
-</div>
-
-<p align="center">
-  <strong>Build consistent product documentation from a stable brief with a CLI-first workflow.</strong>
-</p>
 
----
+# Prodo
 
-## Table of Contents
+**AI-Powered Product Owner for Your Codebase**
 
-- [What is Prodo?](#what-is-prodo)
-- [Install](#install)
-- [Quick Start](#quick-start)
-- [Core Workflow](#core-workflow)
-- [Supported Agents](#supported-agents)
-- [CLI Reference](#cli-reference)
-- [Output Structure](#output-structure)
-- [Validation Model](#validation-model)
-- [Development](#development)
-- [License](#license)
+Turn a short product brief into a complete documentation suite — PRD, workflows, wireframes, user stories, tech spec — validated for cross-artifact consistency.
 
-## What is Prodo?
+[![npm version](https://img.shields.io/npm/v/@shahmarasy/prodo)](https://www.npmjs.com/package/@shahmarasy/prodo)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-99%20passing-brightgreen)]()
 
-Prodo is a CLI-first toolkit for product-document pipelines.
+</div>
 
-It helps teams move from a raw brief to structured artifacts such as:
+---
 
-- PRD
-- Workflow (Markdown explanation + Mermaid)
-- Wireframe (Markdown explanation + HTML)
-- Stories
-- Tech Spec
+## Why Prodo?
 
-Prodo is designed to keep input stable, outputs deterministic, and cross-artifact consistency measurable.
+| Problem | Prodo's Answer |
+|---------|---------------|
+| PRDs drift from implementation | **Input is read-only** — `brief.md` never changes during execution |
+| Docs contradict each other | **7 validation gates** check cross-artifact consistency |
+| Every team reinvents the format | **Strict templates** enforce structure across all artifacts |
+| Tied to one AI tool | **Agent-agnostic** — works with Claude, Codex, Gemini, or any LLM |
+| Manual doc maintenance | **One command** regenerates everything from the brief |
 
-## Install
+## Quick Start
 
 ```bash
+# Install globally
 npm i -g @shahmarasy/prodo
+
+# Initialize in your project
+prodo init . --ai claude-cli --lang en
+
+# Edit your brief
+code brief.md
+
+# Generate everything
+prodo generate
+
+# Check environment
+prodo doctor
 ```
 
-## Quick Start
+**That's it.** Prodo normalizes your brief, generates 5 artifact types, validates them, and writes everything to `product-docs/`.
+
+## What Gets Generated
+
+```
+brief.md                          # Your input (read-only)
+product-docs/
+  prd/                            # Product Requirements Document
+  workflows/                      # Flow descriptions + Mermaid diagrams
+  wireframes/                     # Screen descriptions + HTML prototypes
+  stories/                        # User stories with Gherkin scenarios
+  techspec/                       # Architecture, APIs, data models
+  reports/                        # Validation report
+```
+
+Every artifact includes:
+- **Contract tags** (`[G1]`, `[F2]`, `[C1]`) linking back to brief requirements
+- **Frontmatter** with version, author, upstream references
+- **Companion files** — workflow gets `.mmd` (Mermaid), wireframe gets `.html`
+
+## CLI Reference
+
+### Primary Commands
+
+| Command | Description |
+|---------|-------------|
+| `prodo init [target]` | Bootstrap project with `.prodo/` scaffold and agent commands |
+| `prodo generate` | Full pipeline: normalize → generate all → validate |
+| `prodo doctor` | Check environment, SDKs, and agent availability |
+| `prodo clean` | Remove generated artifacts, keep brief and config |
+
+### Pipeline Commands
+
+| Command | Description |
+|---------|-------------|
+| `prodo normalize` | Convert brief.md to structured JSON |
+| `prodo prd` | Generate Product Requirements Document |
+| `prodo workflow` | Generate workflow (Markdown + Mermaid) |
+| `prodo wireframe` | Generate wireframes (Markdown + HTML) |
+| `prodo stories` | Generate user stories |
+| `prodo techspec` | Generate technical specification |
+| `prodo validate` | Run 7-gate cross-artifact validation |
+| `prodo fix` | Auto-repair failing artifacts with backup |
+
+### Global Flags
+
+| Flag | Available On | Description |
+|------|-------------|-------------|
+| `--ai <name>` | `init` | Agent: `codex`, `gemini-cli`, `claude-cli` |
+| `--lang <code>` | `init` | Language: `en`, `tr` (extensible) |
+| `--agent <name>` | `generate`, `fix` | Override agent profile |
+| `--dry-run` | `generate`, `normalize`, `fix`, `clean` | Preview without writing |
+| `--strict` | `validate`, `generate`, `fix` | Treat warnings as errors |
+| `--interactive` | `normalize` | Q&A loop for low-confidence fields |
+
+## LLM Providers
+
+Prodo supports multiple LLM backends as optional peer dependencies:
 
 ```bash
-# 1) Initialize in your project
-prodo init . --ai codex --lang tr
+# OpenAI
+npm install openai
+export PRODO_AGENT=openai OPENAI_API_KEY=sk-...
 
-# 2) Edit brief
-# brief.md
+# Anthropic Claude
+npm install @anthropic-ai/sdk
+export PRODO_AGENT=anthropic ANTHROPIC_API_KEY=sk-ant-...
 
-# 3) Check environment (optional)
-prodo doctor
+# Google Gemini
+npm install @google/generative-ai
+export PRODO_AGENT=google GOOGLE_API_KEY=AI...
 ```
 
-## Core Workflow
+Install only the SDK you need. `prodo doctor` shows which agents are available.
 
-After initialization, Prodo installs agent-native command files.
+> **Full guide:** [docs/providers.md](docs/providers.md)
 
-Recommended flow inside your AI agent:
+## Agent Integration
 
-1. Normalize the brief
-2. Produce artifacts in sequence
-3. Validate consistency
+`prodo init --ai <name>` installs native command files for your AI agent:
 
-Prodo keeps:
+| Agent | Location | Format | Commands |
+|-------|----------|--------|----------|
+| Codex | `.agents/skills/` | SKILL.md | `$prodo-normalize`, `$prodo-prd`, ... |
+| Gemini CLI | `.gemini/commands/` | TOML | `/prodo-normalize`, `/prodo-prd`, ... |
+| Claude CLI | `.claude/commands/` | Markdown | `/prodo-normalize`, `/prodo-prd`, ... |
 
-- `brief.md` as input
-- `.prodo/` as internal runtime state
-- `product-docs/` as user-facing outputs
+Agent workflow: edit `brief.md` → run `/prodo-normalize` → `/prodo-prd` → ... → `/prodo-validate`
 
-## Supported Agents
+## Validation Gates
 
-`prodo init --ai <name>` supports:
+`prodo validate` runs 7 sequential checks:
 
-- `codex`
-- `gemini-cli`
-- `claude-cli`
+| # | Gate | Type | What It Checks |
+|---|------|------|----------------|
+| 1 | **Schema** | Structural | Frontmatter, required headings, content length |
+| 2 | **Tag Coverage** | Structural | Contract IDs present in frontmatter |
+| 3 | **Contract Relevance** | LLM-based | Tagged content matches contract text |
+| 4 | **Semantic Consistency** | LLM-based | No contradictions between artifact pairs |
+| 5 | **Terminology** | Heuristic | Consistent naming across documents |
+| 6 | **Tracing** | Structural | Every brief requirement referenced in artifacts |
+| 7 | **Cross-Reference** | Structural | Inline references point to real sections |
 
-Agent command files are installed to native locations:
+Use `--strict` to promote warnings to errors (recommended for CI).
 
-- Codex: `.agents/skills/`
-- Gemini CLI: `.gemini/commands/`
-- Claude CLI: `.claude/commands/`
+> **Full guide:** [docs/validation.md](docs/validation.md)
 
-## Agent Commands
+## Human-in-the-Loop Fix
 
-Prodo agent command set:
+When validation fails:
 
-- `/prodo-normalize`
-- `/prodo-prd`
-- `/prodo-workflow`
-- `/prodo-wireframe`
-- `/prodo-stories`
-- `/prodo-techspec`
-- `/prodo-validate`
+```bash
+prodo fix              # Shows proposal → asks confirmation → backs up → repairs
+prodo fix --dry-run    # Preview what would be regenerated
+```
 
-Codex skills mode equivalents:
+The fix command:
+1. Runs validation to identify issues
+2. Computes affected artifacts + downstream dependencies
+3. **Shows a proposal** with issue details
+4. **Asks for confirmation** (auto-proceeds in CI)
+5. Creates a timestamped backup in `.prodo/state/backups/`
+6. Regenerates impacted artifacts with version increment
+7. Re-validates to confirm the fix
 
-- `$prodo-normalize`
-- `$prodo-prd`
-- `$prodo-workflow`
-- `$prodo-wireframe`
-- `$prodo-stories`
-- `$prodo-techspec`
-- `$prodo-validate`
+## Skill Engine
 
-## CLI Reference
+Prodo includes a composable skill system:
+
+```bash
+prodo skills list                                    # List all skills
+prodo skills run normalize --input '{"cwd": "."}'    # Run a skill
+```
 
-Primary commands:
+Built-in skills: `normalize`, `validate`, `fix`, `generate-artifact`, `generate-pipeline`
 
-- `prodo init [target] [--ai <name>] [--lang <code>] [--preset <name>]`
-- `prodo doctor` (alias: `prodo check`)
+> **Full guide:** [docs/skills.md](docs/skills.md)
 
-Version:
+## Presets
 
-- `prodo --version`
-- `prodo -v`
+Domain-specific presets enrich generation with industry context:
 
-## Output Structure
+```bash
+prodo init . --preset saas
+prodo init . --preset fintech
+prodo init . --preset marketplace
+```
 
-Project-level:
+Presets provide specialized prompt templates, validation rules, and domain vocabulary.
 
-- `brief.md` (input, read-only during execution)
-- `product-docs/` (all generated product documents)
-- `.prodo/` (internal runtime state: prompts, schemas, templates, index, context)
+## Internationalization
 
-Paired artifact behavior:
+Prodo supports multiple languages via JSON-based translations:
 
-- Workflow: `*.md` + `*.mmd`
-- Wireframe: `*.md` + `*.html`
+```bash
+prodo init . --lang tr    # Turkish
+prodo init . --lang en    # English (default)
+```
 
-## Validation Model
+Language enforcement prevents mixing — Turkish projects are checked for English leaks and vice versa. Add new languages by creating `src/i18n/<code>.json`.
 
-Validation reports include gate-based checks:
+## Project Structure
 
-- Schema pass
-- Tag coverage pass
-- Contract relevance pass
-- Semantic consistency pass
+```
+your-project/
+  brief.md                    # Your product brief (input)
+  product-docs/               # Generated artifacts (output)
+  .prodo/
+    settings.json             # Language, author, agent config
+    hooks.yml                 # Lifecycle hooks
+    briefs/                   # Normalized brief JSON
+    templates/                # Artifact templates (customizable)
+    schemas/                  # Validation schemas
+    prompts/                  # LLM prompts
+    commands/                 # Agent command templates
+    state/                    # Runtime state, backups
+```
 
-All applicable gates must pass for final success.
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Provider Setup](docs/providers.md) | Configure OpenAI, Anthropic, Google agents |
+| [Writing Briefs](docs/writing-briefs.md) | Structure your brief for best results |
+| [Validation Gates](docs/validation.md) | Understand all 7 validation checks |
+| [Hook System](docs/hooks.md) | Lifecycle hooks with conditions and retries |
+| [Skill Engine](docs/skills.md) | Built-in skills and custom development |
+| [Local Development](docs/local-development.md) | Dev setup and testing |
+| [Upgrade Guide](docs/upgrade.md) | Migrating between versions |
 
 ## Development
 
 ```bash
+git clone https://github.com/shahmarasy/prodo.git
+cd prodo
 npm install
 npm run build
-npm test
-npm run verify:release
+npm test          # 99 tests
+```
+
+## Architecture
+
+```
+src/
+  core/       # Business logic (artifacts, validation, normalization)
+  cli/        # Commander entry points and TUI
+  agents/     # LLM plugins (OpenAI, Anthropic, Google, Mock)
+  skills/     # Composable skill engine
+  i18n/       # Translation system (en, tr)
+  providers/  # Backward-compatible provider shim
 ```
 
 ## License
 
-MIT
+MIT &copy; [Shahmarasy](https://github.com/shahmarasy)

package/bin/prodo.cjs

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
-"use strict";
-require("../dist/cli").runCli().then((code) => {
-  process.exitCode = code;
-});
-
+#!/usr/bin/env node
+"use strict";
+require("../dist/cli/index").runCli().then((code) => {
+  process.exitCode = code;
+});
+

package/dist/agents/agent-registry.d.ts

@@ -0,0 +1,13 @@
+import type { AgentPlugin } from "./base";
+import type { LLMProvider } from "../core/types";
+export declare class AgentRegistry {
+    private agents;
+    register(agent: AgentPlugin): void;
+    list(): AgentPlugin[];
+    get(name: string): AgentPlugin | undefined;
+    resolve(name?: string): Promise<AgentPlugin>;
+    private resolveAgentName;
+    toProvider(agent: AgentPlugin): LLMProvider;
+}
+export declare function getGlobalRegistry(): AgentRegistry;
+export declare function resetGlobalRegistry(): void;

package/dist/agents/agent-registry.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRegistry = void 0;
+exports.getGlobalRegistry = getGlobalRegistry;
+exports.resetGlobalRegistry = resetGlobalRegistry;
+const errors_1 = require("../core/errors");
+const mock_1 = require("./mock");
+const openai_1 = require("./openai");
+const anthropic_1 = require("./anthropic");
+const google_1 = require("./google");
+const AGENT_ALIASES = {
+    mock: "mock",
+    openai: "openai",
+    anthropic: "anthropic",
+    claude: "anthropic",
+    google: "google",
+    gemini: "google"
+};
+class AgentRegistry {
+    agents = new Map();
+    register(agent) {
+        this.agents.set(agent.name, agent);
+    }
+    list() {
+        return Array.from(this.agents.values());
+    }
+    get(name) {
+        const normalized = AGENT_ALIASES[name.toLowerCase().trim()] ?? name.toLowerCase().trim();
+        return this.agents.get(normalized);
+    }
+    async resolve(name) {
+        const agentName = this.resolveAgentName(name);
+        const agent = this.get(agentName);
+        if (!agent) {
+            const available = this.list().map((a) => a.name).join(", ");
+            throw new errors_1.UserError(`Unknown agent: "${agentName}". Available agents: ${available}`);
+        }
+        return agent;
+    }
+    resolveAgentName(override) {
+        if (override)
+            return override;
+        const fromEnv = process.env.PRODO_AGENT;
+        if (fromEnv)
+            return fromEnv;
+        const fromLegacy = process.env.PRODO_LLM_PROVIDER;
+        if (fromLegacy)
+            return fromLegacy;
+        const isTest = process.env.NODE_ENV === "test" ||
+            process.env.PRODO_TEST === "1";
+        if (isTest)
+            return "mock";
+        return "mock";
+    }
+    toProvider(agent) {
+        return {
+            generate: (prompt, inputContext, schemaHint) => agent.generate(prompt, inputContext, schemaHint)
+        };
+    }
+}
+exports.AgentRegistry = AgentRegistry;
+let globalRegistry = null;
+function createDefaultRegistry() {
+    const registry = new AgentRegistry();
+    registry.register(new mock_1.MockAgent());
+    registry.register(new openai_1.OpenAIAgent());
+    registry.register(new anthropic_1.AnthropicAgent());
+    registry.register(new google_1.GoogleAgent());
+    return registry;
+}
+function getGlobalRegistry() {
+    if (!globalRegistry) {
+        globalRegistry = createDefaultRegistry();
+    }
+    return globalRegistry;
+}
+function resetGlobalRegistry() {
+    globalRegistry = null;
+}

package/dist/agents/anthropic/index.d.ts

@@ -0,0 +1,9 @@
+import { BaseAgent, type AgentConfig } from "../base";
+import type { GenerateResult, ProviderSchemaHint } from "../../core/types";
+export declare class AnthropicAgent extends BaseAgent {
+    readonly name = "anthropic";
+    readonly displayName = "Anthropic Claude";
+    readonly sdkRequired = "@anthropic-ai/sdk";
+    getConfig(): AgentConfig;
+    generate(prompt: string, inputContext: Record<string, unknown>, schemaHint: ProviderSchemaHint): Promise<GenerateResult>;
+}

package/dist/agents/anthropic/index.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnthropicAgent = void 0;
+const base_1 = require("../base");
+const system_prompts_1 = require("../system-prompts");
+const errors_1 = require("../../core/errors");
+const dynamicImport = new Function("specifier", "return import(specifier)");
+class AnthropicAgent extends base_1.BaseAgent {
+    name = "anthropic";
+    displayName = "Anthropic Claude";
+    sdkRequired = "@anthropic-ai/sdk";
+    getConfig() {
+        return {
+            name: this.name,
+            displayName: this.displayName,
+            sdkRequired: this.sdkRequired,
+            envVars: ["ANTHROPIC_API_KEY"],
+            defaultModel: "claude-sonnet-4-20250514"
+        };
+    }
+    async generate(prompt, inputContext, schemaHint) {
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+            throw new errors_1.UserError("ANTHROPIC_API_KEY is not set. Set it to use the Anthropic agent.");
+        }
+        const model = process.env.PRODO_ANTHROPIC_MODEL ?? "claude-sonnet-4-20250514";
+        const outputLanguage = typeof inputContext.outputLanguage === "string" && inputContext.outputLanguage.trim()
+            ? inputContext.outputLanguage.trim()
+            : "en";
+        const system = (0, system_prompts_1.buildSystemPrompt)(schemaHint, outputLanguage);
+        const user = (0, system_prompts_1.buildUserMessage)(prompt, inputContext);
+        let AnthropicConstructor;
+        try {
+            const mod = (await dynamicImport("@anthropic-ai/sdk"));
+            AnthropicConstructor = mod.default;
+        }
+        catch {
+            throw new errors_1.UserError("Anthropic SDK is not installed. Run: npm install @anthropic-ai/sdk");
+        }
+        const client = new AnthropicConstructor({ apiKey });
+        const response = await client.messages.create({
+            model,
+            max_tokens: 8192,
+            system,
+            messages: [{ role: "user", content: user }]
+        });
+        const textBlock = response.content.find((block) => block.type === "text");
+        const content = textBlock?.text?.trim() ?? "";
+        if (!content) {
+            throw new errors_1.UserError("Anthropic agent returned an empty response.");
+        }
+        return { body: content };
+    }
+}
+exports.AnthropicAgent = AnthropicAgent;

package/dist/agents/base.d.ts

@@ -0,0 +1,25 @@
+import type { GenerateResult, ProviderSchemaHint } from "../core/types";
+export type AgentConfig = {
+    name: string;
+    displayName: string;
+    sdkRequired: string | null;
+    envVars: string[];
+    defaultModel?: string;
+};
+export interface AgentPlugin {
+    readonly name: string;
+    readonly displayName: string;
+    readonly sdkRequired: string | null;
+    generate(prompt: string, inputContext: Record<string, unknown>, schemaHint: ProviderSchemaHint): Promise<GenerateResult>;
+    isAvailable(): Promise<boolean>;
+    getConfig(): AgentConfig;
+}
+export declare abstract class BaseAgent implements AgentPlugin {
+    abstract readonly name: string;
+    abstract readonly displayName: string;
+    abstract readonly sdkRequired: string | null;
+    abstract generate(prompt: string, inputContext: Record<string, unknown>, schemaHint: ProviderSchemaHint): Promise<GenerateResult>;
+    abstract getConfig(): AgentConfig;
+    isAvailable(): Promise<boolean>;
+    availabilityHint(): string;
+}

package/dist/agents/base.js

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAgent = void 0;
+class BaseAgent {
+    async isAvailable() {
+        const config = this.getConfig();
+        if (config.sdkRequired) {
+            try {
+                await Promise.resolve(`${config.sdkRequired}`).then(s => __importStar(require(s)));
+            }
+            catch {
+                return false;
+            }
+        }
+        for (const envVar of config.envVars) {
+            if (!process.env[envVar]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    availabilityHint() {
+        const config = this.getConfig();
+        const hints = [];
+        if (config.sdkRequired) {
+            hints.push(`SDK required: npm install ${config.sdkRequired}`);
+        }
+        for (const envVar of config.envVars) {
+            if (!process.env[envVar]) {
+                hints.push(`Set environment variable: ${envVar}`);
+            }
+        }
+        return hints.length > 0
+            ? `Agent "${config.displayName}" is not available.\n  ${hints.join("\n  ")}`
+            : `Agent "${config.displayName}" is available.`;
+    }
+}
+exports.BaseAgent = BaseAgent;

package/dist/agents/google/index.d.ts

@@ -0,0 +1,9 @@
+import { BaseAgent, type AgentConfig } from "../base";
+import type { GenerateResult, ProviderSchemaHint } from "../../core/types";
+export declare class GoogleAgent extends BaseAgent {
+    readonly name = "google";
+    readonly displayName = "Google Gemini";
+    readonly sdkRequired = "@google/generative-ai";
+    getConfig(): AgentConfig;
+    generate(prompt: string, inputContext: Record<string, unknown>, schemaHint: ProviderSchemaHint): Promise<GenerateResult>;
+}