If the project doesn't have an architecture.json file, agentic sync should still be able to pick up relevant files

[jiaminc-cmu]

The current agentic sync is too reliant on architecture.json file's guidance.
It should be able to pickup files even when there is no architecture.json according to user's requirement specified in the issue content

[prompt-driven-github]

🚀 Job Queued!

Job ID: yA3lN7WilHEpNuBHFbUi
Triggered by: @jiaminc-cmu
Label: enhancement

View Live Progress
Model: pdd-opus (claude-opus-4-6)

[prompt-driven-github]

Step 1: Duplicate Check

Status: No duplicates found

Search Performed

• Searched for: "architecture.json", "agentic sync", "pick up relevant files", "file discovery", "without architecture", "no architecture", "agentic file selection"
• Issues reviewed: 15 closely evaluated out of ~60 search results across all queries

Findings

No existing issue requests the same change. The closest related issue is:

• Using pdd sync with no arguments to sync up any changes in PRD, architecture, prompts automatically #537 ("Using pdd sync with no arguments to sync up any changes in PRD, architecture, prompts automatically") — This is about orchestrating a global sync across the full PRD → architecture → prompts hierarchy. While it touches on architecture.json, its focus is on propagating changes between layers, not on enabling agentic sync to function without an architecture.json file. Issue If the project doesn't have an architecture.json file, agentic sync should still be able to pick up relevant files #538 is complementary: Using pdd sync with no arguments to sync up any changes in PRD, architecture, prompts automatically #537 assumes architecture.json exists and focuses on syncing it; If the project doesn't have an architecture.json file, agentic sync should still be able to pick up relevant files #538 addresses the case where it doesn't exist at all.

