feature: pdd connect - enable / support Makefile generation to create a turnkey experience

[jamesdlevine]

PDD Connect in particular presents an experience which allows project creation from scratch. However the built artifacts aren't necessarily ready to use without supporting components which fall outside of regular devunits. Examples include packaging and installation support, repo cleaning of interim artifacts, distribution of built deliverables (for example uploading to pypi). An appropriate Makefile will handle these in a straightforward manner.

[prompt-driven-github]

🔗 Connect Session Starting!

Session ID: 2e26f86a-c835-4c37-a64e-7fa8d5eac9d4
Triggered by: @jiaminc-cmu
You can interact with this session from the PDD Cloud web UI.
The session will auto-commit and create a PR on shutdown.

[prompt-driven-github]

🔗 Connect Session Starting!

Session ID: ebb0ed06-7823-47f6-afc1-eb27babe3a14
Triggered by: @jiaminc-cmu
You can interact with this session from the PDD Cloud web UI.
The session will auto-commit and create a PR on shutdown.

[prompt-driven-github]

PDD Connect Session Ready

Your web-based PDD Connect session is now accessible:

Open Session

Session ID: ebb0ed06
This link is temporary and will expire when the session ends (max 4 hours).

Security: Do not share this link. It grants full access to your session.

[prompt-driven-github]

PDD Connect Session Ready

Your web-based PDD Connect session is now accessible:

Open Session

Session ID: 2e26f86a
This link is temporary and will expire when the session ends (max 4 hours).

Security: Do not share this link. It grants full access to your session.

[prompt-driven-github]

Connect Session Stopping

The connect label was removed. Sent shutdown signal to 2 active session(s). Sessions will auto-commit, push changes, and create a PR before exiting.

[prompt-driven-github]

🚀 Job Queued!

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

[prompt-driven-github]

Step 1: Duplicate Check

Status: No duplicates found

Search Performed

• Searched for: "Makefile", "pdd connect", "packaging", "turnkey", "pypi distribution", "project generation", "build artifacts", "installation support", "template", "boilerplate"
• Issues reviewed: 14 potentially related issues

Findings

I performed a thorough search across multiple keywords related to this feature request. While several issues were found that involve Makefiles, none are duplicates of this request:

Issues found that mention Makefiles but are NOT duplicates:

1. Issue dependency graph that will work in a Makefile vs. having to set it up manually #170 - "dependency graph that will work in a Makefile vs. having to set it up manually"

   • Different focus: about dependency graph generation for existing projects
   • No body text or comments to evaluate detailed scope
   • Related but not a duplicate

2. Issue Makefile: evaluate removing pdd-cli from pdd conda environment #312 (CLOSED) - "Makefile: evaluate removing pdd-cli from pdd conda environment"

   • About PDD's own development Makefile configuration
   • Not about generating Makefiles for user projects

3. Issue make regression fails when path contains spaces #334 (CLOSED) - "make regression fails when path contains spaces"

   • Bug fix for PDD's existing Makefile
   • Not about Makefile generation feature

