BoilerWorks

Add MCP server and Claude Code skill - boilerworks/mcp_server.py: FastMCP server exposing list_templates, get_template, search_templates, create_manifest, validate_manifest, dry_run, init_project as tools - pyproject.toml: add mcp optional dep, boilerworks-mcp entry point - skill/: Claude Code skill package (@conflict/boilerworks) for marketplace distribution

anonymous 2026-03-30 18:55 trunk

Commit ff05bb230a342b624a1c44aa1e9d7059f75f20b460976b3ead54d6cddc9422ad

Parent f3f6dc28d35f463…

4 files changed +212 +4 +29 +137

+ boilerworks/mcp_server.py ~ pyproject.toml + skill/package.json + skill/skill.md

A boilerworks/mcp_server.py

+212

		--- a/boilerworks/mcp_server.py
		+++ b/boilerworks/mcp_server.py
		@@ -0,0 +1,212 @@
	1	+"""Boilerworks MCP server — exposes the CLI as tools for AI agents."""
	2	+
	3	+from __future__ import annotations
	4	+
	5	+import json
	6	+from pathlib import Path
	7	+from typing import Annotated
	8	+
	9	+from mcp.server.fastmcp import FastMCP
	10	+
	11	+mcp = FastMCP(
	12	+ "boilerworks",
	13	+ instructions=(
	14	+ "Boilerworks provides 26 production-ready project templates structured for AI-assisted development. "
	15	+ "Use list_templates to explore options, create_manifest to build a boilerworks.yaml, "
	16	+ "and init_project to scaffold the project on disk."
	17	+ ),
	18	+)
	19	+
	20	+
	21	+# ── Templates ─────────────────────────────────────────────────────────────────
	22	+
	23	+
	24	+@mcp.tool()
	25	+def list_templates(
	26	+ size: Annotated[str \| None, "Filter by size: full \| micro \| edge"] = None,
	27	+ language: Annotated[str \| None, "Filter by language: python \| typescript \| ruby \| php \| java \| go \| elixir \| rust \| svelte"] = None,
	28	+ status: Annotated[str \| None, "Filter by status: done \| building \| planned"] = None,
	29	+) -> str:
	30	+ """List all available Boilerworks templates, optionally filtered."""
	31	+ from boilerworks.registry import Registry
	32	+
	33	+ registry = Registry()
	34	+ templates = registry.list_all()
	35	+
	36	+ if size:
	37	+ templates = [t for t in templates if t.size == size]
	38	+ if language:
	39	+ templates = [t for t in templates if t.language == language]
	40	+ if status:
	41	+ templates = [t for t in templates if t.status == status]
	42	+
	43	+ rows = [
	44	+ {
	45	+ "name": t.name,
	46	+ "size": t.size,
	47	+ "language": t.language,
	48	+ "backend": t.backend,
	49	+ "frontend": t.frontend,
	50	+ "status": t.status,
	51	+ "best_for": t.best_for,
	52	+ }
	53	+ for t in templates
	54	+ ]
	55	+ return json.dumps(rows, indent=2)
	56	+
	57	+
	58	+@mcp.tool()
	59	+def get_template(
	60	+ name: Annotated[str, "Template name, e.g. django-nextjs"],
	61	+) -> str:
	62	+ """Get full details for a specific Boilerworks template."""
	63	+ from boilerworks.registry import Registry
	64	+
	65	+ registry = Registry()
	66	+ template = registry.get_by_name(name)
	67	+
	68	+ if template is None:
	69	+ valid = ", ".join(sorted(registry.names()))
	70	+ return f"Template '{name}' not found. Available: {valid}"
	71	+
	72	+ return json.dumps(template.model_dump(), indent=2)
	73	+
	74	+
	75	+@mcp.tool()
	76	+def search_templates(
	77	+ query: Annotated[str, "Search query matched against name, description, and best_for"],
	78	+) -> str:
	79	+ """Search templates by keyword."""
	80	+ from boilerworks.registry import Registry
	81	+
	82	+ registry = Registry()
	83	+ results = registry.search(query)
	84	+
	85	+ if not results:
	86	+ return f"No templates matched '{query}'."
	87	+
	88	+ rows = [{"name": t.name, "size": t.size, "backend": t.backend, "frontend": t.frontend, "best_for": t.best_for} for t in results]
	89	+ return json.dumps(rows, indent=2)
	90	+
	91	+
	92	+# ── Manifest ──────────────────────────────────────────────────────────────────
	93	+
	94	+
	95	+@mcp.tool()
	96	+def create_manifest(
	97	+ project: Annotated[str, "Project slug (lowercase, letters/digits/hyphens)"],
	98	+ family: Annotated[str, "Template family name, e.g. django-nextjs"],
	99	+ size: Annotated[str, "Template size: full \| micro \| edge"],
	100	+ cloud: Annotated[str \| None, "Cloud provider: aws \| gcp \| azure"] = None,
	101	+ region: Annotated[str \| None, "Cloud region, e.g. us-east-1"] = None,
	102	+ topology: Annotated[str, "standard \| api-only \| omni"] = "standard",
	103	+ domain: Annotated[str \| None, "Production domain, e.g. myapp.com"] = None,
	104	+ ops: Annotated[bool, "Include Terraform infrastructure repo"] = False,
	105	+ mobile: Annotated[bool, "Include mobile app template (Full only)"] = False,
	106	+ web_presence: Annotated[bool, "Include marketing site template (Full only)"] = False,
	107	+ compliance: Annotated[list[str] \| None, "Compliance requirements: soc2 \| hipaa \| pci-dss \| gdpr"] = None,
	108	+ email: Annotated[str \| None, "Email service: ses \| sendgrid \| mailgun"] = None,
	109	+ storage: Annotated[str \| None, "File storage: s3 \| gcs \| azure-blob"] = None,
	110	+ search: Annotated[str \| None, "Search engine: opensearch \| meilisearch"] = None,
	111	+ cache: Annotated[str, "Cache: redis \| memcached"] = "redis",
	112	+ database: Annotated[str, "Database: postgres \| mysql \| sqlite"] = "postgres",
	113	+ e2e: Annotated[str \| None, "E2E framework: playwright \| cypress"] = None,
	114	+) -> str:
	115	+ """Build and validate a boilerworks.yaml manifest. Returns the YAML content ready to write to disk."""
	116	+ from boilerworks.manifest import BoilerworksManifest, DataConfig, ServicesConfig, TestingConfig
	117	+
	118	+ try:
	119	+ manifest = BoilerworksManifest(
	120	+ project=project,
	121	+ family=family,
	122	+ size=size,
	123	+ topology=topology,
	124	+ cloud=cloud,
	125	+ ops=ops,
	126	+ region=region,
	127	+ domain=domain,
	128	+ mobile=mobile,
	129	+ web_presence=web_presence,
	130	+ compliance=compliance or [],
	131	+ services=ServicesConfig(
	132	+ email=email,
	133	+ storage=storage,
	134	+ search=search,
	135	+ cache=cache,
	136	+ ),
	137	+ data=DataConfig(database=database),
	138	+ testing=TestingConfig(e2e=e2e),
	139	+ )
	140	+ except Exception as exc:
	141	+ return f"Invalid manifest: {exc}"
	142	+
	143	+ return manifest.to_yaml()
	144	+
	145	+
	146	+@mcp.tool()
	147	+def validate_manifest(
	148	+ yaml_content: Annotated[str, "Contents of a boilerworks.yaml file to validate"],
	149	+) -> str:
	150	+ """Validate a boilerworks.yaml manifest. Returns 'valid' or a description of the errors."""
	151	+ from boilerworks.manifest import BoilerworksManifest
	152	+
	153	+ try:
	154	+ BoilerworksManifest.from_yaml(yaml_content)
	155	+ return "valid"
	156	+ except Exception as exc:
	157	+ return f"invalid: {exc}"
	158	+
	159	+
	160	+# ── Project generation ─────────────────────────────────────────────────────────
	161	+
	162	+
	163	+def _run_cli(args: list[str], manifest_yaml: str) -> str:
	164	+ """Write manifest to a temp file, run the boilerworks CLI, return combined output."""
	165	+ import subprocess
	166	+ import sys
	167	+ import tempfile
	168	+
	169	+ with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
	170	+ f.write(manifest_yaml)
	171	+ tmp_path = f.name
	172	+
	173	+ try:
	174	+ result = subprocess.run(
	175	+ [sys.executable, "-m", "boilerworks.cli"] + args + ["--manifest", tmp_path],
	176	+ capture_output=True,
	177	+ text=True,
	178	+ )
	179	+ output = (result.stdout + result.stderr).strip()
	180	+ return output or ("OK" if result.returncode == 0 else "Command failed with no output.")
	181	+ finally:
	182	+ Path(tmp_path).unlink(missing_ok=True)
	183	+
	184	+
	185	+@mcp.tool()
	186	+def dry_run(
	187	+ manifest_yaml: Annotated[str, "Contents of a boilerworks.yaml manifest"],
	188	+ output_dir: Annotated[str, "Directory where the project would be created"] = ".",
	189	+) -> str:
	190	+ """Preview what boilerworks init would do without writing any files."""
	191	+ return _run_cli(["init", "--dry-run", "--output", output_dir], manifest_yaml)
	192	+
	193	+
	194	+@mcp.tool()
	195	+def init_project(
	196	+ manifest_yaml: Annotated[str, "Contents of a boilerworks.yaml manifest"],
	197	+ output_dir: Annotated[str, "Directory to generate the project in"] = ".",
	198	+) -> str:
	199	+ """
	200	+ Scaffold a new project from a boilerworks.yaml manifest.
	201	+ Clones the template, applies substitutions, and runs git init.
	202	+ Requires network access (GitHub). This may take 10-30 seconds.
	203	+ """
	204	+ return _run_cli(["init", "--output", output_dir], manifest_yaml)
	205	+
	206	+
	207	+def main() -> None:
	208	+ mcp.run()
	209	+
	210	+
	211	+if __name__ == "__main__":
	212	+ main()

	--- a/boilerworks/mcp_server.py
	+++ b/boilerworks/mcp_server.py
	@@ -0,0 +1,212 @@

	--- a/boilerworks/mcp_server.py
	+++ b/boilerworks/mcp_server.py
	@@ -0,0 +1,212 @@
