@pcoliveira90/pdd 0.3.0 → 0.3.1

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 - Patch-Driven Development
 
-PDD is an open-source framework focused on **bugfixes and incremental feature development in existing systems**.
+[![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.
 
-## The Problem
+PDD is a CLI-first framework for bugfix and feature work in existing codebases.  
+It standardizes how teams investigate, plan, validate, and document changes.
 
-Most development is not greenfield.
+Language versions: [Default README](README.md) | [Português (Brasil)](README.pt-BR.md)
 
-It is:
-- fixing bugs in production
-- evolving legacy systems
-- adding features without breaking things
+## 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)
 
-## The Solution: PDD
+## Quick Start
 
-PDD focuses on:
-- understanding existing systems
-- identifying root causes
-- applying minimal safe changes
-- validating with evidence
+```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
 
-## Core Flow
+# 3) Run a fix workflow
+pdd fix "login not saving incomeStatus"
+```
 
-Issue → Recon → Delta Spec → Patch Plan → Change → Verify
+## Core Commands
 
----
+```bash
+pdd init --here
+pdd doctor
+pdd status
+pdd fix "bug description" [--dry-run] [--no-validate] [--open-pr]
+pdd version
+```
 
-## Principles
+AI analysis command:
 
-- Change-first
-- Evidence before edit
-- Minimal safe delta
-- Root-cause over symptom patch
-- Regression-aware
-- Reuse existing patterns
-- Verifiable outcomes
+```bash
+pdd-ai --provider=openai --task=analysis "bug description"
+```
 
----
+## Workflow Summary
 
-## Structure
+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
 
-.pdd/
-examples/
+## IDE Alignment
 
----
+PDD keeps equivalent intents across tools:
 
-## Vision
+- Cursor: `.cursor/commands/pdd-*.md`
+- Claude Code: `.claude/commands/pdd-*.md`
+- GitHub Copilot: `.github/prompts/pdd-*.prompt.md`
 
-Make AI-assisted development safe for real-world systems.
+## 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,74 @@
-# PDD — Patch-Driven Development
+# 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 framework focused on executing safe changes in existing 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"
+```
 
-## CLI
+## Core Commands
 
 ```bash
-pdd init
-pdd fix "bug"
-pdd fix "bug" --dry-run
-pdd fix "bug" --no-validate
-pdd fix "bug" --open-pr
-pdd-ai --provider=openai --task=analysis "bug"
+pdd init --here
+pdd doctor
+pdd status
+pdd fix "bug description" [--dry-run] [--no-validate] [--open-pr]
+pdd version
 ```
 
-## Flow
+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
 
-1. describe issue
-2. generate artifacts
-3. validate
-4. prepare PR (IDE handles opening)
+- `docs/getting-started.md`
+- `docs/installation-and-setup.md`
+- `docs/fix-workflow.md`
+- `docs/manifesto.md`
 
 ## Goal
 

package/README.pt-BR.md

@@ -1,12 +1,75 @@
-# PDD — Patch-Driven Development
+# PDD - Patch-Driven Development
 
-> Entregue mudanças seguras em sistemas existentes.
+[![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/)
 
-PDD é um framework focado em aplicar mudanças seguras em sistemas reais.
+> Entregue mudancas seguras em sistemas reais.
 
-## CLI
+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
-pdd fix "bug"
+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

@@ -9,6 +9,7 @@ async function main() {
     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');

package/bin/pdd.js

@@ -1,27 +1,8 @@
 #!/usr/bin/env node
 
-import fs from 'fs';
-import path from 'path';
+import { runCli } from '../src/cli/index.js';
 
-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');
-}
+runCli(process.argv.slice(2)).catch(err => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcoliveira90/pdd",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Patch-Driven Development CLI — safe, resilient and guided code changes",
   "type": "module",
   "bin": {
@@ -14,8 +14,8 @@
   "scripts": {
     "start": "node bin/pdd-pro.js",
     "dev": "node bin/pdd-pro.js",
-    "test": "echo \"No tests yet\"",
-    "lint": "echo \"No lint configured\"",
+    "test": "node --test",
+    "lint": "node ./scripts/lint-js.mjs",
     "prepublishOnly": "npm pack"
   },
   "engines": {

package/src/ai/run-fix-analysis.js

@@ -13,7 +13,14 @@ function extractArgValue(args, name, fallback = null) {
 }
 
 function getIssueFromArgs(args) {
-  const filtered = args.filter(arg => !arg.startsWith('--provider') && !arg.startsWith('--model') && arg !== 'fix' && arg !== '--ai');
+  const filtered = args.filter(
+    arg =>
+      !arg.startsWith('--provider') &&
+      !arg.startsWith('--model') &&
+      !arg.startsWith('--task') &&
+      arg !== 'fix' &&
+      arg !== '--ai'
+  );
   return filtered.join(' ').trim();
 }
 
@@ -138,10 +145,11 @@ export async function runAiFixAnalysis(argv = process.argv.slice(2)) {
   const provider = extractArgValue(argv, '--provider', 'openai');
   const providerConfig = getAiProviderConfig(provider);
   const model = extractArgValue(argv, '--model', providerConfig.defaultModel);
+  const task = extractArgValue(argv, '--task', 'analysis');
   const issue = getIssueFromArgs(argv);
 
   if (!issue) {
-    throw new Error('Missing issue description. Example: pdd fix --ai "login not saving incomeStatus"');
+    throw new Error('Missing issue description. Example: pdd-ai --provider=openai --task=analysis "login not saving incomeStatus"');
   }
 
   const apiKey = process.env[providerConfig.envKey];
@@ -150,7 +158,11 @@ export async function runAiFixAnalysis(argv = process.argv.slice(2)) {
   }
 
   const baseUrl = resolveBaseUrl(providerConfig);
-  const prompt = buildBugfixPrompt({ issue });
+  const prompt = [
+    `Task mode: ${task}`,
+    '',
+    buildBugfixPrompt({ issue })
+  ].join('\n');
 
   let raw;
   if (provider === 'openai') {
@@ -167,6 +179,7 @@ export async function runAiFixAnalysis(argv = process.argv.slice(2)) {
 
   return {
     provider,
+    task,
     model,
     issue,
     result: parsed

package/src/cli/doctor-command.js

@@ -8,26 +8,42 @@ function exists(baseDir, relativePath) {
   return fs.existsSync(path.join(baseDir, relativePath));
 }
 
+function existsAny(baseDir, relativePaths) {
+  return relativePaths.some(relativePath => exists(baseDir, relativePath));
+}
+
 function cursorAdapterInstalled(baseDir) {
-  return (
-    exists(baseDir, '.cursor/rules/pdd.mdc') ||
-    exists(baseDir, '.cursor/commands/pdd.md') ||
-    exists(baseDir, '.cursor/pdd.prompt.md')
-  );
+  return existsAny(baseDir, [
+    '.cursor/rules/pdd.mdc',
+    '.cursor/commands/pdd.md',
+    '.cursor/commands/pdd-recon.md',
+    '.cursor/commands/pdd-fix.md',
+    '.cursor/commands/pdd-feature.md',
+    '.cursor/commands/pdd-verify.md',
+    '.cursor/pdd.prompt.md'
+  ]);
 }
 
 function claudeAdapterInstalled(baseDir) {
-  return (
-    exists(baseDir, '.claude/commands/pdd.md') ||
-    exists(baseDir, '.claude/CLAUDE.md')
-  );
+  return existsAny(baseDir, [
+    '.claude/CLAUDE.md',
+    '.claude/commands/pdd.md',
+    '.claude/commands/pdd-recon.md',
+    '.claude/commands/pdd-fix.md',
+    '.claude/commands/pdd-feature.md',
+    '.claude/commands/pdd-verify.md'
+  ]);
 }
 
 function copilotAdapterInstalled(baseDir) {
-  return (
-    exists(baseDir, '.github/copilot/pdd.prompt.md') ||
-    exists(baseDir, '.github/copilot-instructions.md')
-  );
+  return existsAny(baseDir, [
+    '.github/copilot-instructions.md',
+    '.github/copilot/pdd.prompt.md',
+    '.github/prompts/pdd-recon.prompt.md',
+    '.github/prompts/pdd-fix.prompt.md',
+    '.github/prompts/pdd-feature.prompt.md',
+    '.github/prompts/pdd-verify.prompt.md'
+  ]);
 }
 
 function readVersion(baseDir) {
@@ -90,6 +106,7 @@ export function runDoctor(baseDir = process.cwd(), argv = []) {
   } else {
     console.log('🎉 Templates up to date');
   }
+  console.log('ℹ️ Note: CLI package version and template version are tracked separately.');
 
   if (!adapters.claude && !adapters.cursor && !adapters.copilot) {
     console.log('ℹ️ No IDE adapters installed');

package/src/core/fix-runner.js

@@ -75,11 +75,11 @@ export async function runResilientFixWorkflow({
   }
 
   const changeId = `change-${Date.now()}`;
+  let phase = 'patch-generation';
   setActiveChange(baseDir, changeId, 'in-progress');
 
   try {
-    let phase = 'patch-generation';
-    const patch = generatePatchArtifacts({ issue, baseDir });
+    const patch = generatePatchArtifacts({ issue, baseDir, changeId });
 
     if (!noValidate) {
       phase = 'validation';
@@ -113,7 +113,6 @@ export async function runResilientFixWorkflow({
       files: patch.files
     };
   } catch (error) {
-    const phase = current.status === 'in-progress' ? current.lastPhase || 'unknown' : 'unknown';
     const payload = buildFailurePayload({ issue, changeId, phase, error });
     const artifacts = persistFailureArtifacts(baseDir, payload);
 

package/src/core/patch-generator.js

@@ -18,15 +18,14 @@ function slugify(value) {
     .slice(0, 48);
 }
 
-export function generatePatchArtifacts({ issue, baseDir = process.cwd() }) {
-  const timestamp = Date.now();
-  const changeId = `change-${timestamp}-${slugify(issue || 'update')}`;
-  const changeDir = path.join(baseDir, 'changes', changeId);
+export function generatePatchArtifacts({ issue, baseDir = process.cwd(), changeId = null }) {
+  const resolvedChangeId = changeId || `change-${Date.now()}-${slugify(issue || 'update')}`;
+  const changeDir = path.join(baseDir, 'changes', resolvedChangeId);
 
   const files = [
-    path.join('changes', changeId, 'delta-spec.md'),
-    path.join('changes', changeId, 'patch-plan.md'),
-    path.join('changes', changeId, 'verification-report.md')
+    path.join('changes', resolvedChangeId, 'delta-spec.md'),
+    path.join('changes', resolvedChangeId, 'patch-plan.md'),
+    path.join('changes', resolvedChangeId, 'verification-report.md')
   ];
 
   writeFile(
@@ -34,7 +33,7 @@ export function generatePatchArtifacts({ issue, baseDir = process.cwd() }) {
     `# Delta Spec
 
 ## Change ID
-${changeId}
+${resolvedChangeId}
 
 ## Issue
 ${issue}
@@ -71,7 +70,7 @@ bugfix | feature | refactor-safe | hotfix
     `# Patch Plan
 
 ## Change ID
-${changeId}
+${resolvedChangeId}
 
 ## Issue
 ${issue}
@@ -98,7 +97,7 @@ ${issue}
     `# Verification Report
 
 ## Change ID
-${changeId}
+${resolvedChangeId}
 
 ## Issue
 ${issue}
@@ -119,7 +118,7 @@ pending
   );
 
   return {
-    changeId,
+    changeId: resolvedChangeId,
     changeDir,
     files
   };

package/src/core/pr-manager.js

@@ -1,21 +1,21 @@
 import fs from 'fs';
 import path from 'path';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 
-function exec(command) {
-  execSync(command, { stdio: 'inherit' });
+function runGit(args, baseDir = process.cwd()) {
+  execFileSync('git', args, { stdio: 'inherit', cwd: baseDir });
 }
 
-export async function openPullRequest({ issue, changeId, changeDir }) {
+export async function openPullRequest({ issue, changeId, changeDir, baseDir = process.cwd() }) {
   const branch = `pdd/${changeId}`;
   const title = `fix: ${issue}`;
 
   fs.writeFileSync(path.join(changeDir, 'pr-title.txt'), title);
   fs.writeFileSync(path.join(changeDir, 'pr-body.md'), issue);
 
-  exec(`git checkout -b ${branch}`);
-  exec('git add .');
-  exec(`git commit -m "${title}"`);
+  runGit(['checkout', '-b', branch], baseDir);
+  runGit(['add', '.'], baseDir);
+  runGit(['commit', '-m', title], baseDir);
 
   console.log('PR ready (use IDE to open)');
 }

package/src/core/template-registry.js

@@ -171,7 +171,7 @@ Map the structure of the system.
 ## Hotspots
 - 
 `,
-  '.pdd/version.json': JSON.stringify({ templateVersion: '0.2.3' }, null, 2) + '\n'
+  '.pdd/version.json': JSON.stringify({ templateVersion: PDD_TEMPLATE_VERSION }, null, 2) + '\n'
 };
 
 export const IDE_ADAPTERS = {

package/src/core/validator.js

@@ -1,9 +1,9 @@
 import fs from 'fs';
 import { execSync } from 'child_process';
 
-function runCommand(command) {
+function runCommand(command, baseDir) {
   console.log(`→ ${command}`);
-  execSync(command, { stdio: 'inherit' });
+  execSync(command, { stdio: 'inherit', cwd: baseDir });
 }
 
 export function runValidation(baseDir = process.cwd()) {
@@ -29,7 +29,7 @@ export function runValidation(baseDir = process.cwd()) {
   }
 
   try {
-    commands.forEach(runCommand);
+    commands.forEach(command => runCommand(command, baseDir));
   } catch {
     throw new Error('Validation failed');
   }