Using pdd sync with no arguments to sync up any changes in PRD, architecture, prompts automatically

[sushmitvaish]

Summary

Extend pdd sync to support a global sync mode (no arguments) that detects changes across the full PDD artifact hierarchy and propagates them downward: PRD → architecture.json → prompt files. This is distinct from the current pdd sync <basename> which only syncs a single dev unit (prompt → code/example/test).

Problem

PDD has a layered artifact hierarchy:

PRD (GitHub issue or set of documents)
  ↓
architecture.json (module specs, interfaces, dependencies)
  ↓
Prompt 1, Prompt 2, Prompt 3, ...
  ────────────────────────────────────
  ↓  (current `pdd sync <basename>` handles below this line)
Code, Example, Test  (per prompt)

Changes can originate at any level — a PRD is updated with new requirements, architecture.json is edited to restructure modules, or a prompt is modified with new constraints. Currently, there is no automated way to propagate changes downward through the upper layers. Users must manually identify and update each affected file, which is error-prone and violates PDD's "single source of truth" principle.

Context: Existing Building Blocks

Several existing commands already handle pieces of this problem:

Command	What it does	Relevance to global sync
pdd detect-change PROMPTS... CHANGE_FILE	Identifies which prompts are affected by a change description	Architecture → Prompts: detects which prompts need updating when architecture changes
pdd change --agentic ISSUE_URL	Takes a GitHub issue and propagates changes to prompts	PRD → Prompts: already handles issue-driven prompt updates
pdd sync <basename>	Syncs a single dev unit (prompt ↔ code/example/test)	Below the line: handles the lower-level sync after prompts are updated
pdd update	Back-propagates code changes to prompts	Upward within dev unit: Code → Prompt (final step of dev-unit sync)
architecture_sync.py	Bidirectional sync between <pdd-*> tags and architecture.json	Prompts ↔ Architecture: already handles tag-level sync

Global sync should orchestrate these existing tools rather than reimplementing their logic.

Proposed Solution

pdd sync (no arguments) — Global Sync

When invoked with no basename argument, pdd sync should:

Phase 1: Change Detection

1. Compare current state of PRD source, architecture.json, and all prompt files against stored fingerprints
2. Identify which level(s) have changes and which downstream artifacts are stale

Phase 2: Downward Propagation

3. PRD → Architecture (if PRD changed): Analyze how PRD changes affect architecture.json — add/remove/modify module entries, update interfaces, adjust dependencies. This is an agentic step requiring LLM semantic understanding.
4. Architecture → Prompts (if architecture changed, directly or from step 3): Use pdd detect-change logic to identify affected prompts, then update their <pdd-*> tags, requirements, and dependency sections.

Phase 3: Review Summary

5. Stop and report: Display a summary of all changes made. Do NOT automatically trigger dev-unit sync (prompt → code/example/test).

The user then reviews the changes and manually runs pdd sync <basename> on affected modules.

Why Two-Step (Not Fully Automatic)

The upper-layer sync involves semantic understanding and may produce imperfect results. Users should review prompt changes before triggering code regeneration, which is expensive and destructive (overwrites code files). From the design discussion: "The synchronization process may not be absolutely correct. People may not want to run that automatically."

PRD Source: GitHub Issues

PRD documents are typically GitHub issues (fetched via gh CLI), not local filesystem files. This means change detection for PRDs requires either:

• Tracking the issue's last-modified timestamp or content hash in .pdd/meta/
• Accepting a --issue URL flag to specify which PRD to sync against
• Reading a stored PRD reference from .pddrc or .pdd/ state

This is a key design decision — see Design Questions below.

Concrete Scenarios

Scenario 1: Architecture edited, prompts become stale

# User adds a new module entry to architecture.json
$ vim architecture.json  # add "auth_middleware" module with dependencies

# Global sync detects the change and updates affected prompts
$ pdd sync
Detecting changes...
  ✓ PRD: no changes
  ✗ architecture.json: 1 module added (auth_middleware), 2 modules with updated dependencies
  ✗ Prompts affected: api_router_python.prompt, user_service_python.prompt

Propagating changes...
  → Created: prompts/auth_middleware_python.prompt (new module from architecture)
  → Updated: prompts/api_router_python.prompt (added <pdd-dependency>auth_middleware_python.prompt)
  → Updated: prompts/user_service_python.prompt (updated <pdd-interface> to match architecture)

Review changes, then run: pdd sync <basename> for each affected module

Scenario 2: PRD updated with new requirements

# PRD (GitHub issue) was updated with a new "audit logging" requirement
$ pdd sync --issue https://github.com/org/repo/issues/42
Detecting changes...
  ✗ PRD: 1 new requirement section (audit logging)

Propagating PRD → Architecture...
  → architecture.json: added audit_logger module, updated 3 existing module interfaces

Propagating Architecture → Prompts...
  → Created: prompts/audit_logger_python.prompt
  → Updated: prompts/api_router_python.prompt (added audit logging hook requirement)
  → Updated: prompts/user_service_python.prompt (added audit event requirement)
  → Updated: prompts/order_service_python.prompt (added audit event requirement)

Review changes, then run: pdd sync <basename> for each affected module