1	"""Boilerworks MCP server — exposes the CLI as tools for AI agents."""
2
3	from __future__ import annotations
4
5	import json
6	from pathlib import Path
7	from typing import Annotated
8
9	from mcp.server.fastmcp import FastMCP
10
11	mcp = FastMCP(
12	"boilerworks",
13	instructions=(
14	"Boilerworks provides 26 production-ready project templates structured for AI-assisted development. "
15	"Use list_templates to explore options, create_manifest to build a boilerworks.yaml, "
16	"and init_project to scaffold the project on disk."
17	),
18	)
19
20
21	# ── Templates ─────────────────────────────────────────────────────────────────
22
23
24	@mcp.tool()
25	def list_templates(
26	size: Annotated[str \| None, "Filter by size: full \| micro \| edge"] = None,
27	language: Annotated[str \| None, "Filter by language: python \| typescript \| ruby \| php \| java \| go \| elixir \| rust \| svelte"] = None,
28	status: Annotated[str \| None, "Filter by status: done \| building \| planned"] = None,
29	) -> str:
30	"""List all available Boilerworks templates, optionally filtered."""
31	from boilerworks.registry import Registry
32
33	registry = Registry()
34	templates = registry.list_all()
35
36	if size:
37	templates = [t for t in templates if t.size == size]
38	if language:
39	templates = [t for t in templates if t.language == language]
40	if status:
41	templates = [t for t in templates if t.status == status]
42
43	rows = [
44	{
45	"name": t.name,
46	"size": t.size,
47	"language": t.language,
48	"backend": t.backend,
49	"frontend": t.frontend,
50	"status": t.status,
51	"best_for": t.best_for,
52	}
53	for t in templates
54	]
55	return json.dumps(rows, indent=2)
56
57
58	@mcp.tool()
59	def get_template(
60	name: Annotated[str, "Template name, e.g. django-nextjs"],
61	) -> str:
62	"""Get full details for a specific Boilerworks template."""
63	from boilerworks.registry import Registry
64
65	registry = Registry()
66	template = registry.get_by_name(name)
67
68	if template is None:
69	valid = ", ".join(sorted(registry.names()))
70	return f"Template '{name}' not found. Available: {valid}"
71
72	return json.dumps(template.model_dump(), indent=2)
73
74
75	@mcp.tool()
76	def search_templates(
77	query: Annotated[str, "Search query matched against name, description, and best_for"],
78	) -> str:
79	"""Search templates by keyword."""
80	from boilerworks.registry import Registry
81
82	registry = Registry()
83	results = registry.search(query)
84
85	if not results:
86	return f"No templates matched '{query}'."
87
88	rows = [{"name": t.name, "size": t.size, "backend": t.backend, "frontend": t.frontend, "best_for": t.best_for} for t in results]
89	return json.dumps(rows, indent=2)
90
91
92	# ── Manifest ──────────────────────────────────────────────────────────────────
93
94
95	@mcp.tool()
96	def create_manifest(
97	project: Annotated[str, "Project slug (lowercase, letters/digits/hyphens)"],
98	family: Annotated[str, "Template family name, e.g. django-nextjs"],
99	size: Annotated[str, "Template size: full \| micro \| edge"],
100	cloud: Annotated[str \| None, "Cloud provider: aws \| gcp \| azure"] = None,
101	region: Annotated[str \| None, "Cloud region, e.g. us-east-1"] = None,
102	topology: Annotated[str, "standard \| api-only \| omni"] = "standard",
103	domain: Annotated[str \| None, "Production domain, e.g. myapp.com"] = None,
104	ops: Annotated[bool, "Include Terraform infrastructure repo"] = False,
105	mobile: Annotated[bool, "Include mobile app template (Full only)"] = False,
106	web_presence: Annotated[bool, "Include marketing site template (Full only)"] = False,
107	compliance: Annotated[list[str] \| None, "Compliance requirements: soc2 \| hipaa \| pci-dss \| gdpr"] = None,
108	email: Annotated[str \| None, "Email service: ses \| sendgrid \| mailgun"] = None,
109	storage: Annotated[str \| None, "File storage: s3 \| gcs \| azure-blob"] = None,
110	search: Annotated[str \| None, "Search engine: opensearch \| meilisearch"] = None,
111	cache: Annotated[str, "Cache: redis \| memcached"] = "redis",
112	database: Annotated[str, "Database: postgres \| mysql \| sqlite"] = "postgres",
113	e2e: Annotated[str \| None, "E2E framework: playwright \| cypress"] = None,
114	) -> str:
115	"""Build and validate a boilerworks.yaml manifest. Returns the YAML content ready to write to disk."""
116	from boilerworks.manifest import BoilerworksManifest, DataConfig, ServicesConfig, TestingConfig
117
118	try:
119	manifest = BoilerworksManifest(
120	project=project,
121	family=family,
122	size=size,
123	topology=topology,
124	cloud=cloud,
125	ops=ops,
126	region=region,
127	domain=domain,
128	mobile=mobile,
129	web_presence=web_presence,
130	compliance=compliance or [],
131	services=ServicesConfig(
132	email=email,
133	storage=storage,
134	search=search,
135	cache=cache,
136	),
137	data=DataConfig(database=database),
138	testing=TestingConfig(e2e=e2e),
139	)
140	except Exception as exc:
141	return f"Invalid manifest: {exc}"
142
143	return manifest.to_yaml()
144
145
146	@mcp.tool()
147	def validate_manifest(
148	yaml_content: Annotated[str, "Contents of a boilerworks.yaml file to validate"],
149	) -> str:
150	"""Validate a boilerworks.yaml manifest. Returns 'valid' or a description of the errors."""
151	from boilerworks.manifest import BoilerworksManifest
152
153	try:
154	BoilerworksManifest.from_yaml(yaml_content)
155	return "valid"
156	except Exception as exc:
157	return f"invalid: {exc}"
158
159
160	# ── Project generation ─────────────────────────────────────────────────────────
161
162
163	def _run_cli(args: list[str], manifest_yaml: str) -> str:
164	"""Write manifest to a temp file, run the boilerworks CLI, return combined output."""
165	import subprocess
166	import sys
167	import tempfile
168
169	with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
170	f.write(manifest_yaml)
171	tmp_path = f.name
172
173	try:
174	result = subprocess.run(
175	[sys.executable, "-m", "boilerworks.cli"] + args + ["--manifest", tmp_path],
176	capture_output=True,
177	text=True,
178	)
179	output = (result.stdout + result.stderr).strip()
180	return output or ("OK" if result.returncode == 0 else "Command failed with no output.")
181	finally:
182	Path(tmp_path).unlink(missing_ok=True)
183
184
185	@mcp.tool()
186	def dry_run(
187	manifest_yaml: Annotated[str, "Contents of a boilerworks.yaml manifest"],
188	output_dir: Annotated[str, "Directory where the project would be created"] = ".",
189	) -> str:
190	"""Preview what boilerworks init would do without writing any files."""
191	return _run_cli(["init", "--dry-run", "--output", output_dir], manifest_yaml)
192
193
194	@mcp.tool()
195	def init_project(
196	manifest_yaml: Annotated[str, "Contents of a boilerworks.yaml manifest"],
197	output_dir: Annotated[str, "Directory to generate the project in"] = ".",
198	) -> str:
199	"""
200	Scaffold a new project from a boilerworks.yaml manifest.
201	Clones the template, applies substitutions, and runs git init.
202	Requires network access (GitHub). This may take 10-30 seconds.
203	"""
204	return _run_cli(["init", "--output", output_dir], manifest_yaml)
205
206
207	def main() -> None:
208	mcp.run()
209
210
211	if __name__ == "__main__":
212	main()