Other reviewed issues (#531, #245, #318, #85, #520) address distinct concerns (agentic fix mode, context files for agentic fallback, context map sampling, template tag generation, and docs-only changes respectively).

This is a new enhancement request to make agentic sync less dependent on architecture.json by enabling it to identify relevant project files based on the issue content alone.

---

Proceeding to Step 2: Documentation Check

[prompt-driven-github]

Step 2: Documentation Check

Status: Partially Implemented

Documentation Reviewed

• README.md — agentic sync documentation, pdd sync usage, pdd generate architecture.json workflow
• pdd/agentic_sync.py — main agentic sync entry point (365 lines)
• pdd/agentic_sync_runner.py — parallel sync runner (815 lines)
• pdd/prompts/agentic_sync_identify_modules_LLM.prompt — LLM prompt template for module identification
• pdd/load_prompt_template.py — prompt template loading logic
• docs/sync_architecture_analysis.md — sync system architecture analysis
• pdd/sync_order.py — dependency graph building and topological sort

Findings

The codebase has partial infrastructure for handling missing architecture.json, but the feature is effectively non-functional due to a critical gap in the LLM prompt design.

What exists today:

1. Graceful detection (agentic_sync.py:250-252): When architecture.json is missing, a yellow warning is printed and the code continues.

2. Fallback dependency graph (agentic_sync.py:310-314): When no architecture exists, the dependency graph is built by scanning prompt files for <include> tags instead of reading architecture.json entries.

3. LLM receives "No architecture.json available." (agentic_sync.py:259): The string is passed as the architecture context to the LLM.

What's broken — the critical gap:

4. The LLM prompt explicitly requires architecture.json (agentic_sync_identify_modules_LLM.prompt:17):

   "Only include modules that exist in the architecture.json"

   When the LLM receives "No architecture.json available." as the architecture context, it has no list of modules to choose from. The prompt gives it no alternative strategy for discovering modules (e.g., scanning the prompts/ directory, using file paths mentioned in the issue, or inferring module names from the codebase).

5. Empty module list = immediate failure (agentic_sync.py:286-287): If the LLM returns no modules (which is the expected outcome given the prompt constraint), run_agentic_sync returns (False, "LLM identified no modules to sync", ...) immediately.

In summary: The plumbing handles missing architecture.json (dependency graph fallback, graceful warnings), but the LLM module identification step — which is the core intelligence of agentic sync — is entirely dependent on architecture.json content. Without it, the LLM has no guidance on what modules exist and the workflow fails.

What needs to change

To make agentic sync work without architecture.json, the system needs:

1. An alternative module discovery strategy when architecture.json is absent — e.g., listing prompt files from the prompts/ directory, scanning .pddrc for configured paths, or using the issue content to infer relevant files
2. An updated LLM prompt (or a second prompt variant) that can identify relevant modules from a file listing rather than an architecture.json manifest
3. The prompt should leverage the issue content more heavily to determine which files/modules are relevant based on user requirements

---

Proceeding to Step 3: Identify Dev Units

[prompt-driven-github]

Step 3: Research & Clarification

Status: Research Complete

Summary

Researched best practices for LLM-based file/module discovery without a manifest file, convention-over-configuration patterns, conditional prompt design, and graceful degradation strategies. The core finding is that the fix should follow the convention-over-configuration pattern — scanning the prompts/ directory to discover available modules and providing that listing to the LLM as an alternative to architecture.json — combined with conditional prompt instructions that adapt based on which context is available.

Research Findings

Technical Background

1. Convention over Configuration (CoC): Frameworks like Rails, pytest, and Spring Boot demonstrate that directory/naming conventions can replace explicit manifests for module discovery. PDD already follows this pattern — prompt files use <basename>_<language>.prompt naming — so the prompts/ directory is the implicit module registry. The existing build_dependency_graph() function in sync_order.py:110-153 already scans for *_*.prompt files and extracts basenames, proving this approach is viable.

2. Two-Phase LLM File Selection (CGRAG pattern): Research on code-generation agents shows a two-pass approach is effective: (1) present a directory listing and ask the LLM to identify which modules are relevant to the issue, then (2) use those selections for deeper processing. This maps directly to the current architecture — the module identification LLM call is already Phase 1; we just need to give it a file listing when architecture.json is absent.

3. Conditional Prompt Instructions: Best practices for LLM prompts recommend embedding if...then conditional rules directly in natural language prompts, so the model can adapt its behavior based on what context is available. This avoids needing two entirely separate prompt templates.

Best Practices

1. Provide a curated directory listing, not raw filesystem access. Research consistently shows LLMs perform better with a structured, filtered file listing (excluding .git, __pycache__, LLM prompts, etc.) rather than a raw ls dump. The existing extract_module_from_include() function already handles this filtering logic.

2. Include module metadata when available. Even without architecture.json, each prompt file contains useful context: its filename implies the module name and language, and <include> tags reveal dependencies. Providing this lightweight metadata helps the LLM make better module selection decisions.

3. Use default/fallback values in prompt templates. Template systems (Jinja, PromptL, LangChain) recommend providing fallback paths when primary data sources are unavailable, rather than creating entirely separate templates. A single prompt with conditional sections is more maintainable than two separate prompts.

4. Leverage issue content heavily. When the structured architecture manifest is missing, the issue content becomes the primary signal for module identification. The prompt should instruct the LLM to match keywords, file paths, and module names mentioned in the issue against the discovered file listing.

Similar Implementations

• PDD's own pdd update command (repository-wide mode): When run without arguments, it scans the entire repository to find all code/prompt pairs. This is the same pattern needed here — scanning prompts/ for available modules.
• pytest auto-discovery: Finds test files by naming convention (test_*.py) without any manifest. PDD can similarly discover modules by convention (*_<language>.prompt).
• Artemis (arXiv 2025): Automatically analyzes codebase structure to identify optimizable components without requiring manifests, using semantic search over directory listings.
• Claude Code's agentic approach: Makes parallel tool calls to understand directory structure and key files, then selects relevant ones based on the task description.

Security/Edge Cases

1. Empty prompts/ directory: If no prompt files exist, the system should fail gracefully with a clear message ("No prompt files found in prompts/ directory") rather than passing an empty list to the LLM.
2. Very large prompts/ directory: If there are hundreds of prompt files, the full listing may consume significant context window. Consider capping at a reasonable limit (e.g., 200 modules) or truncating with a note.
3. Ambiguous module matching: Without architecture.json's reason and description fields, the LLM has less context for matching issue content to modules. The prompt should instruct the LLM to be conservative and explain its reasoning.
4. Dependency validation should be skipped: Task 2 (dependency validation/correction) in the current prompt only makes sense when architecture.json exists. The no-architecture path should skip this entirely and set DEPS_VALID: true.
5. Module name format consistency: The LLM might return names with or without language suffixes. The existing extract_module_from_include() stripping logic at agentic_sync.py:292-296 already handles this, so no additional work needed.

Refined Specifications

Based on the research, here are clarified requirements:

1. Scan prompts/ directory for available modules when architecture.json is absent. Reuse the existing build_dependency_graph() logic from sync_order.py or a simplified version that just collects basenames and filenames. This is consistent with how pdd update works in repository-wide mode.

2. Update the LLM prompt template (agentic_sync_identify_modules_LLM.prompt) with conditional instructions:

   • When architecture.json is provided: current behavior (select from architecture, validate deps)
   • When a directory listing is provided instead: select modules based on filename/basename matching against issue content; skip dependency validation (DEPS_VALID: true)
   • Remove or conditionalize the line "Only include modules that exist in the architecture.json"

3. Construct a module listing string in agentic_sync.py (around line 259) when architecture is None. Format: one module per line with basename and filename, e.g.:

   Available modules (from prompts/ directory):
   - order_api (order_api_Python.prompt)
   - order_models (order_models_Python.prompt)
   - checkout_page (checkout_page_React.prompt)
   

4. Handle edge case: no prompt files found. Return early with a clear error message instead of sending an empty listing to the LLM.

5. Skip dependency correction (_apply_architecture_corrections) when architecture is None — this is already handled at agentic_sync.py:302 but the prompt should also tell the LLM not to attempt corrections.

6. The {architecture_json} placeholder should receive either the JSON content (existing behavior) OR the directory listing string (new behavior), keeping the template interface simple with no new placeholders needed.

Alternative Approaches Considered

• Two separate prompt templates (one for architecture.json, one for directory listing): Pros — cleaner separation of concerns, each prompt fully optimized for its context. Cons — code duplication, two templates to maintain, more complex dispatch logic. Not recommended — the conditional-instructions approach within a single template is simpler and more maintainable.

• Embedding file content/headers in the listing: Pros — gives LLM richer context for matching (e.g., first few lines of each prompt file). Cons — significantly increases token usage, potentially exceeding context limits for large projects, slower. Not recommended — basename + filename is sufficient for the initial module identification pass; the actual sync step reads the full files.

• Semantic search / embeddings over prompt files: Pros — more accurate matching for large codebases. Cons — requires embedding infrastructure, adds complexity and latency, overkill for the typical PDD project size. Not recommended for this change — could be a future enhancement.

• Single conditional prompt template with directory listing fallback (recommended): Pros — minimal code changes, reuses existing infrastructure, single template to maintain, graceful degradation. Cons — slightly longer prompt template. This is the approach that best fits PDD's existing architecture.

Recommended Approach

Use a single updated prompt template with conditional sections and a directory-scanned module listing as the fallback. Specifically:

1. In agentic_sync.py, when architecture is None, scan prompts/ to build a formatted module listing string.
2. Pass that listing through the existing {architecture_json} placeholder (repurposed for both cases).
3. Update the prompt template with conditional instructions: "If architecture.json is provided, [current behavior]. If a directory listing is provided instead, [select from listed modules, skip dep validation]."
4. The existing fallback dependency graph (build_dependency_graph via <include> tag scanning at lines 311-314) remains unchanged for the execution phase.

This approach requires changes to only two files (agentic_sync.py and the prompt template), follows the convention-over-configuration pattern, and maintains backward compatibility with the architecture.json path.

---

Proceeding to Step 4: Documentation Changes

[prompt-driven-github]

Step 3: Research & Clarification

Status: Research Complete

Summary

Researched patterns for LLM-driven module discovery without a manifest file, conditional prompt branching, graceful degradation with fallback file scanning, and context engineering best practices. The findings confirm that a conditional prompt variant combined with directory-scanning-based module discovery is the correct approach, with well-established patterns to draw from.

Research Findings

Technical Background

The core problem is a graceful degradation scenario: when architecture.json (the manifest) is missing, the system should fall back to discovering modules from the prompts/ directory structure using naming conventions — a classic convention-over-configuration pattern.

Key concepts at play:

1. Convention over Configuration: Frameworks like Rails and Spring Boot popularized this — when explicit config is absent, use predictable naming/structure conventions. PDD already follows this: prompt files are named {module}_{Language}.prompt, which is a parseable convention.

2. Context Engineering vs. Prompt Engineering: Modern LLM systems distinguish between static prompts and dynamic context systems. The architecture.json content is context injected into the prompt. When that context changes form (from structured JSON to a directory listing), the prompt instructions must adapt accordingly (Context Engineering Guide).

3. Conditional Prompt Branching: A well-documented LLM pattern where the system detects available context and routes to the appropriate prompt variant. Rather than one prompt trying to handle both cases (with/without architecture.json), two specialized prompt paths produce better results (llm-exe Conditional Logic).

Best Practices

1. Structured context outperforms raw dumps: Research consistently shows that presenting file listings with metadata (basename, language, inferred purpose from filename) produces better LLM results than raw directory listings. The prompt should format discovered modules as a structured list, not just filenames (Context Engineering — Addyo).

2. Two-pass LLM approach (CGRAG pattern): For large codebases, a two-pass approach works well — first ask the LLM what modules are relevant, then provide detailed context for those. PDD already does this (identify modules → sync each). The gap is only in the first pass needing an alternative context source (CGRAG for Large Codebases).

3. Include first lines of prompt files: Tools like code2prompt and repomix show that including brief content excerpts (not just filenames) significantly improves LLM accuracy in identifying relevant modules (code2prompt).

4. Hierarchical discovery: AGENTS.md and similar patterns show that combining root-level metadata with per-directory context produces the best results. PDD can replicate this by combining the prompts/ directory listing with the <include> dependency information already extractable from prompt files (AGENTS.md, OpenAI Codex AGENTS.md Guide).

Similar Implementations

1. Mastra (AI Agent Framework): Supports both manifest-based and direct file-linking approaches. When no manifest exists, it links directly to source files and generates a table of contents dynamically (Mastra Blog).

2. Continue.dev Agent Mode: Uses built-in tools (file exploration, code search, Git integration) to navigate codebases without requiring pre-configured indexes — pure heuristic discovery (Continue Docs).

3. Codex CLI Fallback: Searches for config files from root to current directory, with configurable fallback filenames. When none found, falls back to heuristic exploration (OpenAI Codex).

4. Harvard LMPL '25 Research: Proposes that LLMs should automatically generate and consider high-level artifacts (like dependency graphs) as part of their context alongside code — exactly the pattern PDD can adopt when architecture.json is missing (The Modular Imperative).

Security/Edge Cases

1. Empty prompts/ directory: If neither architecture.json nor any prompt files exist, the system should fail fast with a clear error message rather than sending a vacuous prompt to the LLM.

2. Mixed state: A project might have architecture.json that is outdated or only partially covers modules in prompts/. Consider whether to merge both sources or prefer one over the other.

3. Very large prompt directories: If prompts/ contains hundreds of files, passing all of them to the LLM could exceed context limits or degrade quality. A truncation or summarization strategy should be considered (e.g., top-level listing only, exclude deeply nested files).

4. Ambiguous module names: Without architecture.json's reason and description fields, the LLM has less semantic context. Including the first 1-3 lines of each prompt file as a description excerpt mitigates this.

5. Non-standard prompt filenames: Files that don't follow the {name}_{Language}.prompt convention should be gracefully handled (included with a note, or excluded with a warning).

6. LLM hallucinating modules: Without a constrained list from architecture.json, the LLM might invent module names. The prompt must explicitly instruct the LLM to only return basenames that correspond to actual files in the listing.

Refined Specifications

Based on the research, here are clarified requirements:

1. Scan prompts/ directory when architecture.json is absent: Use build_dependency_graph() from sync_order.py (which already exists) to discover all modules. Extract basenames via extract_module_from_include() for each *_*.prompt file (excluding _LLM files).

2. Build structured module listing for the LLM: Format discovered modules as a structured list including: basename, full filename, language suffix, and (optionally) the first non-empty line of the prompt file as a description excerpt. This gives the LLM enough context to make informed module selection.

3. Create a conditional/variant LLM prompt: Either (a) modify the existing agentic_sync_identify_modules_LLM.prompt to have conditional instructions based on whether architecture.json is present, or (b) create a second prompt template agentic_sync_identify_modules_no_arch_LLM.prompt for the no-architecture case. The variant should:

   • Replace "Only include modules that exist in the architecture.json" with "Only include modules that exist in the Available Modules listing below"
   • Skip Task 2 (dependency validation) since there's no architecture.json to validate
   • Emphasize using issue content keywords to match against module names and descriptions

4. Pass discovered module listing into the prompt: Add a new template variable (e.g., {available_modules}) that receives the formatted module listing when architecture.json is absent.

5. Validate LLM output against actual files: After parsing MODULES_TO_SYNC, verify each basename corresponds to an actual prompt file in prompts/. Discard any hallucinated module names with a warning.

6. Handle edge case of zero discovered modules: If prompts/ has no valid prompt files, fail with a clear message: "No prompt files found in prompts/ directory and no architecture.json available."

Alternative Approaches Considered

• Single unified prompt with conditional sections: Embed both code paths in one prompt template using markers like {if_architecture}...{endif}. Pros: Single file to maintain. Cons: Makes the prompt harder to read and test; LLMs perform better with focused, non-branching instructions.

• Two separate prompt templates (recommended): Create agentic_sync_identify_modules_no_arch_LLM.prompt alongside the existing one. Pros: Each prompt is focused and testable; easier to tune independently. Cons: Two files to maintain, but they share minimal overlap.

• Semantic search over prompt file contents: Use embedding-based search to find relevant modules based on issue content similarity. Pros: Most accurate matching. Cons: Requires embedding infrastructure, adds complexity and latency; overkill for typical project sizes (< 100 modules).

• Include full prompt file contents in LLM context: Pass entire prompt file contents to the LLM for maximum context. Pros: Best possible context. Cons: Quickly exceeds token limits for projects with many modules; expensive.

Recommended Approach

Use a two-prompt-template strategy with directory-scanned module discovery:

1. In agentic_sync.py, when architecture is None, scan prompts/ to build a structured module listing (basename, filename, language, first-line excerpt).
2. Load the new agentic_sync_identify_modules_no_arch_LLM.prompt template instead of the standard one.
3. Pass the module listing as {available_modules} context to the LLM.
4. The new prompt instructs the LLM to select from the available modules list (not architecture.json), skip dependency validation, and use issue content to identify relevant modules.
5. After LLM response, validate returned basenames against actual files.
6. The existing fallback dependency graph (include-based) already handles the rest of the workflow correctly.

This approach follows the convention-over-configuration pattern, implements clean graceful degradation, and leverages existing infrastructure (build_dependency_graph, extract_module_from_include) while only requiring changes to: (a) agentic_sync.py (module discovery + prompt selection logic), and (b) a new prompt template file.

---

Proceeding to Step 4: Documentation Changes

[prompt-driven-github]

Step 3: Research & Clarification

Status: Research Complete

Summary

Researched best practices for LLM-driven module discovery without manifest files, dynamic context injection for prompt templates, and graceful degradation patterns. The key finding is that the codebase already has most of the infrastructure needed — the primary gap is in the LLM prompt template and the module discovery step that bridges filesystem scanning to LLM-based identification.

Research Findings

Technical Background

Convention over Configuration / Graceful Degradation:
The established software pattern of "convention over configuration" (popularized by Rails, Spring Boot, etc.) applies directly here. When a manifest (architecture.json) is absent, the system should fall back to convention-based discovery — scanning the prompts/ directory for *_<Language>.prompt files using the naming convention already enforced by extract_module_from_include() in sync_order.py. This is a well-understood graceful degradation pattern: transform the hard dependency on architecture.json into a soft dependency by providing an alternative discovery path.

Context Engineering (not just Prompt Engineering):
Modern best practices emphasize treating LLM prompts as dynamically assembled pipelines rather than static text. The key principle from context engineering research: "What inputs does this system need? How do I get those and feed them in? In what format? At what time?" For this feature, when architecture.json is missing, the prompt should dynamically inject a directory listing of available modules instead, giving the LLM equivalent (if reduced) context to work with.

Filesystem as Context Interface:
Research from Vercel and LlamaIndex shows that modern AI coding agents increasingly treat the filesystem itself as the primary context interface — using directory structure, file naming conventions, and file content scanning to understand project structure. This aligns with PDD's existing build_dependency_graph() function which already scans <include> tags from prompt files.

Best Practices

1. Two-tier prompt strategy: Use a single prompt template with conditional sections (e.g., {% if architecture_json %}...{% else %}...{% endif %}) or a variant prompt. The architecture.json branch instructs the LLM to select from known modules; the no-architecture branch provides a file listing and asks the LLM to identify relevant modules based on filenames, directory structure, and issue content.

2. Provide sufficient context in the fallback path: When no architecture.json exists, the LLM needs:

   • A list of all discovered module basenames (from scanning prompts/)
   • Optionally, the first few lines or <pdd-reason> tags from each prompt file (to give the LLM semantic understanding of what each module does)
   • The full issue content (already provided)

3. Don't over-rely on LLM for structural tasks: For the no-architecture case, consider a hybrid approach: use filesystem scanning to enumerate candidates, then use the LLM to filter/rank them based on issue relevance. This is more reliable than asking the LLM to discover modules from scratch.

4. Preserve the existing architecture.json path: The current flow should remain the primary/preferred path. The no-architecture fallback should be additive, not a replacement.

Similar Implementations

• Claude Code / Cursor: Both tools scan the filesystem when no explicit manifest exists, using ls, grep, and file reading to build context dynamically. They rely on AGENTS.md / CLAUDE.md as optional guidance but function without them.
• DeepCode (arxiv 2512.07921): Uses "blueprint distillation" and "stateful code memory" to build repository understanding without requiring pre-existing manifests — scanning file structure and content to build an internal model.
• GitHub Copilot Agent: Uses .instructions.md files as optional context but also scans directory structure when they're absent, building context from file names and content.

Security/Edge Cases

1. Prompt injection via issue content: Issue content is already escaped with _escape_format_braces(), but when providing a file listing to the LLM, ensure filenames don't contain prompt injection payloads. The existing extract_module_from_include() function validates against known language suffixes, which provides natural sanitization.

2. Large project directories: A project with hundreds of prompt files could exceed the LLM context window if all are included. Implement a max modules cap (e.g., 50-100 module names) or use a two-pass approach: first pass lists basenames only, second pass reads descriptions of top candidates.

3. Empty prompts directory: If no prompts/ directory exists or contains no valid prompt files, the system should fail gracefully with a clear error message rather than sending an empty context to the LLM.

4. Ambiguous module names: Without architecture.json's reason field, the LLM must infer module purpose from basename alone. Module names like utils or helpers are ambiguous. Including <pdd-reason> tag content (if available) from prompt files mitigates this.

5. No matching modules found: Even after fallback discovery, the LLM may identify zero relevant modules. The error message at agentic_sync.py:286-287 should differentiate between "no architecture.json and no modules found" vs "architecture.json present but no modules matched."

Refined Specifications

Based on the research, here are clarified requirements:

1. Module discovery fallback: When architecture.json is absent, scan the prompts/ directory (recursively) for *_<Language>.prompt files using build_dependency_graph() or a similar mechanism. Extract basenames via extract_module_from_include(). This infrastructure already exists in sync_order.py:110-153.

2. Variant LLM prompt section: Modify agentic_sync_identify_modules_LLM.prompt to handle two cases:

   • With architecture.json: Current behavior (select from modules in architecture.json, validate dependencies)
   • Without architecture.json: Provide a list of discovered module basenames (with optional descriptions from <pdd-reason> tags), instruct the LLM to identify relevant modules from this listing based on issue content. Skip dependency validation (Task 2) since there's no dependency manifest to validate.

3. Enrich fallback context: For the no-architecture path, build a lightweight module catalog: {basename: reason_text} by scanning <pdd-reason> tags from prompt files. This gives the LLM semantic context beyond just filenames.

4. Update response parsing: The _parse_llm_response() function should handle the case where DEPS_VALID and DEPS_CORRECTIONS are absent (since dependency validation is skipped in the no-architecture path). Currently it defaults deps_valid = True, which is correct.

5. Preserve existing behavior: The architecture.json path must remain unchanged. All changes should be additive — only activating when architecture is None.

Alternative Approaches Considered

• Approach A — Prompt-only fix (minimal): Only modify the LLM prompt template to remove the "Only include modules that exist in the architecture.json" constraint when architecture.json is absent, passing the raw file listing instead. Pros: Minimal code change (1 file). Cons: LLM has minimal context to work with (just basenames), may produce unreliable results for large projects.

• Approach B — Hybrid filesystem scan + LLM filtering (recommended): Scan prompts/ to build a module catalog (basename + optional reason), inject this into a conditional section of the LLM prompt, let the LLM filter based on issue relevance. Pros: Leverages existing infrastructure (build_dependency_graph, extract_module_from_include), gives LLM actionable context, reliable for medium-sized projects. Cons: Slightly more code (build catalog, update prompt template, update agentic_sync.py).

• Approach C — Full auto-generation of architecture.json: When architecture.json is missing, generate one dynamically by scanning all prompt files and their <include> / <pdd-dependency> tags, then proceed with the existing flow. Pros: Cleanest long-term solution, reuses all existing architecture.json-based logic. Cons: Most complex, risk of generating incorrect metadata, adds latency, and deviates from the user's expectation that the system works without architecture.json.

Recommended Approach

Approach B — Hybrid filesystem scan + LLM filtering. This involves three targeted changes:

1. agentic_sync.py (~15 lines): When architecture is None, scan prompts/ to build a module catalog (basenames + reasons). Pass this catalog string to the prompt template instead of "No architecture.json available.".

2. agentic_sync_identify_modules_LLM.prompt (~15 lines): Add a conditional section that replaces Task 1's "Only include modules that exist in the architecture.json" with "Select from the following discovered modules" and replaces Task 2 with "Dependency validation is skipped (no architecture.json)".

3. agentic_sync.py (~3 lines): Adjust the error message at line 286-287 to provide more context in the no-architecture case.

This approach is minimal, leverages existing infrastructure, and maintains backward compatibility with the architecture.json path.

---

Proceeding to Step 4: Documentation Changes

[prompt-driven-github]

Step 4: Requirements Clarity Check

Status: Requirements Clear

Clarity Assessment

Aspect	Status
Problem statement	✅ Clear
Expected outcomes	✅ Defined
Scope	✅ Bounded
Edge cases	✅ Addressable

Understanding Summary

When architecture.json is absent, agentic sync should discover available modules by scanning the prompts/ directory (reusing existing build_dependency_graph() infrastructure) and provide that module catalog to the LLM so it can identify which modules are relevant to the issue — instead of the current behavior where the LLM prompt instructs it to only select from architecture.json, causing it to return an empty list and fail.

Assumptions Made

• Module catalog source: When architecture.json is missing, the prompts/ directory scan (already implemented in sync_order.py:build_dependency_graph()) is the correct fallback for discovering available modules. No other discovery mechanisms (e.g., scanning source directories or config files) are needed.
• LLM prompt approach: A conditional section within the existing agentic_sync_identify_modules_LLM.prompt template is preferred over creating a separate prompt file. The LLM will receive a flat list of discovered module basenames instead of the structured architecture.json data.
• Dependency validation (Task 2): When architecture.json is absent, the LLM's "Validate Dependencies" task will be skipped or adapted to only work with include-based dependencies, since there is no architecture file to correct.
• Empty prompts/ directory: If no modules are discovered from the directory scan, the system should fail with a clear error message rather than sending the LLM an empty catalog.
• Existing fallback graph logic is preserved: The existing code at agentic_sync.py:310-314 that builds dependency graphs from <include> tags when architecture.json is absent will continue to work as-is; only the module identification step (LLM prompt) needs updating.

---

Proceeding to Step 5: Documentation Changes

[prompt-driven-github]

Step 5: Documentation Changes

Status: Documentation Updates Required

Summary

The pdd sync <github_issue_url> (agentic sync) mode is completely undocumented in the README, tutorials, and FAQ. The feature change (making agentic sync work without architecture.json) requires documenting: (1) the agentic sync mode itself, (2) the new fallback behavior when architecture.json is absent, and (3) that projects without architecture.json can still use issue-driven sync.

Files to Update

1. README.md

Section: Introduction (Lines 27-34) — Agentic commands list

Change: Add pdd sync <issue-url> to the agentic commands list
Draft content:

For CLI users, PDD also offers powerful **agentic commands** that implement GitHub issues automatically:
- `pdd change <issue-url>` - Implement feature requests (12-step workflow)
- `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)

Section: Command Reference → ### 1. sync (Line 775) — Add Agentic Mode subsection

Change: Add an "Agentic Mode" subsection after the existing basename-mode documentation (similar to how generate, test, and change document their agentic modes)
Draft content:

**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:

# Sync modules affected by a GitHub issue (with architecture.json)
pdd sync https://github.com/myorg/myrepo/issues/42

# Works equally well without architecture.json — modules discovered from prompts/ directory
pdd sync https://github.com/myorg/myrepo/issues/42

##### Section: Agentic Commands list (Lines 572-576)
**Change:** Add sync to the agentic commands list  
**Draft content:**
```markdown
### 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)

---

2. docs/TUTORIALS.md

New section: After "Method 4: Generating Architecture from a PRD" (after line ~513)

Change: Add a tutorial section for issue-driven sync
Draft content:

### 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 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:

# 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

---

#### 3. `docs/faq.md`

##### New Q&A entry in the appropriate section
**Change:** Add FAQ entry about using PDD without `architecture.json`  
**Draft content:**
```markdown
### 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.

---

Files to Create

• None required. The changes fit naturally into existing documentation files.

No Changes Needed

• docs/prompting_guide.md — This guide focuses on writing prompts, not on the sync command workflow. The Architecture Metadata Tags section describes tags that sync to architecture.json, but doesn't need to document what happens when architecture.json is absent (that's a runtime behavior, not a prompt-writing concern).
• CONTRIBUTING.md — No changes needed; this feature doesn't change contribution workflows.
• docs/whitepaper.md and related whitepapers — These are conceptual documents; the operational behavior change doesn't affect them.
• context/ directory — No new example patterns needed; the feature is an internal behavior change in module discovery, not a new prompt convention.
• CHANGELOG.md — Should be updated when the feature is released, but that's a release-time task, not part of this step.

---

Proceeding to Step 6: Identify Dev Units

[prompt-driven-github]

Step 6: Dev Units Identified

Status: Found 2 dev units to modify + 2 direct edit candidates

Change Summary

Make agentic sync (pdd sync <github_issue_url>) work when no architecture.json exists by scanning the prompts/ directory to build a module catalog and updating the LLM prompt template to accept a file-listing-based module catalog instead of requiring architecture.json.

Project Structure (from .pddrc)

• Source directory: pdd/ (pdd_cli context)
• Test directory: tests/ (pdd_cli context)
• Example directory: context/ (pdd_cli context)
• Language: python

Dev Units to MODIFY

Important note: The two primary code modules (agentic_sync.py and agentic_sync_runner.py) do NOT have corresponding _python.prompt files in prompts/. They are hand-written/non-PDD-generated modules. The only PDD-managed prompt in scope is the LLM runtime prompt.

#	Prompt	Code	Example	Test	Reason
1	prompts/agentic_sync_identify_modules_LLM.prompt	N/A (LLM runtime prompt)	N/A	N/A	Primary fix target. Line 17 says "Only include modules that exist in the architecture.json" — must add conditional section for no-architecture case. When {architecture_json} is "No architecture.json available.", the LLM needs instructions to select from a provided module catalog listing instead.

The LLM prompt also exists at pdd/prompts/agentic_sync_identify_modules_LLM.prompt (loaded at runtime via load_prompt_template). Both copies must stay in sync.

Dev Units to CREATE

None. All changes can be accomplished by modifying existing files.

Reuse Analysis

No new modules needed. The existing sync_order.build_dependency_graph() already scans prompts/ for *_<Language>.prompt files and extracts basenames — this infrastructure can be reused directly in agentic_sync.py for the module catalog fallback.

Dependencies (may need interface updates)

None from the tracked dependency graph. The modules in the dependency graph (agentic_common, load_prompt_template, agentic_bug, etc.) are unrelated to the agentic sync flow.

Direct Edit Candidates (No Prompt)

Files that need scoped direct edits because no corresponding _python.prompt exists

#	File	Edit Type	Description
1	pdd/agentic_sync.py	Add module catalog logic	Lines 250-263: When architecture is None, scan prompts/ directory using existing build_dependency_graph() to build a module catalog (list of basenames with optional <pdd-reason> context). Format this catalog as a string and pass it to the LLM prompt template via a new {module_catalog} placeholder (or conditionally substitute it into the {architecture_json} slot). Lines 286-287: Improve error message when LLM returns no modules — distinguish between "no architecture.json AND no prompts directory" vs "LLM couldn't identify relevant modules from the catalog".
2	pdd/agentic_sync.py	Skip dependency validation	Lines 301-305: When architecture is None, skip the _apply_architecture_corrections step entirely (dependency validation is meaningless without architecture.json). The fallback dependency graph from build_dependency_graph() (line 311-314) already handles this correctly.

Integration Points Discovered

Integration Point	Reason for Update	Prompt File
pdd/commands/maintenance.py	No changes needed — already dispatches to run_agentic_sync() which will be modified in-place	prompts/commands/maintenance_python.prompt (does not exist — manual update if needed, but no changes required)
pdd/prompts/agentic_sync_identify_modules_LLM.prompt	Runtime copy of the LLM prompt — must be kept in sync with prompts/agentic_sync_identify_modules_LLM.prompt	N/A (runtime copy)

Search performed:

• grep -r "from.*agentic_sync\|import.*agentic_sync" pdd/ → found pdd/commands/maintenance.py and pdd/agentic_sync.py (self-import of runner)
• glob prompts/*_python.prompt → no results (no PDD-generated python module prompts in this project's prompts/ root)
• glob prompts/*sync* → no results (agentic_sync LLM prompt is agentic_sync_identify_modules_LLM.prompt, not a sync_ prefix)
• Listed pdd/prompts/ directory to verify runtime prompt copies

Frontend Dev Units (Cross-Layer)

Not applicable. This is a CLI tool with no frontend component.

Documentation Files (from Step 5)

These files need documentation updates (handled separately by pdd change):

• README.md — Add agentic sync mode documentation
• docs/TUTORIALS.md — Add tutorial for issue-driven sync
• docs/faq.md — Add FAQ about architecture.json being optional

Summary of Changes

Change	File	Type
Update LLM prompt with conditional no-architecture section	prompts/agentic_sync_identify_modules_LLM.prompt	MODIFY (PDD prompt)
Keep runtime copy in sync	pdd/prompts/agentic_sync_identify_modules_LLM.prompt	MODIFY (runtime copy)
Add module catalog scanning when no architecture.json	pdd/agentic_sync.py	Direct Edit (no prompt)
Improve error messaging for empty module list	pdd/agentic_sync.py	Direct Edit (no prompt)

Files Explored

• .pddrc — project configuration
• prompts/ — all 100+ prompt files (flat directory, no subdirectories)
• pdd/agentic_sync.py — main agentic sync orchestrator (365 lines)
• pdd/agentic_sync_runner.py — parallel sync runner (815 lines)
• pdd/sync_order.py — dependency graph builder with build_dependency_graph() (353 lines)
• pdd/sync_main.py — CLI wrapper for sync command (741 lines)
• pdd/commands/maintenance.py — CLI entry point dispatching to agentic sync (282 lines)
• pdd/load_prompt_template.py — prompt template loader
• prompts/agentic_sync_identify_modules_LLM.prompt — LLM prompt template (39 lines)
• pdd/prompts/agentic_sync_identify_modules_LLM.prompt — runtime copy of LLM prompt
• tests/test_agentic_sync.py — existing tests (377 lines)
• tests/test_agentic_sync_runner.py — existing runner tests (1195 lines)
• context/agentic_sync_example.py — example file (95 lines)
• context/agentic_sync_runner_example.py — runner example file (107 lines)

---

Proceeding to Step 7: Architecture Review

[prompt-driven-github]

Step 7: Architecture Review

Status: Architecture Clear

Reuse Validation

• No new modules proposed — Step 6 correctly identified only modifications to existing files. Validated.
• build_dependency_graph() reuse confirmed — sync_order.py:110-153 already scans prompts/ for *_<Language>.prompt files, extracts basenames via extract_module_from_include(), and builds a dependency graph from <include> tags. This is the exact fallback module discovery mechanism needed — no new scanning logic required.
• No creation-vs-modification concerns — all changes extend existing files.

Analysis

The implementation approach is straightforward based on the dev units identified in Step 6. The changes follow a clear pattern: detect the no-architecture.json case (already handled at line 250), generate a module catalog from existing infrastructure, pass it to the LLM via a conditional prompt section, and let the existing downstream logic (dependency graph building, parallel sync) work as-is.

Implementation Approach

1. pdd/agentic_sync.py (direct edit):

   • After _load_architecture_json() returns None (line 248), call build_dependency_graph(prompts_dir) to get all module basenames and their include-based dependencies
   • Format the result as a module catalog string (list of basenames with their prompt filenames)
   • Pass the catalog to the LLM prompt template via the existing {architecture_json} placeholder (no new format variables needed)
   • Improve error message at line 287 to distinguish "no modules found" from "no architecture.json" scenarios

2. prompts/agentic_sync_identify_modules_LLM.prompt (PDD prompt modification):

   • Add a conditional instruction block that replaces the current "Only include modules that exist in the architecture.json" constraint
   • When the input contains a module catalog instead of architecture.json, instruct the LLM to: select from the provided catalog, use issue content as the primary selection signal, and output DEPS_VALID: true (skip validation since there's no architecture.json to correct)
   • The conditional can be embedded inline using clear markers in the architecture section itself (e.g., "source": "prompts_directory_scan")

3. pdd/prompts/agentic_sync_identify_modules_LLM.prompt (runtime copy): Sync with the prompts/ version after modification.

Key Patterns

• Graceful degradation: The no-architecture path provides a best-effort module catalog from the filesystem. It has less metadata (no reason, no interface) but sufficient information (basenames, filenames, include-based dependencies) for the LLM to make reasonable selections.
• Single code path: The module catalog is formatted to fit the existing {architecture_json} placeholder, avoiding prompt template refactoring. The LLM distinguishes the two cases by the content structure.
• Downstream compatibility: Lines 307-314 already handle the no-architecture fallback for dependency graph building, and the parallel sync runner (AsyncSyncRunner) is agnostic to the discovery method.

Assumptions

• The prompts/ directory scan is the correct and sufficient fallback — projects without architecture.json will still have prompts/*.prompt files
• A conditional section in the existing prompt template is preferred over creating a separate prompt file
• The module catalog does not need reason or interface metadata — basenames and filenames are sufficient for LLM module selection
• Empty prompts/ directories should produce a clear error early (before LLM call)
• The DEPS_VALID / DEPS_CORRECTIONS output markers should still be emitted by the LLM (as DEPS_VALID: true with no corrections) to keep the parsing logic unchanged

---

Proceeding to Step 8: Analyze Prompt Changes

[prompt-driven-github]

Step 8: Prompt Change Analysis

Status: Changes Analyzed

Summary

One LLM runtime prompt needs modification (agentic_sync_identify_modules_LLM.prompt) to add conditional instructions for when no architecture.json exists. The prompt must guide the LLM to select modules from a provided module catalog (scanned from prompts/ directory) instead of requiring architecture.json entries. No new prompts are needed — the existing build_dependency_graph() infrastructure provides the fallback discovery mechanism.

Prompt Modifications

pdd/prompts/agentic_sync_identify_modules_LLM.prompt

Current state: A 39-line LLM runtime prompt with two placeholders ({issue_content}, {architecture_json}). It has two tasks: (1) identify modules to sync from the issue, and (2) validate architecture.json dependencies. Line 17 explicitly says "Only include modules that exist in the architecture.json", which makes the LLM return empty results when no architecture.json exists.

Changes needed:

1. Update requirement (Task 1, line 17): Change "Only include modules that exist in the architecture.json" → make this conditional. When architecture.json is present, keep the existing constraint. When absent, instruct the LLM to select from the provided module catalog instead.

2. Add conditional section for no-architecture case: After the {architecture_json} section, add instructions that activate when the architecture content indicates no architecture.json:

   • Instruct the LLM to identify relevant modules from the provided module catalog (list of basenames discovered by scanning prompts/ directory)
   • Use the issue content (title, description, comments) to determine which modules are relevant
   • Allow the LLM to infer relevance from module names, since <pdd-reason> metadata may not be available without architecture.json
   • Still require output in the same MODULES_TO_SYNC: [...] format

3. Update requirement (Task 2): Make dependency validation conditional:

   • When architecture.json exists: validate dependencies as before
   • When architecture.json is absent: output DEPS_VALID: true (no architecture to validate) and skip DEPS_CORRECTIONS

4. Add new placeholder {module_catalog}: The prompt needs a third placeholder to receive the list of available modules when architecture.json is absent. This will be populated by agentic_sync.py using build_dependency_graph() from sync_order.py, which already scans prompts/ for *_<Language>.prompt files and extracts basenames.

   • When architecture.json exists: {module_catalog} = "See architecture.json above." (or empty)
   • When architecture.json is absent: {module_catalog} = newline-separated list of basename (filename) pairs discovered from prompts/

Proposed prompt structure (high-level):

You are analyzing a GitHub issue to determine which PDD modules need to be synced,
and validating the architecture.json dependency graph.

## Issue
{issue_content}

## Architecture (architecture.json)
{architecture_json}

## Available Module Catalog
{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

If architecture.json is available:
- Only include modules that exist in the architecture.json
- Use the architecture metadata (reason, dependencies) to determine relevance

If architecture.json is NOT available (indicated by "No architecture.json available."):
- Select modules from the Available Module Catalog above
- 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
If architecture.json is available:
- Review the `dependencies` field for each identified module
- Are the listed dependencies correct and complete?
- 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
[unchanged — same MODULES_TO_SYNC / DEPS_VALID / DEPS_CORRECTIONS markers]

Code Changes Required (Direct Edits, Step 9)

The prompt change requires a corresponding code change in pdd/agentic_sync.py (a direct-edit file with no PDD prompt):

1. Add module catalog generation (~15 lines around line 259): When architecture is None, call build_dependency_graph(prompts_dir) to get the module list, format it as a catalog string, and pass it as {module_catalog}
2. Add {module_catalog} placeholder to the .format() call at line 260-263
3. Improve error messaging at line 286-287: When no modules found and no architecture.json, provide a more helpful error message suggesting the user check their prompts/ directory
4. Sync runtime prompt copy: pdd/prompts/agentic_sync_identify_modules_LLM.prompt must be updated to match the prompts/ version (they're the same file in this case — the file lives at pdd/prompts/)

Interface Changes

• New placeholder {module_catalog} added to the prompt template. The calling code in agentic_sync.py must supply this value. This is a non-breaking change since only agentic_sync.py:260 calls .format() on this template.
• Output format unchanged: MODULES_TO_SYNC, DEPS_VALID, and DEPS_CORRECTIONS markers remain identical. The _parse_llm_response() function needs no changes.
• No breaking changes to any public API or interface. The run_agentic_sync() function signature and return type are unchanged.

Existing Tests Impact

• All existing tests will pass without modification. The tests in test_agentic_sync.py mock load_prompt_template with a simple template string ("template {issue_content} {architecture_json}"), so they don't exercise the actual prompt content. The mock would need to be updated to include {module_catalog} in Step 9.
• New tests needed (in Step 9): Test the no-architecture.json flow end-to-end with mocked LLM responses showing module catalog-based selection.

Risk Assessment

• Low: This is a targeted, additive change to a single LLM runtime prompt. The modification is strictly conditional — the existing with-architecture code path is unchanged. The new no-architecture path reuses proven infrastructure (build_dependency_graph()).
• Mitigation:
  • The conditional structure ensures backward compatibility (when architecture.json exists, behavior is identical)
  • The "prefer including over excluding" instruction for the no-architecture case ensures the LLM errs on the side of syncing too many modules rather than too few
  • The DEPS_VALID: true bypass for the no-architecture case avoids false dependency corrections
  • The existing _parse_llm_response() handles the output format regardless of which code path generated it

---

Proceeding to Step 9: Implement Changes