docs: document GitHub template workflow

README.md

@@ -4,7 +4,11 @@ Last reviewed: 2026-06-03
 
 Opinionated sane defaults and conventions for software projects.
 
-This is not a scaffolding CLI. It is a reference repo that gives agents and humans a shared baseline for how new projects should be shaped: repository layout, local development, dependency safety, CI, agent instructions, operational memory, and documentation. It comes from 508.dev practice, but it is meant to be useful outside 508.dev too.
+This is not a scaffolding CLI. It is a reference repo and GitHub template that
+gives agents and humans a shared baseline for how new projects should be shaped:
+repository layout, local development, dependency safety, CI, agent instructions,
+operational memory, and documentation. It comes from 508.dev practice, but it
+is meant to be useful outside 508.dev too.
 
 Point an agent at this repo when starting or normalizing a project. The agent should inspect the target repo, ask clarifying questions when the product or stack is ambiguous, and then copy or adapt only the conventions that fit.
 
@@ -33,7 +37,30 @@ Point an agent at this repo when starting or normalizing a project. The agent sh
 
 ## Quickstart
 
-Use the repo directly:
+### Create A New Repository
+
+Use GitHub's `Use this template` button to create a new repository from
+`508-dev/508-devkit`.
+
+GitHub templates copy the default-branch file tree. Treat the generated
+repository as a bootstrap workspace: the first PR should select the root
+hygiene files, stacks, extras, docs, and workflows that fit the product, then
+delete the rest.
+
+Recommended first prompt in the generated repo:
+
+```text
+This repository was generated from 508 Devkit. Do a template selection pass:
+inspect the product goal and existing files, keep only the root hygiene, stacks,
+extras, docs, and workflows that fit this project, delete the rest, rename all
+devkit/example identifiers, and run the narrowest relevant checks.
+```
+
+See `docs/github-template.md` for the cleanup checklist.
+
+### Normalize An Existing Repository
+
+Use the repo directly as a reference:
 
 ```text
 Use https://github.com/508-dev/508-devkit or a local checkout of it as the
@@ -80,11 +107,12 @@ extras          Optional workflow, deployment, and support add-ons
 2. Read `docs/pattern-report.md`.
 3. Read `docs/tooling.md`.
 4. Read `docs/template-proposal.md`.
-5. Read `docs/frontend.md`.
-6. Copy `.env.example` to `.env`.
-7. Run `./scripts/worktree-ports.sh env`.
-8. Run `./scripts/docker-compose.sh up -d postgres redis`.
-9. Run `./scripts/dev.sh`.
+5. Read `docs/github-template.md` when starting from GitHub's template button.
+6. Read `docs/frontend.md`.
+7. Copy `.env.example` to `.env`.
+8. Run `./scripts/worktree-ports.sh env`.
+9. Run `./scripts/docker-compose.sh up -d postgres redis`.
+10. Run `./scripts/dev.sh`.
 
 The port helper's `env` command is the print-only URL/port mode. It prints
 `WEB_URL` first, followed by `WEB_PORT` and the rest of the assigned worktree
@@ -124,7 +152,8 @@ commands to `pnpm install --frozen-lockfile`.
 
 ## Pick-And-Choose Stacks And Extras
 
-This repository intentionally includes files that conflict with each other. It is a starter template, not an installable preset.
+This repository intentionally includes files that conflict with each other. It
+is a template source, not an installable preset or final generated app.
 
 - `stacks/typescript/`: framework-neutral TypeScript conventions, Drizzle
   examples, Biome, Vitest.
@@ -141,11 +170,19 @@ This repository intentionally includes files that conflict with each other. It i
 - `extras/todo-to-issue/`: opt-in workflow for turning TODO comments into GitHub issues.
 - `.sops.yaml.example`: optional SOPS starter only for repos that need encrypted files.
 
-Keep root defaults for most new projects: shell wrappers, shell worktree ports, and example Compose-managed infra. Select language/runtime stacks such as `stacks/typescript/`, `stacks/python/`, future `stacks/go/`, or future `stacks/rust/` based on the target project. Treat stack files as conventions to adapt, not product code to copy blindly.
+Keep root defaults for most new projects: shell wrappers, shell worktree ports,
+and example Compose-managed infra. Select language/runtime stacks such as
+`stacks/typescript/`, `stacks/python/`, future `stacks/go/`, or future
+`stacks/rust/` based on the target project. Treat stack files as conventions to
+adapt, not product code to copy blindly. If this repo was used through
+GitHub's template button, do the same selection and pruning before feature work.
 
 ## Agent Notes
 
 - Never copy the whole repository into a target project.
+- A GitHub-generated repo starts with the whole file tree by design; make the
+  first project PR a template selection pass that removes irrelevant stacks,
+  extras, workflows, and docs.
 - Start with root hygiene files, then select only the stacks and extras that
   match the target repo.
 - Treat `stacks/` as peer language/runtime convention packs. TypeScript and

docs/agent-walkthrough.md

@@ -9,15 +9,26 @@ Use /path/to/508-devkit as the project bootstrap reference.
 Inspect my target repo, ask any necessary questions, then apply the relevant conventions.
 ```
 