4. Other issues (pdd update tries to create prompts for all files even ones that are not code files #224, pdd sync generates files in wrong locations due to path pattern mismatch and dir_prefix bug #237, Issues Starting Up With PDD Local #299) - Various PDD issues mentioning Makefiles in passing but unrelated to this feature request

Why this is NOT a duplicate:

This issue specifically requests a feature where PDD Connect generates Makefiles for new projects to provide:

• Packaging and installation support
• Repo cleaning of interim artifacts
• Distribution of built deliverables (e.g., uploading to PyPI)
• A turnkey experience for projects created from scratch

No existing issue requests this Makefile generation capability as part of the PDD Connect project creation workflow.

Conclusion: This appears to be a new feature request for PDD Connect to enhance project scaffolding with build automation support.

---

Proceeding to Step 2: Documentation Check

[prompt-driven-github]

[prompt-driven-github]

Step 2: Documentation Check

Status: Not Implemented

Documentation Reviewed

• README.md (main documentation)
• docs/ONBOARDING.md (user onboarding guide)
• docs/TUTORIALS.md (workflow tutorials)
• docs/prompting_guide.md
• pdd/commands/connect.py (PDD Connect source code)
• pdd/commands/generate.py (generate command source)
• pdd/commands/templates.py (template system)
• examples/template_example/Makefile (example Makefile)
• examples/template_example/README.md (template workflow docs)

Findings

Current State:

PDD Connect (via pdd connect) provides a web-based interface for running PDD commands and browsing project files, but does not include automatic Makefile generation as part of its project creation workflow.

What PDD Currently Provides:

1. Template-based workflow - PDD supports generating projects using templates:

   • pdd generate --template architecture/architecture_json creates architecture.json
   • pdd templates command group for managing templates
   • Example projects in examples/ directory include handcrafted Makefiles

2. Manual Makefile creation - The existing example Makefiles (e.g., examples/template_example/Makefile) provide sophisticated build automation including:

   • Architecture generation from PRDs
   • Prompt file generation
   • Code/test synchronization with pdd sync
   • Test execution
   • Clean targets

   However, these Makefiles are manually created by developers, not generated automatically by PDD.

3. PDD Connect - The web interface (pdd connect) provides:

   • Visual command execution
   • File browsing and editing
   • Remote session access via PDD Cloud

   But it does not automatically generate Makefiles, setup.py, pyproject.toml, or other packaging/distribution infrastructure.

Gap Analysis:

The issue specifically requests that PDD Connect automatically generate Makefiles when creating projects from scratch to provide:

• Packaging and installation support
• Repository cleaning of interim artifacts
• Distribution of built deliverables (e.g., uploading to PyPI)
• A "turnkey experience" for new projects

This capability does not currently exist. While PDD can generate code, tests, and architecture from prompts, it does not automatically generate build/packaging infrastructure (Makefiles, setup scripts, CI/CD configs) as part of the project scaffolding process.

Conclusion

This is a new feature request. The functionality described in issue #436 - automatic Makefile generation as part of PDD Connect's project creation workflow - is not currently implemented or documented.

---

Proceeding to Step 3: Identify Dev Units

[prompt-driven-github]

Step 3: Research & Clarification

Status: Research Complete

Summary

Conducted comprehensive research on Makefile generation best practices for Python projects, examining modern packaging standards (pyproject.toml), template generation systems (Cookiecutter/Copier), and security considerations for credential management. Found that PDD already has sophisticated Jinja2-based templating infrastructure that can be extended to generate Makefiles.

Research Findings

Technical Background

Python Packaging Standards (2026)

• Modern Python projects use pyproject.toml (PEP 517/518/621) as the standard configuration format
• Build backends include setuptools, Hatch, PDM, and uv, each with different capabilities
• Distribution requires both sdist and wheel archives for maximum compatibility
• PyPI publishing typically uses twine or built-in backend capabilities

Makefile Best Practices for Python
Standard targets for Python projects include:

• clean: Remove __pycache__, *.pyc, build artifacts, and distribution files
• install / install-dev: Install package and dependencies (often into virtual environment)
• test: Run pytest with appropriate configuration
• lint / fmt: Code quality checks and formatting (ruff, mypy, black)
• build / dist: Build distribution packages using build tools
• publish: Upload to PyPI using twine
• help: Display available targets and usage

Common patterns include:

• Using .PHONY declarations for non-file targets
• Virtual environment integration via variables (VENV, PIP, PY)
• Configurable flags (USE_LOCAL, USE_FORCE, USE_INFISICAL for secrets)
• Dependency ordering between targets

Best Practices

Template Generation Systems

• Cookiecutter: Mature tool using Jinja2 templates with cookiecutter.json configuration

  • Supports pre/post-generation hooks (Python/shell scripts) for validation and cleanup
  • Variables defined in JSON, templated using {{ variable }} syntax
  • Can extend with custom Jinja2 extensions, filters, and tests

• Copier: Modern alternative using YAML + Jinja2

  • Supports template updates and keeping projects in sync
  • More expressive than Cookiecutter for evolving projects

• PDD's Existing System: Already uses Jinja2-based template expansion

  • Supports placeholders like {name}, {category}, {ext}, {language}
  • Has template_expander.py with case conversion utilities (snake_case, PascalCase, kebab-case)
  • Template registry system at pdd/template_registry.py
  • Generate command accepts -e KEY=VALUE for environment variables

Security Considerations
Critical security practices for Makefiles handling credentials:

• Never hardcode PyPI tokens or API keys in Makefiles or code
• Use environment variables loaded from secure sources (.env files in .gitignore)
• Consider Trusted Publishing (OIDC) for PyPI - uses short-lived tokens (15-minute expiration)
• Use OS keyring integration (keyring library) or cloud secret managers (AWS Secrets Manager, etc.)
• Add credential files to .gitignore to prevent accidental commits
• Be aware of dependency security - malicious packages can steal environment variables

Common Pitfalls

• Storing long-lived API tokens in version control (use Trusted Publishing instead)
• Not using .PHONY for non-file targets causes make to skip execution if files exist
• Hardcoding paths instead of using variables reduces portability
• Missing dependencies between targets causes build failures

Similar Implementations

Found several reference implementations:

• python-project-template (rochacbruno - now archived, recommends uv)
• python-project-makefile-template (mivanit) - Uses uv, pytest, mypy, ruff
• Generic_Makefile (mmphego) - Feature-rich template with extensive targets

PDD's existing examples/template_example/Makefile demonstrates:

• Architecture generation and prompt management
• Dynamic module discovery from architecture.json
• Configurable mode switching (local vs cloud, force mode, Infisical integration)
• Clean target for generated artifacts
• Sophisticated sync workflow with format detection

Refined Specifications

Based on research, the Makefile generation feature should include:

1. Template-based generation using PDD's existing Jinja2 infrastructure (template_expander.py, template_registry.py)

2. Standard Python project targets:

   • clean: Remove pycache, build/, dist/, *.egg-info, .pytest_cache
   • install: Install package in development mode
   • test: Run pytest with coverage
   • lint: Run ruff/mypy/other linters
   • build: Build distribution packages (sdist + wheel)
   • publish: Upload to PyPI (with safety checks)
   • help: Display available targets

3. Security-first design:

   • Use environment variables for credentials (TWINE_USERNAME, TWINE_PASSWORD)
   • Support Trusted Publishing workflow (recommended in comments)
   • Include .gitignore checks to prevent credential leakage
   • Provide secure defaults (never hardcode tokens)

4. Project-aware customization:

   • Detect build backend from pyproject.toml (setuptools, hatch, poetry, uv)
   • Adjust commands based on project structure
   • Support for PDD-specific targets (architecture generation, sync workflows)
   • Optional integration with Infisical or other secret managers

5. Edge cases to handle:

   • Projects without pyproject.toml (legacy setup.py)
   • Multiple Python versions (tox, nox support)
   • Non-Python assets (documentation, frontend builds)
   • Monorepo structures with multiple packages

Alternative Approaches Considered

Alternative 1: Static template files

• Pros: Simple to implement, easy to understand, predictable output
• Cons: Not customizable to project specifics, requires manual editing after generation

Alternative 2: External tool integration (invoke/just/task)

• Pros: Modern alternatives to Make with better Python integration
• Cons: Additional dependency, less universal than Make, steeper learning curve for users

Alternative 3: Full Cookiecutter/Copier integration

• Pros: Industry-standard tools, rich ecosystem, template update support
• Cons: Heavy dependency, complexity overkill for just Makefile generation, duplicates PDD's existing template system

Alternative 4: Extend existing template system (RECOMMENDED)

• Pros: Leverages PDD's Jinja2 infrastructure, consistent with current architecture, minimal new dependencies
• Cons: Requires template authoring, may need enhancements to template_expander.py

Recommended Approach

Extend PDD's existing template system to generate Makefiles:

1. Create new template: packaging/makefile_python in template registry
2. Use Jinja2 templating with conditionals based on:
   • Detected build backend (from pyproject.toml)
   • Project structure (src-layout vs flat-layout)
   • Optional features (linting, type checking, documentation)
3. Invoke during pdd connect or via explicit pdd generate --template packaging/makefile_python
4. Support customization via -e variables (e.g., -e PACKAGE_NAME=myapp -e BUILD_BACKEND=hatch)
5. Include security best practices by default (environment variables, .gitignore reminders)

This approach:

• Aligns with PDD's existing architecture and patterns
• Minimal new code (primarily template content + registry entry)
• Familiar workflow for PDD users
• Extensible to other project file types (justfile, taskfile, etc.)

---

Proceeding to Step 4: Identify Dev Units

Sources:

• Packaging Python Projects - Python Packaging User Guide
• The State of Python Packaging in 2026
• Managing your Python project with a Makefile
• Python Packaging Best Practices 2026
• python-project-template Makefile
• Cookiecutter Documentation
• From Cookiecutter to Copier, uv, and Just
• PyPI Security Model - Trusted Publishers
• Python Secrets Management Best Practices
• Securing Credentials in Python