M pyproject.toml

		--- pyproject.toml
		+++ pyproject.toml
		@@ -27,12 +27,16 @@
27	27	"jinja2>=3.0",
28	28	"gitpython>=3.1",
29	29	"pyyaml>=6.0",
30	30	]
31	31
	32	+[project.optional-dependencies]
	33	+mcp = ["mcp[cli]>=1.0"]
	34	+
32	35	[project.scripts]
33	36	boilerworks = "boilerworks.cli:main"
	37	+boilerworks-mcp = "boilerworks.mcp_server:main"
34	38
35	39	[project.urls]
36	40	Homepage = "https://boilerworks.dev"
37	41	Repository = "https://github.com/ConflictHQ/boilerworks"
38	42	Issues = "https://github.com/ConflictHQ/boilerworks/issues"
39	43
40	44	ADDED skill/package.json
41	45	ADDED skill/skill.md

	--- pyproject.toml
	+++ pyproject.toml
	@@ -27,12 +27,16 @@
27	"jinja2>=3.0",
28	"gitpython>=3.1",
29	"pyyaml>=6.0",
30	]
31



32	[project.scripts]
33	boilerworks = "boilerworks.cli:main"

34
35	[project.urls]
36	Homepage = "https://boilerworks.dev"
37	Repository = "https://github.com/ConflictHQ/boilerworks"
38	Issues = "https://github.com/ConflictHQ/boilerworks/issues"
39
40	DDED skill/package.json
41	DDED skill/skill.md

	--- pyproject.toml
	+++ pyproject.toml
	@@ -27,12 +27,16 @@
