Template customization and scaffolding: new-service bootstrap guide, module generator, deptrac placeholders, composer name typo

[Kravalg]

Description

As a maintainer of php-service-template, I want a documented and partially automated path for turning the template into a real service, so that downstream teams can rename the src/CompanySubdomain/SomeModule placeholder and scaffold new bounded contexts without guesswork or breaking the locked quality gates.

Today there is no guide for renaming the CompanySubdomain/SomeModule placeholder when bootstrapping a real service (grep of README.md/CONTRIBUTING.md/AGENTS.md finds zero mentions of it). deptrac.yaml hardcodes the placeholder namespaces in enumerated class-suffix regexes while AGENTS.md and the deptrac-fixer skill forbid editing deptrac.yaml — a contradictory rule the very first real customization must break. No scaffolding generates a new bounded context with the Domain/Application/Infrastructure layers, composer.json still carries the template identity with a typo (vilnacrm/php-serice-template), and there is no per-service extension point such as an optional Makefile.local include, so downstream repos must fork-edit synced files that the weekly template-sync will then fight.

Affected quality attributes

• customizability — 3/5, no rename/bootstrap checklist for the placeholder namespace, composer.json name, workspace.dsl and deptrac.yaml — target 5/5
• tailorability — 3/5, locked policy files (scripts/validate-configuration.sh) with no sanctioned override path or Makefile.local seam for downstream services — target 5/5
• extensibility — 4/5, adding a module requires hand-appending brittle deptrac.yaml regexes and there is no bounded-context scaffolder — target 5/5
• adaptability — 4/5, deptrac.yaml collectors hardcode CompanySubdomain\SomeModule / Internal\HealthCheck instead of structural layer patterns — target 5/5
• evolvability — 4/5, no documented sanctioned edit/divergence path for downstream consumers of template-sync — target 5/5
• intuitiveness — 4/5, placeholder module ships with no accompanying guide on how to replace it — target 5/5

This issue is part of the enterprise quality audit (report: docs/audit/enterprise-quality-audit-2026-07.md on branch claude/enterprise-quality-audit-bc8jch).

Tasks

• Add docs/NEW-SERVICE.md (linked from the README quick start) with a step-by-step bootstrap walkthrough: rename src/CompanySubdomain/SomeModule, update composer.json name/description, deptrac.yaml collectors, workspace.dsl, config/api_platform/resources.yaml, and .env secrets
• Add a scaffolding script or maker (scripts/new-module.sh exposed as make new-module name=...) that generates a new bounded context skeleton with all three layers (Domain/Application/Infrastructure) plus a passing example test
• Parameterize deptrac.yaml namespace patterns (structural regexes such as App\\.*\\Domain\\.* covering any module) or document the sanctioned edit path so new modules do not require weakening the ruleset agents are forbidden to edit
• Fix the composer.json package name typo (vilnacrm/php-serice-template → vilnacrm/php-service-template)
• Add an optional Makefile.local include (e.g. -include Makefile.local, gitignored) as a per-service extension point
• Document in the template-sync docs which files downstream services may diverge on (with .templatesyncignore examples) so customization survives weekly syncs

Acceptance Criteria

• docs/NEW-SERVICE.md exists, is linked from README.md, and covers renaming deptrac.yaml, workspace.dsl, and composer.json
• Running the module scaffolder produces a new bounded context that passes make deptrac, make psalm, and the unit test suite without editing deptrac.yaml by hand (or via the documented sanctioned path)
• composer.json name no longer contains the typo and composer validate passes
• A Makefile.local include is honored when present and absent-safe when not
• All existing quality gates still pass (make ci)
• The linked PR passes GitHub CI checks and CodeRabbit review feedback is addressed

Never propose lowering existing quality gates — thresholds may only be added or raised.

[coderabbitai]

🔗 Related PRs

#39 - add correct badges [merged]
#57 - update Readme, fix GitHub action, move AUTORELEASE.md [merged]
#172 - feat(#171): synchronize AI agent support baseline [merged]
#175 - feat(#174): sync README and FrankenPHP enterprise baseline [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!