@pcoliveira90/pdd 0.3.0 → 0.4.0

package/README.en.md

@@ -1,60 +1,72 @@
-# 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) Initialize PDD in the repository (if running in primary, PDD auto-creates a linked worktree)
+pdd init --here
 
----
+# 2) Run a fix workflow
+pdd fix "login not saving incomeStatus"
+```
 
-## Core Flow
+## Core Commands
 
-Issue → Recon → Delta Spec → Patch Plan → Change → Verify
+```bash
+pdd init --here
+pdd doctor
+pdd status
+pdd fix "bug description" [--dry-run] [--no-validate] [--open-pr]
+pdd version
+```
 
----
+AI analysis command:
 
-## Principles
+```bash
+pdd-ai --provider=openai --task=analysis "bug description"
+```
 
-- Change-first
-- Evidence before edit
-- Minimal safe delta
-- Root-cause over symptom patch
-- Regression-aware
-- Reuse existing patterns
-- Verifiable outcomes
+## 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
 
-## Structure
+## IDE Alignment
 
-.pdd/
-examples/
+PDD keeps equivalent intents across tools:
 
----
+- Cursor: `.cursor/commands/pdd-*.md`
+- Claude Code: `.claude/commands/pdd-*.md`
+- GitHub Copilot: `.github/prompts/pdd-*.prompt.md`
 
-## Vision
+## Documentation
 
-Make AI-assisted development safe for real-world systems.
+- `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,71 @@
-# 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) Initialize PDD in the repository (if running in primary, PDD auto-creates a linked worktree)
+pdd init --here
+
+# 2) Run a fix workflow
+pdd fix "login not saving incomeStatus"
+```
+
+## Core Commands
 
-## CLI
+```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 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-ai --provider=openai --task=analysis "bug description"
 ```
 
-## Flow
+## 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,72 @@
-# 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) Inicialize o PDD no repositorio (se estiver na principal, o PDD cria worktree vinculada automaticamente)
+pdd init --here
+
+# 2) 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 init
-pdd fix "bug"
+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.4.0",
   "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/cli/index.js

@@ -1,6 +1,7 @@
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
 import { runValidation } from '../core/validator.js';
 import { openPullRequest } from '../core/pr-manager.js';
 import { generatePatchArtifacts } from '../core/patch-generator.js';
@@ -8,7 +9,7 @@ import { runInit } from './init-command.js';
 import { runDoctor } from './doctor-command.js';
 import { runStatus } from './status-command.js';
 import { runResilientFixWorkflow } from '../core/fix-runner.js';
-import { enforceLinkedWorktree } from '../core/worktree-guard.js';
+import { createLinkedWorktree, detectWorktreeContext } from '../core/worktree-guard.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -33,6 +34,44 @@ function parseFixArgs(argv) {
   };
 }
 
+function maybeAutoRelocateToWorktree({
+  cwd,
+  argv,
+  commandName,
+  enabled
+}) {
+  if (!enabled || argv.includes('--allow-main-worktree')) {
+    return false;
+  }
+
+  const context = detectWorktreeContext(cwd);
+  if (!context.isGitRepo || !context.isPrimaryWorktree) {
+    return false;
+  }
+
+  const { worktreePath, branchName } = createLinkedWorktree({
+    baseDir: cwd,
+    commandName
+  });
+
+  console.log(`🔀 Primary worktree detected. Auto-created linked worktree: ${worktreePath}`);
+  console.log(`🪴 Branch: ${branchName}`);
+  console.log('▶️ Continuing command in the new worktree...');
+
+  const result = spawnSync(
+    process.execPath,
+    [process.argv[1], ...argv],
+    { cwd: worktreePath, stdio: 'inherit' }
+  );
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  process.exitCode = typeof result.status === 'number' ? result.status : 1;
+  return true;
+}
+
 export async function runCli(argv = process.argv.slice(2)) {
   const command = argv[0];
   const cwd = process.cwd();
@@ -43,27 +82,27 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
 
   if (command === 'init') {
-    const allowMainWorktree = argv.includes('--allow-main-worktree');
     const mutatesCurrentRepo = argv.includes('--here') || argv.includes('--upgrade');
-    if (mutatesCurrentRepo) {
-      enforceLinkedWorktree({
-        baseDir: cwd,
-        commandName: 'init',
-        allowMainWorktree
-      });
+    if (maybeAutoRelocateToWorktree({
+      cwd,
+      argv,
+      commandName: 'init',
+      enabled: mutatesCurrentRepo
+    })) {
+      return;
     }
     await runInit(argv);
     return;
   }
 
   if (command === 'doctor') {
-    const allowMainWorktree = argv.includes('--allow-main-worktree');
-    if (argv.includes('--fix')) {
-      enforceLinkedWorktree({
-        baseDir: cwd,
-        commandName: 'doctor --fix',
-        allowMainWorktree
-      });
+    if (maybeAutoRelocateToWorktree({
+      cwd,
+      argv,
+      commandName: 'doctor-fix',
+      enabled: argv.includes('--fix')
+    })) {
+      return;
     }
     runDoctor(cwd, argv);
     return;
@@ -75,7 +114,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
 
   if (command === 'fix') {
-    const { issue, openPr, dryRun, noValidate, allowMainWorktree } = parseFixArgs(argv);
+    const { issue, openPr, dryRun, noValidate } = parseFixArgs(argv);
 
     if (!issue) {
       console.error('❌ Missing issue description.');
@@ -83,11 +122,14 @@ export async function runCli(argv = process.argv.slice(2)) {
       process.exit(1);
     }
 
-    enforceLinkedWorktree({
-      baseDir: cwd,
+    if (maybeAutoRelocateToWorktree({
+      cwd,
+      argv,
       commandName: 'fix',
-      allowMainWorktree
-    });
+      enabled: true
+    })) {
+      return;
+    }
 
     console.log('🔧 PDD Fix Workflow');
     console.log(`Issue: ${issue}`);
@@ -143,8 +185,8 @@ export async function runCli(argv = process.argv.slice(2)) {
     console.log('  pdd version   (or: pdd --version, pdd -v)                        Show CLI version');
     console.log('');
     console.log('Worktree policy:');
-    console.log('  Mutating commands require linked git worktree by default.');
-    console.log('  Override intentionally with --allow-main-worktree.');
+    console.log('  Mutating commands auto-create and use a linked git worktree when needed.');
+    console.log('  Use --allow-main-worktree only if you intentionally want to run in primary.');
     console.log('');
     console.log('AI command (official binary):');
     console.log('  pdd-ai [--provider=openai|claude|openrouter] [--task=analysis|build|test|review] [--model=<id>] "issue"');

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');
   }

package/src/core/worktree-guard.js

@@ -1,4 +1,5 @@
-import { execSync } from 'child_process';
+import fs from 'fs';
+import { execSync, execFileSync } from 'child_process';
 import path from 'path';
 
 function runGit(command, baseDir) {
@@ -9,7 +10,7 @@ function normalize(p) {
   return path.resolve(String(p || '')).toLowerCase();
 }
 
-function detectWorktreeContext(baseDir = process.cwd()) {
+export function detectWorktreeContext(baseDir = process.cwd()) {
   try {
     const topLevel = runGit('git rev-parse --show-toplevel', baseDir);
     const gitDir = runGit('git rev-parse --git-dir', baseDir);
@@ -31,6 +32,45 @@ function detectWorktreeContext(baseDir = process.cwd()) {
   }
 }
 
+function slug(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+}
+
+export function createLinkedWorktree({
+  baseDir = process.cwd(),
+  commandName = 'change'
+}) {
+  const context = detectWorktreeContext(baseDir);
+  if (!context.isGitRepo) {
+    throw new Error('Current directory is not a git repository.');
+  }
+
+  const topLevel = context.topLevel;
+  const repoName = slug(path.basename(topLevel)) || 'repo';
+  const commandSlug = slug(commandName) || 'change';
+  const stamp = Date.now();
+  const branchName = `feature/pdd-auto-${commandSlug}-${stamp}`;
+
+  const worktreesRoot = path.join(path.dirname(topLevel), 'pdd-worktrees');
+  fs.mkdirSync(worktreesRoot, { recursive: true });
+  const worktreePath = path.join(worktreesRoot, `${repoName}-${commandSlug}-${stamp}`);
+
+  execFileSync(
+    'git',
+    ['worktree', 'add', '-b', branchName, worktreePath, 'HEAD'],
+    { cwd: topLevel, stdio: 'pipe' }
+  );
+
+  return {
+    worktreePath,
+    branchName
+  };
+}
+
 export function enforceLinkedWorktree({
   baseDir = process.cwd(),
   commandName = 'command',