27	"jinja2>=3.0",
28	"gitpython>=3.1",
29	"pyyaml>=6.0",
30	]
31
32	[project.optional-dependencies]
33	mcp = ["mcp[cli]>=1.0"]
34
35	[project.scripts]
36	boilerworks = "boilerworks.cli:main"
37	boilerworks-mcp = "boilerworks.mcp_server:main"
38
39	[project.urls]
40	Homepage = "https://boilerworks.dev"
41	Repository = "https://github.com/ConflictHQ/boilerworks"
42	Issues = "https://github.com/ConflictHQ/boilerworks/issues"
43
44	DDED skill/package.json
45	DDED skill/skill.md

A skill/package.json

+29

		--- a/skill/package.json
		+++ b/skill/package.json
		@@ -0,0 +1,29 @@
	1	+{
	2	+ "name": "@conflict/boilerworks",
	3	+ "version": "0.1.0",
	4	+ "description": "Claude Code skill for Boilerworks — AI-ready project templates that ship fast",
	5	+ "keywords": [
	6	+ "claude",
	7	+ "claude-code",
	8	+ "skill",
	9	+ "boilerworks",
	10	+ "scaffolding",
	11	+ "templates",
	12	+ "ai"
	13	+ ],
	14	+ "homepage": "https://boilerworks.dev",
	15	+ "repository": {
	16	+ "type": "git",
	17	+ "url": "https://github.com/ConflictHQ/boilerworks.git",
	18	+ "directory": "skill"
	19	+ },
	20	+ "license": "MIT",
	21	+ "files": [
	22	+ "skill.md"
	23	+ ],
	24	+ "claude": {
	25	+ "skill": "skill.md",
	26	+ "name": "boilerworks",
	27	+ "description": "AI-ready Boilerworks project templates — pick a stack, ship in minutes"
	28	+ }
	29	+}

	--- a/skill/package.json
	+++ b/skill/package.json
	@@ -0,0 +1,29 @@

	--- a/skill/package.json
	+++ b/skill/package.json
	@@ -0,0 +1,29 @@