+For a repository generated from GitHub's `Use this template` button:
+
+```text
+This repository was generated from 508 Devkit. Do a template selection pass:
+inspect the product goal and existing files, keep only the root hygiene, stacks,
+extras, docs, and workflows that fit this project, delete the rest, rename all
+devkit/example identifiers, and run the narrowest relevant checks.
+```
+
 ## Expected Agent Flow
 
 1. Inspect the target repo before editing.
 2. Read existing `AGENTS.md`, package manifests, lockfiles, workflows, Compose files, scripts, and docs.
 3. Decide which devkit conventions already exist.
 4. Ask questions only when the product shape or stack cannot be inferred safely.
 5. Apply the smallest useful set of files.
-6. Run focused validation.
-7. Summarize what was adopted, skipped, and why.
+6. If the repo was generated from the GitHub template, delete unselected stacks,
+   extras, example app names, and docs that do not describe the target project.
+7. Run focused validation.
+8. Summarize what was adopted, skipped, and why.
 
 ## Example Questions
 

docs/github-template.md

@@ -0,0 +1,72 @@
+# GitHub Template Usage
+
+508 Devkit is marked as a GitHub template repository, but it is still a
+pick-and-choose reference repo. GitHub templates copy the default-branch file
+tree into a new repository. That generated repository should be treated as a
+bootstrap workspace, not as the final project shape.
+
+## Intended Flow
+
+1. Create a new repository from the GitHub `Use this template` button.
+2. Make the first project PR a template selection pass.
+3. Keep the root hygiene files that apply to most software repos.
+4. Select only the language stacks and extras that match the project.
+5. Delete unselected examples, placeholder workflows, and docs that no longer
+   describe the project.
+6. Rename package names, env defaults, service names, and documentation from
+   devkit examples to the real product.
+7. Run the narrowest relevant checks before building product features.
+
+The selection pass is part of using the template. Do not start feature work
+while the repository still contains irrelevant stacks or optional extras.
+
+## Keep By Default
+
+These files are broadly useful for most generated repos, with project-specific
+edits:
+
+- `AGENTS.md`, `CLAUDE.md`, and `.cursor/rules/`.
+- `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, and the docs that still match
+  the project.
+- `scripts/` entrypoints for lint, typecheck, test, dev, Compose, and worktree
+  ports.
+- `.env.example`, `.gitignore`, `.dockerignore`, `.editorconfig`, and
+  `.worktreeinclude`.
+- `.github/` PR and issue templates when the project uses GitHub.
+
+## Select Explicitly
+
+Keep these only when they fit the project:
+
+- `stacks/typescript/` for JavaScript or TypeScript projects.
+- `stacks/typescript/pnpm/` when pnpm is the chosen JavaScript package manager.
+- `stacks/python/` for Python APIs, workers, packages, or tools.
+- `stacks/ruby/` for Ruby, Rails, or Rack projects.
+- `compose.yml` and `docker-compose.yml` only for the local infrastructure the
+  project actually needs.
+- `extras/` directories only after confirming the workflow, owners, secrets,
+  permissions, and deployment needs.
+- `skills/` only when the target repo wants to ship project-local agent skills.
+
+## Remove Or Rewrite
+
+Before calling the generated repo ready, remove or rewrite:
+
+- Unused language stacks.
+- Example app/package names such as `508-devkit`, `example_api`, and
+  `example_shared`.
+- Optional GitHub extras with placeholder owners or extra permissions.
+- Docs that describe template design history instead of the generated project.
+- Databases, caches, object storage, observability, or LLM env vars that the
+  project does not use.
+
+## Agent Prompt
+
+Use this prompt immediately after creating a repository from the template:
+
+```text
+This repository was generated from 508 Devkit. Do a template selection pass:
+inspect the product goal and existing files, keep only the root hygiene, stacks,
+extras, docs, and workflows that fit this project, delete the rest, rename all
+devkit/example identifiers, and run the narrowest relevant checks.
+```

docs/interfaces.md

@@ -9,10 +9,16 @@ Use this repository as the source of truth.
 It is best for:
 
 - Copying concrete files into a new project.
+- Creating a bootstrap repository through GitHub's `Use this template` button.
 - Reviewing conventions in GitHub.
 - Evolving scripts, CI, docs, and examples through normal PRs.
 - Letting any agent or human inspect the same artifact.
 
+GitHub's template button copies the default branch file tree. That is a useful
+starting point, but generated repos should immediately run a template selection
+pass: keep applicable root hygiene, choose stacks and extras intentionally, and
+delete everything else before product work starts.
+
 ## Downloadable Skill
 
 A skill is useful as the agent-facing interface over this repo.

docs/template-proposal.md

@@ -2,7 +2,14 @@
 
 ## Design Goal
 
-This template captures recurring conventions from existing repositories so coding agents can create project-specific files on demand without needing a scaffolding CLI.
+This template captures recurring conventions from existing repositories so
+coding agents can create project-specific files on demand without needing a
+scaffolding CLI.
+
+When used as a GitHub template repository, the first generated-repo change
+should be a selection pass. GitHub copies the default branch file tree, so users
+and agents must prune unselected stacks, extras, example apps, and design-history
+docs before feature work starts.
 
 It is optimized for:
 
@@ -51,9 +58,18 @@ It is optimized for:
 - For product repos with browser UI, add Playwright after the first interactive flow exists.
 - For LLM features, add deterministic eval fixtures before live model evals.
 
+## GitHub Template Mode
+
+Marking this repo as a GitHub template improves discoverability, but it does
+not change the pick-and-choose model. Generated repos should keep the broad root
+hygiene, explicitly select one or more stacks, and remove irrelevant examples.
+
+See `docs/github-template.md` for the generated-repo cleanup checklist.
+
 ## Non-Goals
 
 - No CLI generator.
+- No expectation that generated repos keep every file from this repo.
 - No mandatory deployment platform.
 - No full app implementation.
 - No secret management opinion beyond environment-variable contracts and CI secret boundaries.

skills/508-devkit/SKILL.md

@@ -21,6 +21,11 @@ Canonical repo: https://github.com/508-dev/508-devkit
   object storage, CODEOWNERS, Gitleaks, Dependency Review, and TODO-to-issue.
 - `.context/` is workspace-local agent scratch and must not be committed.
 
+When the target repo was generated from GitHub's `Use this template` button,
+treat the first change as a template selection pass. GitHub copies the
+default-branch file tree; the generated repo should not keep every stack, extra,
+example app, or design-history document.
+
 ## Workflow
 
 1. Inspect the target repo first:
@@ -71,7 +76,9 @@ Canonical repo: https://github.com/508-dev/508-devkit
    - Use SOPS only when encrypted tracked files are needed.
 3. Copy or adapt files from the `508-devkit` repository.
 4. Update names, package scopes, ports, and docs to fit the target project.
-5. Run the narrowest relevant checks.
+5. In GitHub-template-generated repos, delete unselected stacks, extras,
+   workflows, example names, and docs before starting product feature work.
+6. Run the narrowest relevant checks.
 
 ## Worktree And Docker Files