@pcoliveira90/pdd 0.2.6 → 0.3.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Paula Oliveira
-
-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
+MIT License
+
+Copyright (c) 2026 Paula Oliveira
+
+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.en.md

@@ -1,60 +1,75 @@
-# PDD — Patch-Driven Development
-![npm](https://img.shields.io/npm/v/@pcoliveira90/pdd)
-![license](https://img.shields.io/github/license/pcoliveira90/pdd)
-![stars](https://img.shields.io/github/stars/pcoliveira90/pdd)
-![issues](https://img.shields.io/github/issues/pcoliveira90/pdd)
-> Ship safe changes in living systems.
-
-PDD is an open-source framework focused on **bugfixes and incremental feature development in existing systems**.
-
----
-
-## The Problem
-
-Most development is not greenfield.
-
-It is:
-- fixing bugs in production
-- evolving legacy systems
-- adding features without breaking things
-
----
-
-## The Solution: PDD
-
-PDD focuses on:
-- understanding existing systems
-- identifying root causes
-- applying minimal safe changes
-- validating with evidence
-
----
-
-## Core Flow
-
-Issue → Recon → Delta Spec → Patch Plan → Change → Verify
-
----
-
-## Principles
-
-- Change-first
-- Evidence before edit
-- Minimal safe delta
-- Root-cause over symptom patch
-- Regression-aware
-- Reuse existing patterns
-- Verifiable outcomes
-
----
-
-## Structure
-
-.pdd/
-examples/
-
----
-
-## Vision
-
-Make AI-assisted development safe for real-world systems.
+# PDD - Patch-Driven Development
+
+[![npm version](https://img.shields.io/npm/v/@pcoliveira90/pdd)](https://www.npmjs.com/package/@pcoliveira90/pdd)
+[![CLI Self Validation](https://github.com/pcoliveira90/pdd/actions/workflows/cli-self-validation.yml/badge.svg)](https://github.com/pcoliveira90/pdd/actions/workflows/cli-self-validation.yml)
+[![License: MIT](https://img.shields.io/github/license/pcoliveira90/pdd)](https://github.com/pcoliveira90/pdd/blob/main/LICENSE)
+[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+> Safe changes in real systems.
+
+PDD is a CLI-first framework for bugfix and feature work in existing codebases.  
+It standardizes how teams investigate, plan, validate, and document changes.
+
+Language versions: [Default README](README.md) | [Português (Brasil)](README.pt-BR.md)
+
+## Why PDD
+
+- Worktree-first execution for safer parallel development
+- Structured change artifacts (`delta-spec`, `patch-plan`, `verification-report`)
+- Consistent workflow for Cursor, Claude Code, and GitHub Copilot
+- Built-in quality gates (`doctor`, validation, baseline CI checks)
+
+## Quick Start
+
+```bash
+# 1) Create a linked worktree (recommended and enforced for mutating flows)
+git worktree add ../pdd-worktrees/my-change -b feature/my-change
+
+# 2) Initialize PDD in the repository
+pdd init --here
+
+# 3) Run a fix workflow
+pdd fix "login not saving incomeStatus"
+```
+
+## Core Commands
+
+```bash
+pdd init --here
+pdd doctor
+pdd status
+pdd fix "bug description" [--dry-run] [--no-validate] [--open-pr]
+pdd version
+```
+
+AI analysis command:
+
+```bash
+pdd-ai --provider=openai --task=analysis "bug description"
+```
+
+## Workflow Summary
+
+1. Understand current behavior and root cause
+2. Generate change artifacts under `changes/<change-id>/`
+3. Validate tests/lint/build
+4. Prepare PR artifacts and review in IDE
+
+## IDE Alignment
+
+PDD keeps equivalent intents across tools:
+
+- Cursor: `.cursor/commands/pdd-*.md`
+- Claude Code: `.claude/commands/pdd-*.md`
+- GitHub Copilot: `.github/prompts/pdd-*.prompt.md`
+
+## Documentation
+
+- `docs/getting-started.md`
+- `docs/installation-and-setup.md`
+- `docs/fix-workflow.md`
+- `docs/manifesto.md`
+
+## Goal
+
+Reliable execution engine for safe software changes.

package/README.md

@@ -1,26 +1,75 @@
-# PDD — Patch-Driven Development
-
-> Safe changes in real systems.
-
-PDD is a framework focused on executing safe changes in existing systems.
-
-## CLI
-
-```bash
-pdd init
-pdd fix "bug"
-pdd fix "bug" --dry-run
-pdd fix "bug" --no-validate
-pdd fix "bug" --open-pr
-```
-
-## Flow
-
-1. describe issue
-2. generate artifacts
-3. validate
-4. prepare PR (IDE handles opening)
-
-## Goal
-
-Reliable execution engine for safe software changes.
+# PDD - Patch-Driven Development
+
+[![npm version](https://img.shields.io/npm/v/@pcoliveira90/pdd)](https://www.npmjs.com/package/@pcoliveira90/pdd)
+[![CLI Self Validation](https://github.com/pcoliveira90/pdd/actions/workflows/cli-self-validation.yml/badge.svg)](https://github.com/pcoliveira90/pdd/actions/workflows/cli-self-validation.yml)
+[![License: MIT](https://img.shields.io/github/license/pcoliveira90/pdd)](https://github.com/pcoliveira90/pdd/blob/main/LICENSE)
+[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+> Safe changes in real systems.
+
+PDD is a CLI-first framework for bugfix and feature work in existing codebases.  
+It standardizes how teams investigate, plan, validate, and document changes.
+
+Language versions: [English](README.en.md) | [Português (Brasil)](README.pt-BR.md)
+
+## Why PDD
+
+- Worktree-first execution for safer parallel development
+- Structured change artifacts (`delta-spec`, `patch-plan`, `verification-report`)
+- Consistent workflow for Cursor, Claude Code, and GitHub Copilot
+- Built-in quality gates (`doctor`, validation, baseline CI checks)
+
+## Quick Start
+
+```bash
+# 1) Create a linked worktree (recommended and enforced for mutating flows)
+git worktree add ../pdd-worktrees/my-change -b feature/my-change
+
+# 2) Initialize PDD in the repository
+pdd init --here
+
+# 3) Run a fix workflow
+pdd fix "login not saving incomeStatus"
+```
+
+## Core Commands
+
+```bash
+pdd init --here
+pdd doctor
+pdd status
+pdd fix "bug description" [--dry-run] [--no-validate] [--open-pr]
+pdd version
+```
+
+AI analysis command:
+
+```bash
+pdd-ai --provider=openai --task=analysis "bug description"
+```
+
+## Workflow Summary
+
+1. Understand current behavior and root cause
+2. Generate change artifacts under `changes/<change-id>/`
+3. Validate tests/lint/build
+4. Prepare PR artifacts and review in IDE
+
+## IDE Alignment
+
+PDD keeps equivalent intents across tools:
+
+- Cursor: `.cursor/commands/pdd-*.md`
+- Claude Code: `.claude/commands/pdd-*.md`
+- GitHub Copilot: `.github/prompts/pdd-*.prompt.md`
+
+## Documentation
+
+- `docs/getting-started.md`
+- `docs/installation-and-setup.md`
+- `docs/fix-workflow.md`
+- `docs/manifesto.md`
+
+## Goal
+
+Reliable execution engine for safe software changes.

package/README.pt-BR.md

@@ -1,12 +1,75 @@
-# PDD — Patch-Driven Development
-
-> Entregue mudanças seguras em sistemas existentes.
-
-PDD é um framework focado em aplicar mudanças seguras em sistemas reais.
-
-## CLI
-
-```bash
-pdd init
-pdd fix "bug"
-```
+# PDD - Patch-Driven Development
+
+[![npm version](https://img.shields.io/npm/v/@pcoliveira90/pdd)](https://www.npmjs.com/package/@pcoliveira90/pdd)
+[![CLI Self Validation](https://github.com/pcoliveira90/pdd/actions/workflows/cli-self-validation.yml/badge.svg)](https://github.com/pcoliveira90/pdd/actions/workflows/cli-self-validation.yml)
+[![License: MIT](https://img.shields.io/github/license/pcoliveira90/pdd)](https://github.com/pcoliveira90/pdd/blob/main/LICENSE)
+[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+> Entregue mudancas seguras em sistemas reais.
+
+PDD e um framework orientado a CLI para bugfix e evolucao de features em sistemas existentes.  
+Ele padroniza como o time investiga, planeja, valida e documenta mudancas.
+
+Versoes por idioma: [README padrao](README.md) | [English](README.en.md)
+
+## Por que usar PDD
+
+- Execucao worktree-first para desenvolvimento paralelo mais seguro
+- Artefatos estruturados de mudanca (`delta-spec`, `patch-plan`, `verification-report`)
+- Fluxo consistente para Cursor, Claude Code e GitHub Copilot
+- Quality gates nativos (`doctor`, validacao e checagens de CI)
+
+## Inicio rapido
+
+```bash
+# 1) Crie uma worktree vinculada (recomendado e exigido para fluxos mutaveis)
+git worktree add ../pdd-worktrees/minha-mudanca -b feature/minha-mudanca
+
+# 2) Inicialize o PDD no repositorio
+pdd init --here
+
+# 3) Rode um fluxo de correcao
+pdd fix "login nao salva incomeStatus"
+```
+
+## Comandos principais
+
+```bash
+pdd init --here
+pdd doctor
+pdd status
+pdd fix "descricao do bug" [--dry-run] [--no-validate] [--open-pr]
+pdd version
+```
+
+Comando de analise por IA:
+
+```bash
+pdd-ai --provider=openai --task=analysis "descricao do bug"
+```
+
+## Resumo do fluxo
+
+1. Entender comportamento atual e causa raiz
+2. Gerar artefatos em `changes/<change-id>/`
+3. Validar testes/lint/build
+4. Preparar artefatos de PR e revisar na IDE
+
+## Alinhamento entre IDEs
+
+O PDD mantem intencoes equivalentes entre ferramentas:
+
+- Cursor: `.cursor/commands/pdd-*.md`
+- Claude Code: `.claude/commands/pdd-*.md`
+- GitHub Copilot: `.github/prompts/pdd-*.prompt.md`
+
+## Documentacao
+
+- `docs/getting-started.md`
+- `docs/installation-and-setup.md`
+- `docs/fix-workflow.md`
+- `docs/manifesto.md`
+
+## Objetivo
+
+Motor de execucao confiavel para mudancas seguras em software real.

package/bin/pdd-ai.js

@@ -1,23 +1,24 @@
-#!/usr/bin/env node
-
-import { runAiFixAnalysis } from '../src/ai/run-fix-analysis.js';
-
-async function main() {
-  try {
-    const result = await runAiFixAnalysis(process.argv.slice(2));
-
-    console.log('\n🤖 PDD AI Analysis');
-    console.log('----------------------');
-    console.log(`Provider: ${result.provider}`);
-    console.log(`Model: ${result.model}`);
-    console.log(`Issue: ${result.issue}`);
-    console.log('\nResult:\n');
-
-    console.log(JSON.stringify(result.result, null, 2));
-  } catch (err) {
-    console.error('❌ Error:', err.message);
-    process.exit(1);
-  }
-}
-
-main();
+#!/usr/bin/env node
+
+import { runAiFixAnalysis } from '../src/ai/run-fix-analysis.js';
+
+async function main() {
+  try {
+    const result = await runAiFixAnalysis(process.argv.slice(2));
+
+    console.log('\n🤖 PDD AI Analysis');
+    console.log('----------------------');
+    console.log(`Provider: ${result.provider}`);
+    console.log(`Task: ${result.task}`);
+    console.log(`Model: ${result.model}`);
+    console.log(`Issue: ${result.issue}`);
+    console.log('\nResult:\n');
+
+    console.log(JSON.stringify(result.result, null, 2));
+  } catch (err) {
+    console.error('❌ Error:', err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/pdd-pro.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-
-import { runCli } from '../src/cli/index.js';
-
-runCli().catch(err => {
-  console.error(err);
-  process.exitCode = 1;
-});
+
+import { runCli } from '../src/cli/index.js';
+
+runCli().catch(err => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/bin/pdd.js

@@ -1,27 +1,8 @@
-#!/usr/bin/env node
-
-import fs from 'fs';
-import path from 'path';
-
-const command = process.argv[2];
-
-if (command === 'init') {
-  const targetDir = process.cwd();
-  const pddDir = path.join(targetDir, '.pdd');
-
-  if (fs.existsSync(pddDir)) {
-    console.log('PDD already initialized.');
-    process.exit(0);
-  }
-
-  fs.mkdirSync(pddDir, { recursive: true });
-  fs.mkdirSync(path.join(pddDir, 'templates'));
-  fs.mkdirSync(path.join(pddDir, 'commands'));
-  fs.mkdirSync(path.join(pddDir, 'memory'));
-
-  fs.writeFileSync(path.join(pddDir, 'README.md'), 'PDD initialized');
-
-  console.log('✅ PDD initialized successfully.');
-} else {
-  console.log('Usage: pdd init');
-}
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli/index.js';
+
+runCli(process.argv.slice(2)).catch(err => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,42 +1,43 @@
-{
-  "name": "@pcoliveira90/pdd",
-  "version": "0.2.6",
-  "description": "Patch-Driven Development CLI — safe, resilient and guided code changes",
-  "type": "module",
-  "bin": {
-    "pdd": "bin/pdd-pro.js"
-  },
-  "files": [
-    "bin",
-    "src"
-  ],
-  "scripts": {
-    "start": "node bin/pdd-pro.js",
-    "dev": "node bin/pdd-pro.js",
-    "test": "echo \"No tests yet\"",
-    "lint": "echo \"No lint configured\"",
-    "prepublishOnly": "npm pack"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "cli",
-    "developer-tools",
-    "patch",
-    "refactoring",
-    "ai-workflow",
-    "engineering",
-    "pdd"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/pcoliveira90/pdd.git"
-  },
-  "bugs": {
-    "url": "https://github.com/pcoliveira90/pdd/issues"
-  },
-  "homepage": "https://github.com/pcoliveira90/pdd#readme",
-  "author": "Paula Oliveira",
-  "license": "MIT"
-}
+{
+  "name": "@pcoliveira90/pdd",
+  "version": "0.3.1",
+  "description": "Patch-Driven Development CLI — safe, resilient and guided code changes",
+  "type": "module",
+  "bin": {
+    "pdd": "bin/pdd-pro.js",
+    "pdd-ai": "bin/pdd-ai.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "start": "node bin/pdd-pro.js",
+    "dev": "node bin/pdd-pro.js",
+    "test": "node --test",
+    "lint": "node ./scripts/lint-js.mjs",
+    "prepublishOnly": "npm pack"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cli",
+    "developer-tools",
+    "patch",
+    "refactoring",
+    "ai-workflow",
+    "engineering",
+    "pdd"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pcoliveira90/pdd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pcoliveira90/pdd/issues"
+  },
+  "homepage": "https://github.com/pcoliveira90/pdd#readme",
+  "author": "Paula Oliveira",
+  "license": "MIT"
+}

package/src/ai/analyze-change.js

@@ -1,41 +1,41 @@
-import fs from 'fs';
-import path from 'path';
-
-function readIfExists(filePath) {
-  if (!fs.existsSync(filePath)) return null;
-  return fs.readFileSync(filePath, 'utf-8');
-}
-
-export function buildAiAnalysisContext(baseDir = process.cwd()) {
-  const context = {
-    constitution: readIfExists(path.join(baseDir, '.pdd', 'constitution.md')),
-    deltaSpec: readIfExists(path.join(baseDir, '.pdd', 'templates', 'delta-spec.md')),
-    patchPlan: readIfExists(path.join(baseDir, '.pdd', 'templates', 'patch-plan.md')),
-    verification: readIfExists(path.join(baseDir, '.pdd', 'templates', 'verification-report.md'))
-  };
-
-  return context;
-}
-
-export function buildBugfixPrompt({ issue, baseDir = process.cwd() }) {
-  const context = buildAiAnalysisContext(baseDir);
-
-  return [
-    'You are a senior engineer working in an existing system.',
-    'Follow Patch-Driven Development principles.',
-    'Focus on root cause, minimal safe delta, and regression awareness.',
-    '',
-    'Issue:',
-    issue,
-    '',
-    'Available context:',
-    JSON.stringify(context, null, 2),
-    '',
-    'Return:',
-    '- root cause hypothesis',
-    '- impacted areas',
-    '- minimal safe delta',
-    '- regression risks',
-    '- validation plan'
-  ].join('\n');
-}
+import fs from 'fs';
+import path from 'path';
+
+function readIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, 'utf-8');
+}
+
+export function buildAiAnalysisContext(baseDir = process.cwd()) {
+  const context = {
+    constitution: readIfExists(path.join(baseDir, '.pdd', 'constitution.md')),
+    deltaSpec: readIfExists(path.join(baseDir, '.pdd', 'templates', 'delta-spec.md')),
+    patchPlan: readIfExists(path.join(baseDir, '.pdd', 'templates', 'patch-plan.md')),
+    verification: readIfExists(path.join(baseDir, '.pdd', 'templates', 'verification-report.md'))
+  };
+
+  return context;
+}
+
+export function buildBugfixPrompt({ issue, baseDir = process.cwd() }) {
+  const context = buildAiAnalysisContext(baseDir);
+
+  return [
+    'You are a senior engineer working in an existing system.',
+    'Follow Patch-Driven Development principles.',
+    'Focus on root cause, minimal safe delta, and regression awareness.',
+    '',
+    'Issue:',
+    issue,
+    '',
+    'Available context:',
+    JSON.stringify(context, null, 2),
+    '',
+    'Return:',
+    '- root cause hypothesis',
+    '- impacted areas',
+    '- minimal safe delta',
+    '- regression risks',
+    '- validation plan'
+  ].join('\n');
+}