1	{
2	"name": "@conflict/boilerworks",
3	"version": "0.1.0",
4	"description": "Claude Code skill for Boilerworks — AI-ready project templates that ship fast",
5	"keywords": [
6	"claude",
7	"claude-code",
8	"skill",
9	"boilerworks",
10	"scaffolding",
11	"templates",
12	"ai"
13	],
14	"homepage": "https://boilerworks.dev",
15	"repository": {
16	"type": "git",
17	"url": "https://github.com/ConflictHQ/boilerworks.git",
18	"directory": "skill"
19	},
20	"license": "MIT",
21	"files": [
22	"skill.md"
23	],
24	"claude": {
25	"skill": "skill.md",
26	"name": "boilerworks",
27	"description": "AI-ready Boilerworks project templates — pick a stack, ship in minutes"
28	}
29	}

A skill/skill.md

+137

		--- a/skill/skill.md
		+++ b/skill/skill.md
		@@ -0,0 +1,137 @@
	1	+# Boilerworks
	2	+
	3	+You are an expert assistant for the Boilerworks project scaffolding system. Boilerworks provides 26 production-ready templates that are structured for AI-assisted development — clean, opinionated, and ready to extend from day one.
	4	+
	5	+## What Boilerworks is
	6	+
	7	+A CLI tool (`pip install boilerworks`) that clones and configures a project template from a manifest file (`boilerworks.yaml`). Every template ships with auth, CI/CD, Docker, database, and deployment config already in place. The user's job — and yours — is to build the business logic on top.
	8	+
	9	+## Installation
	10	+
	11	+```bash
	12	+pip install boilerworks
	13	+# or with uv (recommended):
	14	+uv tool install boilerworks
	15	+```
	16	+
	17	+Requires Python 3.12+.
	18	+
	19	+## Core workflow
	20	+
	21	+```bash
	22	+boilerworks setup # interactive wizard → writes boilerworks.yaml
	23	+boilerworks init # clone + configure the chosen template
	24	+cd <project>
	25	+docker compose up -d # full stack running
	26	+```
	27	+
	28	+### Key commands
	29	+
	30	+```bash
	31	+boilerworks list # all 26 templates
	32	+boilerworks list --size micro # filter by size
	33	+boilerworks list --language python # filter by language
	34	+boilerworks init --dry-run # preview without writing
	35	+boilerworks init --output /path # write to specific directory
	36	+```
	37	+
	38	+## Template catalogue
	39	+
	40	+### Full templates — apps with users, org management, session auth
	41	+
	42	+\| Template \| Backend \| Frontend \|
	43	+\|---\|---\|---\|
	44	+\| django-nextjs \| Django 5 + Strawberry GraphQL \| Next.js 16 \|
	45	+\| nestjs-nextjs \| NestJS 11 \| Next.js 16 \|
	46	+\| rails-hotwire \| Rails 8 \| Hotwire + Tailwind \|
	47	+\| rails-nextjs \| Rails 8 \| Next.js 16 \|
	48	+\| spring-angular \| Spring Boot 3 \| Angular 19 \|
	49	+\| go-nextjs \| Go + Chi \| Next.js 16 \|
	50	+\| phoenix-liveview \| Phoenix 1.7 \| LiveView \|
	51	+\| laravel-vue \| Laravel 12 \| Inertia + Vue 3 \|
	52	+\| django-htmx \| Django 5 \| HTMX + Alpine.js \|
	53	+\| fastapi-nextjs \| FastAPI \| Next.js 16 \|
	54	+\| spring-nextjs \| Spring Boot 3 \| Next.js 16 \|
	55	+\| laravel-livewire \| Laravel 12 \| Livewire 3 \|
	56	+\| go-htmx \| Go + Chi \| HTMX + Templ \|
	57	+\| fastapi-htmx \| FastAPI \| HTMX + Alpine.js \|
	58	+\| saleor-nextjs \| Saleor (Django) \| Next.js 16 \|
	59	+
	60	+### Micro templates — API services with API-key auth
	61	+
	62	+\| Template \| Backend \|
	63	+\|---\|---\|
	64	+\| django-micro \| Django 5 (DRF/Ninja) \|
	65	+\| fastapi-micro \| FastAPI \|
	66	+\| nestjs-micro \| NestJS 11 \|
	67	+\| go-micro \| Go + Chi \|
	68	+\| rust-micro \| Axum (Rust) \|
	69	+\| cherrypy-micro \| CherryPy \|
	70	+
	71	+### Edge templates — serverless / Cloudflare
	72	+
	73	+\| Template \| Framework \|
	74	+\|---\|---\|
	75	+\| sveltekit-full \| SvelteKit \|
	76	+\| remix-full \| Remix \|
	77	+\| hono-micro \| Hono (Cloudflare Workers) \|
	78	+\| nuxt-full \| Nuxt 4 \|
	79	+\| astro-site \| Astro \|
	80	+
	81	+## boilerworks.yaml reference
	82	+
	83	+```yaml
	84	+project: my-app # slug: lowercase, letters/digits/hyphens
	85	+family: django-nextjs # template name from catalogue
	86	+size: full # full \| micro \| edge
	87	+topology: standard # standard \| api-only \| omni
	88	+cloud: aws # aws \| gcp \| azure \| null
	89	+region: us-east-1
	90	+domain: myapp.com
	91	+mobile: false # Full only
	92	+web_presence: false # Full only
	93	+compliance:
	94	+ - soc2 # soc2 \| hipaa \| pci-dss \| gdpr
	95	+services:
	96	+ email: ses # ses \| sendgrid \| mailgun \| null
	97	+ storage: s3 # s3 \| gcs \| azure-blob \| null
	98	+ search: opensearch # opensearch \| meilisearch \| null
	99	+ cache: redis # redis \| memcached \| null
	100	+data:
	101	+ database: postgres # postgres \| mysql \| sqlite
	102	+ migrations: true
	103	+ seed_data: true
	104	+testing:
	105	+ e2e: playwright # playwright \| cypress \| null
	106	+ unit: true
	107	+ integration: true
	108	+```
	109	+
	110	+## How to help users
	111	+
	112	+Picking a template: Ask what they're building. Full = user-facing product with accounts. Micro = internal API or service. Edge = content site, serverless, Cloudflare. Match backend to their team's language preference.
	113	+
	114	+Setting up a project: Walk them through `boilerworks setup` or help them write `boilerworks.yaml` directly if they know what they want. Then run `boilerworks init`.
	115	+
	116	+Working inside a generated project: Every template has a `bootstrap.md` (primary conventions doc) and `CLAUDE.md` (agent-specific notes). Read both before writing any code. The `CLAUDE.md` in each template points to `bootstrap.md` — that doc is written so an agent can generate correct, idiomatic code without exploring the codebase first.
	117	+
	118	+Common template conventions (django-nextjs and others):
	119	+- All business models inherit from `Tracking` (audit trails) or `BaseCoreModel` (+ guid/name/slug)
	120	+- Soft deletes only — set `deleted_at`/`deleted_by`, never call `.delete()` on business objects
	121	+- Never expose integer PKs in API responses — use `guid` or relay global ID
	122	+- Auth check required at the top of every resolver/mutation/controller
	123	+- `make lint` before committing; `make test` before pushing
	124	+
	125	+Adding a new app (django-nextjs):
	126	+```bash
	127	+./run.sh manage startapp myapp
	128	+# register in config/settings.py INSTALLED_APPS
	129	+# models → migrations → admin → schema → tests
	130	+make migrations && make test
	131	+```
	132	+
	133	+## What's already built in every Full template
	134	+
	135	+Auth, session management, org management, permissions (role-based), admin panel, CI/CD pipeline, Docker Compose stack, database migrations, seed data, email, file storage, background jobs (Celery or equivalent), feature flags, rate limiting, soft deletes, audit history.
	136	+
	137	+Users should never rebuild any of this. Their job is to add domain models, business logic, and UI on top.

	--- a/skill/skill.md
	+++ b/skill/skill.md
	@@ -0,0 +1,137 @@

	--- a/skill/skill.md
	+++ b/skill/skill.md
	@@ -0,0 +1,137 @@
