Design community template ecosystem via create-apm-* packages

[Copilot]

📖 Documentation Update

Changes

Documents the community-driven template ecosystem following npm's initializer pattern (npm init <initializer> → npx create-<initializer>).

Template Ecosystem Spec (docs/templates.md)

• Package naming convention: create-apm-<template-name>
• Required structure: package.json, bin/index.js, templates/
• Variable substitution: {{project_name}}, {{author}}, {{year}}
• Publishing workflow and best practices

Example Package (templates/create-apm-hello-world/)

• Working reference implementation of a create-apm-* npm package
• Includes executable CLI, template files, instructions, and chatmode

CLI Integration Design

apm init hello-world my-app
        ↓
npx create-apm-hello-world my-app

Scope

• README updates
• API documentation
• User guides
• Code comments
• Other: Example template package structure

Checklist

• LABEL: Apply documentation or docs label to this PR
• Content is accurate and up-to-date
• Links and references work correctly
• Formatting is consistent

Fixes #21

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Future] Design community template ecosystem via create-apm-* packages</issue_title>
<issue_description>## 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</issue_description>

<agent_instructions>Hey, don't overcomplicate things</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [Future] Design community template ecosystem via create-apm-* packages #17

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[danielmeppiel]

@copilot I don't liek this, you need to do it in this way:

---

[Copilot]

@copilot I don't liek this, you need to do it in this way:

---

It looks like your instructions got cut off. Could you share how you'd like me to approach this?