Scenario 3: Prompt updated, architecture tags become stale

# User edited a prompt and changed its interface
$ vim prompts/user_service_python.prompt  # changed <pdd-interface> and <pdd-dependency>

$ pdd sync
Detecting changes...
  ✓ PRD: no changes
  ✓ architecture.json: no direct changes
  ✗ Prompts changed: user_service_python.prompt (interface and dependencies modified)

Propagating Prompts → Architecture (upward)...
  → architecture.json: updated user_service entry (interface, dependencies synced from <pdd-*> tags)

No downstream prompts affected.

Relationship to pdd update

pdd update handles upward back-propagation within the dev unit (Code → Prompt). It is the final step in the existing pdd sync <basename> loop. Global sync complements it by handling the upper layers:

         ┌─── Global Sync (this issue) ───┐
         │                                 │
         │   PRD ──→ architecture.json     │    DOWNWARD (agentic)
         │   architecture ──→ Prompts      │    DOWNWARD (detect-change + change)
         │   Prompts ──→ architecture      │    UPWARD  (architecture_sync.py)
         │                                 │
         └─────────────────────────────────┘
                    ↓ user reviews
         ┌─── Dev-Unit Sync (existing) ────┐
         │                                 │
         │   Prompt → Code/Example/Test    │    DOWNWARD (pdd generate)
         │   Code → Prompt (pdd update)    │    UPWARD  (pdd update)
         │                                 │
         └─────────────────────────────────┘

Likely Agentic Implementation

This is likely an agentic task (not purely programmatic) because determining how a PRD change affects architecture and how architecture changes affect prompt requirements involves semantic understanding beyond simple diffing.

The implementation will probably leverage an LLM (via Claude Code CLI, Gemini, or Codex CLI) to analyze diffs, determine downstream impact, and generate updated content for affected files.

Scope

In Scope

• Change detection across PRD, architecture.json, and prompt files
• Downward: PRD → architecture.json → prompt files
• Upward: Prompt <pdd-*> tag changes → architecture.json (leveraging existing architecture_sync.py)
• Summary/report of what changed and what was updated
• Two-step workflow: global sync stops after prompt updates; user manually triggers dev-unit sync

Out of Scope (handled by existing commands)

• Prompt → Code/Example/Test sync (pdd sync <basename>)
• Code → Prompt back-propagation (pdd update)

Suggested Phased Implementation

Phase 1: Architecture ↔ Prompts (simpler, mostly programmatic)

• Detect changes in architecture.json and prompt <pdd-*> tags
• Propagate architecture changes to prompt tags (and vice versa)
• Leverage existing architecture_sync.py and pdd detect-change
• Fingerprint tracking for architecture.json in .pdd/meta/

Phase 2: PRD → Architecture (harder, fully agentic)

• Detect PRD changes (GitHub issue tracking or local PRD files)
• Agentic analysis of how PRD changes affect architecture
• Incremental architecture updates (vs. the existing 11-step from-scratch generation)
• Budget management for expensive agentic runs

Key Files to Understand

File	Purpose
pdd/commands/maintenance.py	Current pdd sync CLI entry point
pdd/sync_main.py	Current sync orchestration (dev-unit level)
pdd/sync_determine_operation.py	State-based operation selection
pdd/detect_change.py	Identifies which prompts are affected by a change
pdd/change_main.py	Applies changes to prompts (manual + agentic modes)
pdd/architecture_sync.py	Bidirectional prompt ↔ architecture.json sync via <pdd-*> tags
pdd/agentic_architecture_orchestrator.py	11-step from-scratch generation (reference for PRD → Arch logic)
pdd/update_main.py	pdd update (code → prompt back-propagation)
.pdd/meta/	Fingerprint storage for change detection

Design Questions to Resolve

1. PRD source: How does global sync know where the PRD is? Options: --issue URL flag, stored reference in .pddrc, local PRD files in a configured directory?
2. Change detection for PRDs: If PRD is a GitHub issue, how do we detect changes? Store content hash? Track last-modified? Re-fetch every time?
3. Dependency graph traversal: Use dependencies field in architecture.json to determine affected prompts? Topological ordering?
4. Conflict resolution: What if a prompt was manually edited AND its parent architecture entry changed?
5. Cost management: Agentic sync across many modules could be expensive ($10-$20+ per run). Budget cap? Confirmation before expensive steps?
6. Convergence: If global sync updates prompts, then dev-unit sync calls pdd update which modifies prompts again, could this loop? How to ensure convergence?
7. Incremental vs. full: Always process everything, or only changed subtrees?

Acceptance Criteria

• pdd sync (no args) detects changes at architecture and prompt levels (Phase 1)
• Architecture changes propagate to affected prompt <pdd-*> tags
• Prompt <pdd-*> tag changes propagate to architecture.json
• User sees a summary of all changes before any dev-unit sync occurs
• Dev-unit sync (code/example/test) is NOT automatically triggered
• Existing pdd sync <basename> behavior is unchanged
• Fingerprint/state tracking extended to cover architecture level
• (Phase 2) PRD changes detected and propagated to architecture.json

[sushmitvaish]

Sushmit Vaish, Target Plan for Feb 19