[Future] Design community template ecosystem via create-apm-* packages

[danielmeppiel]

Summary

Design community-driven template ecosystem using create-apm-* packages that follow npm's initializer pattern. This is future work and not a blocker for the core init/install redesign.

Background

npm's Approach

npm init <initializer>  # Runs: npx create-<initializer>

# Examples:
npm init react-app my-app    # → npx create-react-app my-app
npm init vite@latest my-app  # → npx create-vite@latest my-app
npm init next-app my-app     # → npx create-next-app my-app

Key insight: Templates live as separate npm packages, not bundled with core CLI.

Proposed APM Pattern

apm init <initializer>  # Runs: npx create-apm-<initializer>

# Examples:
apm init hello-world my-app    # → npx create-apm-hello-world my-app
apm init express-api my-app    # → npx create-apm-express-api my-app
apm init compliance-template   # → npx create-apm-compliance-template

Design Requirements

1. Package Naming Convention

• Format: create-apm-<template-name>
• Registry: npm (standard Node.js packages)
• Discoverability: Searchable by create-apm prefix

2. Template Package Structure

create-apm-hello-world/
├── package.json
├── bin/
│   └── index.js          # Entry point
├── templates/
│   ├── apm.yml
│   ├── hello-world.prompt.md
│   ├── .apm/
│   │   ├── instructions/
│   │   └── chatmodes/
│   └── README.md
└── README.md             # Template documentation

3. Template Package API

// bin/index.js
#!/usr/bin/env node

const args = process.argv.slice(2);
const projectName = args[0] || 'my-apm-project';

// Create project directory
// Copy template files
// Substitute variables ({{project_name}}, etc.)
// Run post-creation tasks (apm install, etc.)

4. APM CLI Integration

def init(ctx, initializer, project_name, yes):
    if initializer:
        # Delegate to npx
        cmd = ['npx', f'create-apm-{initializer}']
        if project_name:
            cmd.append(project_name)
        subprocess.run(cmd)
    else:
        # Minimal init (default)
        _create_minimal_apm_yml()

Community Template Examples

Official Templates (Future)

• create-apm-hello-world - Basic workflow examples
• create-apm-express-api - Express.js backend
• create-apm-frontend-app - Frontend SPA
• create-apm-fullstack - Full-stack application

Community Templates (Examples)

• create-apm-compliance - GDPR, legal review workflows
• create-apm-design-system - UI component standards
• create-apm-data-pipeline - Data engineering workflows

Documentation Needs

Template Author Guide

# Creating APM Templates

1. Create npm package named `create-apm-<name>`
2. Add executable entry point in `bin/`
3. Structure templates in `templates/` directory
4. Use variable substitution for customization
5. Publish to npm registry

See: https://github.com/danielmeppiel/create-apm-hello-world (example)

Template Discovery

• Website/registry listing available templates
• apm templates command to search npm for create-apm-* packages
• GitHub topic for template repositories

Non-Goals (Out of Scope)

• ❌ Built-in template bundling in APM CLI
• ❌ Custom template registry (use npm)
• ❌ Template versioning system (use npm semver)
• ❌ Template validation/certification program

Benefits

✅ Separation of Concerns - Core CLI stays minimal
✅ Community Ownership - Anyone can publish templates
✅ Standard Tooling - Uses npm/npx (no new tools)
✅ Versioning - Templates can evolve independently
✅ Discoverability - Standard npm search works

Implementation Phases

Phase 1: Design (This Issue)

• Research npm init pattern thoroughly
• Design template package spec
• Create example template package
• Document template authoring guide

Phase 2: CLI Integration (Future)

• Add apm init <template> → npx create-apm-<template> delegation
• Add apm templates search command (optional)
• Update docs with template usage

Phase 3: Ecosystem (Future)

• Publish official create-apm-hello-world
• Migrate existing hello-world template
• Encourage community templates

Acceptance Criteria

• Template package spec documented
• Example create-apm-hello-world package created
• Template authoring guide written
• CLI integration design reviewed
• No implementation required yet

Related

• Not a blocker for issues Refactor apm init to minimal-only mode (breaking change) #13, Add auto-bootstrap in apm install when no apm.yml exists #14, Improve error messages in apm install with actionable suggestions #15, Update documentation for new init/install workflows #16
• Future enhancement after core redesign ships
• Part of npm-parity long-term vision