1	# Boilerworks
2
3	You are an expert assistant for the Boilerworks project scaffolding system. Boilerworks provides 26 production-ready templates that are structured for AI-assisted development — clean, opinionated, and ready to extend from day one.
4
5	## What Boilerworks is
6
7	A CLI tool (`pip install boilerworks`) that clones and configures a project template from a manifest file (`boilerworks.yaml`). Every template ships with auth, CI/CD, Docker, database, and deployment config already in place. The user's job — and yours — is to build the business logic on top.
8
9	## Installation
10
11	```bash
12	pip install boilerworks
13	# or with uv (recommended):
14	uv tool install boilerworks
15	```
16
17	Requires Python 3.12+.
18
19	## Core workflow
20
21	```bash
22	boilerworks setup # interactive wizard → writes boilerworks.yaml
23	boilerworks init # clone + configure the chosen template
24	cd <project>
25	docker compose up -d # full stack running
26	```
27
28	### Key commands
29
30	```bash
31	boilerworks list # all 26 templates
32	boilerworks list --size micro # filter by size
33	boilerworks list --language python # filter by language
34	boilerworks init --dry-run # preview without writing
35	boilerworks init --output /path # write to specific directory
36	```
37
38	## Template catalogue
39
40	### Full templates — apps with users, org management, session auth
41
42	\| Template \| Backend \| Frontend \|
43	\|---\|---\|---\|
44	\| django-nextjs \| Django 5 + Strawberry GraphQL \| Next.js 16 \|
45	\| nestjs-nextjs \| NestJS 11 \| Next.js 16 \|
46	\| rails-hotwire \| Rails 8 \| Hotwire + Tailwind \|
47	\| rails-nextjs \| Rails 8 \| Next.js 16 \|
48	\| spring-angular \| Spring Boot 3 \| Angular 19 \|
49	\| go-nextjs \| Go + Chi \| Next.js 16 \|
50	\| phoenix-liveview \| Phoenix 1.7 \| LiveView \|
51	\| laravel-vue \| Laravel 12 \| Inertia + Vue 3 \|
52	\| django-htmx \| Django 5 \| HTMX + Alpine.js \|
53	\| fastapi-nextjs \| FastAPI \| Next.js 16 \|
54	\| spring-nextjs \| Spring Boot 3 \| Next.js 16 \|
55	\| laravel-livewire \| Laravel 12 \| Livewire 3 \|
56	\| go-htmx \| Go + Chi \| HTMX + Templ \|
57	\| fastapi-htmx \| FastAPI \| HTMX + Alpine.js \|
58	\| saleor-nextjs \| Saleor (Django) \| Next.js 16 \|
59
60	### Micro templates — API services with API-key auth
61
62	\| Template \| Backend \|
63	\|---\|---\|
64	\| django-micro \| Django 5 (DRF/Ninja) \|
65	\| fastapi-micro \| FastAPI \|
66	\| nestjs-micro \| NestJS 11 \|
67	\| go-micro \| Go + Chi \|
68	\| rust-micro \| Axum (Rust) \|
69	\| cherrypy-micro \| CherryPy \|
70
71	### Edge templates — serverless / Cloudflare
72
73	\| Template \| Framework \|
74	\|---\|---\|
75	\| sveltekit-full \| SvelteKit \|
76	\| remix-full \| Remix \|
77	\| hono-micro \| Hono (Cloudflare Workers) \|
78	\| nuxt-full \| Nuxt 4 \|
79	\| astro-site \| Astro \|
80
81	## boilerworks.yaml reference
82
83	```yaml
84	project: my-app # slug: lowercase, letters/digits/hyphens
85	family: django-nextjs # template name from catalogue
86	size: full # full \| micro \| edge
87	topology: standard # standard \| api-only \| omni
88	cloud: aws # aws \| gcp \| azure \| null
89	region: us-east-1
90	domain: myapp.com
91	mobile: false # Full only
92	web_presence: false # Full only
93	compliance:
94	- soc2 # soc2 \| hipaa \| pci-dss \| gdpr
95	services:
96	email: ses # ses \| sendgrid \| mailgun \| null
97	storage: s3 # s3 \| gcs \| azure-blob \| null
98	search: opensearch # opensearch \| meilisearch \| null
99	cache: redis # redis \| memcached \| null
100	data:
101	database: postgres # postgres \| mysql \| sqlite
102	migrations: true
103	seed_data: true
104	testing:
105	e2e: playwright # playwright \| cypress \| null
106	unit: true
107	integration: true
108	```
109
110	## How to help users
111
112	Picking a template: Ask what they're building. Full = user-facing product with accounts. Micro = internal API or service. Edge = content site, serverless, Cloudflare. Match backend to their team's language preference.
113
114	Setting up a project: Walk them through `boilerworks setup` or help them write `boilerworks.yaml` directly if they know what they want. Then run `boilerworks init`.
115
116	Working inside a generated project: Every template has a `bootstrap.md` (primary conventions doc) and `CLAUDE.md` (agent-specific notes). Read both before writing any code. The `CLAUDE.md` in each template points to `bootstrap.md` — that doc is written so an agent can generate correct, idiomatic code without exploring the codebase first.
117
118	Common template conventions (django-nextjs and others):
119	- All business models inherit from `Tracking` (audit trails) or `BaseCoreModel` (+ guid/name/slug)
120	- Soft deletes only — set `deleted_at`/`deleted_by`, never call `.delete()` on business objects
121	- Never expose integer PKs in API responses — use `guid` or relay global ID
122	- Auth check required at the top of every resolver/mutation/controller
123	- `make lint` before committing; `make test` before pushing
124
125	Adding a new app (django-nextjs):
126	```bash
127	./run.sh manage startapp myapp
128	# register in config/settings.py INSTALLED_APPS
129	# models → migrations → admin → schema → tests
130	make migrations && make test
131	```
132
133	## What's already built in every Full template
134
135	Auth, session management, org management, permissions (role-based), admin panel, CI/CD pipeline, Docker Compose stack, database migrations, seed data, email, file storage, background jobs (Celery or equivalent), feature flags, rate limiting, soft deletes, audit history.
136
137	Users should never rebuild any of this. Their job is to add domain models, business logic, and UI on top.

BoilerWorks

Keyboard Shortcuts