feat: support agentic sync without architecture.json (#538)

README.md

@@ -29,6 +29,7 @@ For CLI users, PDD also offers powerful **agentic commands** that implement GitH
 - `pdd bug <issue-url>` - Create failing tests for bugs
 - `pdd fix <issue-url>` - Fix the failing tests
 - `pdd generate <issue-url>` - Generate architecture.json from a PRD issue (11-step workflow)
+- `pdd sync <issue-url>` - Identify and sync affected modules from a GitHub issue
 - `pdd test <issue-url>` - Generate UI tests from issue descriptions (9-step workflow)
 
 For prompt-based workflows, the **`sync`** command automates the complete development cycle with intelligent decision-making, real-time visual feedback, and sophisticated state management.
@@ -571,6 +572,7 @@ flowchart TB
 
 ### Agentic Commands (Issue-Driven)
 - **[`change`](#8-change)**: Implement feature requests from GitHub issues (12-step workflow)
+- **[`sync`](#1-sync)**: Identify and sync affected modules from GitHub issues
 - **[`bug`](#14-bug)**: Analyze bugs and create failing tests from GitHub issues
 - **[`fix`](#6-fix)**: Fix failing tests (supports issue-driven and manual modes)
 - **[`test`](#4-test)**: Generate UI tests from GitHub issues (9-step workflow in agentic mode)
@@ -922,6 +924,29 @@ cd frontend && pdd --force sync dashboard     # Uses frontend context with real-
 pdd --context backend --force sync calculator # Explicit context override with visual progress
 ```
 
+**Agentic Mode (Issue-Driven Sync):**
+
+When the positional argument is a GitHub issue URL instead of a basename, `sync` enters agentic mode. It uses an LLM to analyze the issue content, identify which modules need syncing, validate dependencies, and then run `pdd sync` on each affected module in parallel (respecting dependency order).
+
+```bash
+pdd sync https://github.com/owner/repo/issues/123
+```
+
+**How module identification works:**
+- **With `architecture.json`**: The LLM analyzes the issue against the architecture to identify directly affected modules and their transitive dependencies. It also validates and corrects the dependency graph if needed.
+- **Without `architecture.json`**: The system scans the `prompts/` directory for `*_<Language>.prompt` files to build a module catalog. The LLM then selects relevant modules from this catalog based on the issue content. Dependencies are inferred from `<include>` tags in prompt files.
+
+**Prerequisites:**
+- `gh` CLI must be installed and authenticated
+- The project must have a `prompts/` directory with prompt files (with or without `architecture.json`)
+
+**Example:**
+```bash
+# Sync modules affected by a GitHub issue
+# Works with or without architecture.json — modules discovered from prompts/ directory
+pdd sync https://github.com/myorg/myrepo/issues/42
+```
+
 ### 2. generate
 
 Create runnable code from a prompt file. This command produces the full implementation code that fulfills all requirements in the prompt. When changes are detected between the current prompt and its last committed version, it can automatically perform incremental updates rather than full regeneration.

docs/TUTORIALS.md

@@ -511,3 +511,41 @@ If the workflow stops (e.g., PRD needs clarification):
 - Include tech stack preferences explicitly (e.g., "FastAPI + PostgreSQL" vs. leaving it ambiguous)
 - Review the generated `architecture.json` before generating individual module prompts
 - The `context_urls` field in each module entry provides documentation links for code generation
+
+## Method 5: Syncing Modules from a GitHub Issue
+
+If you have a GitHub issue describing a feature or bug, you can use `pdd sync` to automatically identify and sync all affected modules:
+
+```bash
+pdd sync https://github.com/myorg/myrepo/issues/42
+```
+
+### How it works
+
+1. Fetches the issue content (title, description, and comments)
+2. Identifies which modules need syncing using an LLM
+3. Validates the dependency graph
+4. Runs `pdd sync` on each module in dependency order (parallelizing where possible)
+
+### With or without `architecture.json`
+
+- If your project has an `architecture.json`, the LLM uses it to identify affected modules and their dependencies
+- If your project only has prompt files in `prompts/`, the system scans for `*_<Language>.prompt` files to build a module catalog and uses `<include>` tags to infer dependencies
+
+### Prerequisites
+
+1. `gh` CLI installed and authenticated (`gh auth login`)
+2. Prompt files in your `prompts/` directory
+
+### Example workflow
+
+```bash
+# Someone files an issue about improving the calculator module
+# Run agentic sync to update affected modules
+pdd sync https://github.com/myorg/myrepo/issues/99
+
+# The command will:
+# - Analyze the issue
+# - Identify that calculator_python.prompt and its dependents need sync
+# - Run pdd sync on each in the correct order
+```

docs/faq.md

@@ -475,4 +475,8 @@ The AI development landscape has a tool for every project size. PDD's strength i
 
 -   **Small Projects / Demos**: Tools like **Lovable** or **Bolt** are fantastic for getting quick results with minimal setup.
 -   **Medium-Sized Features / Prototyping**: Interactive, chat-based tools like **Cursor** or the **Claude Code** are excellent for iterative refinement and exploration.
--   **Production-Scale, Long-Lived Systems**: **PDD** is the best choice when you need deterministic, maintainable, and version-controlled code generation that can scale with your team and project complexity."*
+-   **Production-Scale, Long-Lived Systems**: **PDD** is the best choice when you need deterministic, maintainable, and version-controlled code generation that can scale with your team and project complexity."*
+
+## Q: Can I use `pdd sync` with a GitHub issue URL if my project doesn't have an `architecture.json`?
+
+Yes. When no `architecture.json` is present, the system scans your `prompts/` directory for `*_<Language>.prompt` files to build a module catalog. The LLM then selects relevant modules based on the issue content, and dependencies are inferred from `<include>` tags in the prompt files. You still get parallel sync with dependency ordering — `architecture.json` is optional, not required.

pdd/agentic_sync.py

@@ -257,9 +257,24 @@ def run_agentic_sync(
         return False, "Failed to load agentic_sync_identify_modules_LLM prompt template", 0.0, ""
 
     arch_json_str = json.dumps(architecture, indent=2) if architecture else "No architecture.json available."
+
+    # Build module catalog from prompts/ directory for LLM context
+    prompts_dir = project_root / "prompts"
+    module_catalog_str = "No prompts/ directory found."
+    if prompts_dir.is_dir():
+        prompt_files = sorted(
+            f.name for f in prompts_dir.rglob("*_*.prompt")
+            if not f.stem.lower().endswith("_llm")
+        )
+        if prompt_files:
+            module_catalog_str = "\n".join(f"- {name}" for name in prompt_files)
+        else:
+            module_catalog_str = "No module prompt files found in prompts/ directory."
+
     prompt = prompt_template.format(
         issue_content=issue_content,
         architecture_json=arch_json_str,
+        module_catalog=module_catalog_str,
     )
 
     if not quiet:

pdd/prompts/agentic_sync_identify_modules_LLM.prompt

@@ -1,3 +1,16 @@
+<pdd-reason>LLM prompt that identifies modules needing sync from a GitHub issue, with or without architecture.json.</pdd-reason>
+
+<pdd-interface>
+{
+  "type": "module",
+  "module": {
+    "functions": [
+      {"name": "identify_modules", "signature": "(issue_content, architecture_json, module_catalog)", "returns": "MODULES_TO_SYNC[], DEPS_VALID, DEPS_CORRECTIONS[]"}
+    ]
+  }
+}
+</pdd-interface>
+
 You are analyzing a GitHub issue to determine which PDD modules need to be synced,
 and validating the architecture.json dependency graph.
 
@@ -7,22 +20,43 @@ and validating the architecture.json dependency graph.
 ## Architecture (architecture.json)
 {architecture_json}
 
+## Available Module Catalog
+This lists all prompt files found in the prompts/ directory. Use this as a reference for valid module names.
+When architecture.json is available, cross-reference this catalog with the architecture metadata.
+When architecture.json is NOT available, this catalog is the primary source of available modules.
+
+{module_catalog}
+
 ## Task 1: Identify Modules
 Based on the issue description, identify which modules (by basename) need `pdd sync`.
 A basename is the module name without the language suffix (e.g., "llm_invoke" for "llm_invoke_python.prompt").
 
 Consider:
 - Modules directly mentioned or affected by the issue
 - Transitive dependencies: if module A depends on B, and B needs sync, A may also need sync
-- Only include modules that exist in the architecture.json
+
+If architecture.json is available (i.e., the Architecture section above contains JSON data):
+- Prefer modules that exist in the architecture.json
+- Use the architecture metadata (reason, dependencies) to determine relevance
+- Cross-reference with the module catalog to ensure selected modules have prompt files
+
+If architecture.json is NOT available (indicated by "No architecture.json available." above):
+- Select modules from the Available Module Catalog above
+- Only include modules that exist in the catalog
+- Use module basenames and filenames to infer relevance to the issue
+- When uncertain, prefer including a module over excluding it (false positives are less costly than false negatives)
 
 ## Task 2: Validate Dependencies
-Review the `dependencies` field for each identified module in architecture.json.
+If architecture.json is available:
+- Review the `dependencies` field for each identified module in architecture.json
 - Are the listed dependencies correct and complete?
 - Are there missing dependencies or incorrect ones?
 - If everything is correct, say DEPS_VALID: true
 - If corrections are needed, output the changes
 
+If architecture.json is NOT available:
+- Output DEPS_VALID: true (no architecture to validate)
+
 ## Output Format
 You MUST output the following markers exactly as shown: