feat: Hierarchical architecture generation for large PRDs (#604)

[prompt-driven-github]

Summary

Add subsystem support to the architecture generation pipeline, enabling recursive sub-architecture generation for large PRDs (30+ modules). This prevents the LLM from collapsing granular API routes and components into single modules — addressing the issue where a 74-module video editor PRD produced only 50 modules.

Closes #604

Changes Made

Schema Modified

• pdd/templates/architecture/architecture_json.prompt — Add "type": "subsystem" entry with sub_architecture_dir and scope fields

Prompts Modified

• pdd/prompts/agentic_arch_step5_design_LLM.prompt — Add complexity assessment; instruct LLM to design subsystem hierarchy for 30+ module projects
• pdd/prompts/agentic_arch_step5b_completeness_gate_LLM.prompt — Accept subsystem-scoped requirements as covered
• pdd/prompts/agentic_arch_step5b_fix_LLM.prompt — Handle subsystem entries when fixing completeness gaps
• pdd/prompts/agentic_arch_step7_generate_LLM.prompt — Document subsystem entry format in architecture.json output
• pdd/prompts/agentic_arch_step7b_review_LLM.prompt — Validate subsystem entries (scope coverage, directory paths, no overlaps)
• pdd/prompts/agentic_arch_step8_pddrc_LLM.prompt — Skip subsystem entries when building .pddrc context mappings
• pdd/prompts/agentic_arch_step9_prompts_LLM.prompt — Skip prompt generation for subsystem entries
• pdd/prompts/agentic_arch_step10_completeness_LLM.prompt — Defer subsystem-scoped requirements; skip prompt file checks for subsystem entries

Documentation Updated

• README.md — Add hierarchical architecture feature description
• docs/TUTORIALS.md — Add tutorial section on subsystem usage
• docs/faq.md — Add FAQ entry for large PRD handling
• docs/prompting_guide.md — Add guidance on subsystem prompting

Review Checklist

• Prompt syntax is valid
• Schema changes are backward-compatible (new optional type)
• PDD conventions followed
• Documentation is up to date

Note on Orchestrator Changes

This PR covers prompt and schema changes only. The following code changes are required to enable the full recursive workflow but are outside prompt scope:

1. pdd/agentic_architecture_orchestrator.py — Detect subsystem entries after Step 7 and recursively invoke the workflow
2. pdd/agentic_architecture.py — Support scoped PRD context for subsystem passes
3. pdd/registry.py — Register and resolve cross-subsystem dependencies

These should be implemented in a follow-up PR or as part of this PR before merge.

Next Steps After Merge

1. Implement orchestrator recursive invocation logic
2. Run tests to verify backward compatibility with existing (flat) architecture generation
3. Test with a large PRD (e.g., the 3blue1brown video editor demo) to validate subsystem generation

---

Created by pdd change workflow