docs(runbooks): add repository bootstrap guide

AGENTS.md

@@ -97,6 +97,7 @@ For recurring organization workflows, prefer the runbooks and keep the first pas
 - issue and PR triage: `runbooks/triage.md`
 - label maintenance: `runbooks/labels.md`
 - project tracker automation: `runbooks/project-tracker.md`
+- new-repository bootstrap: `runbooks/new-repository.md`
 - ADR drafting: `runbooks/adr.md`
 - release coordination and release-model classification: `runbooks/release.md`
 
@@ -139,6 +140,7 @@ Do not silently work around drift. Open or update an issue in `z-shell/.github`,
 - `runbooks/org-review.md`
 - `runbooks/adr.md`
 - `runbooks/labels.md`
+- `runbooks/new-repository.md`
 - `runbooks/project-tracker.md`
 - `runbooks/release.md`
 - `runbooks/triage.md`

runbooks/new-repository.md

@@ -0,0 +1,133 @@
+# Runbook — New Repository Bootstrap
+
+How to create a new z-shell plugin, annex, or module repository without copying
+unreviewed files from an existing project.
+
+**Hard rule:** keep organization-wide instructions, workflows, and issue
+metadata centralized. Add child-repository files only when the repository needs
+project-specific behavior.
+
+## Step 1 — Classify and record the repository
+
+1. Open a tracker issue describing the artifact, owner, consumers, and release
+   class from `runbooks/release.md`.
+2. Choose the repository name:
+   - plugin: `zsh-<name>`
+   - annex: `z-a-<name>`
+   - compiled module: a short descriptive name
+3. Add the clone to the private meta-workspace `.gitmodules` and
+   `workspace/repos.yml`. Do not put local paths, credentials, or machine facts
+   in the public repository.
+4. Apply canonical labels via `runbooks/labels.md` and verify project-tracker
+   enrollment via `runbooks/project-tracker.md`.
+
+## Step 2 — Create the common repository envelope
+
+Every repository starts with:
+
+```text
+LICENSE
+README.md
+.editorconfig
+.gitignore
+.github/
+  workflows/
+```
+
+Use the organization-approved license for the artifact. The initial `README.md`
+must state the purpose, install path, supported shell/runtime, verification
+command, release model, and wiki link.
+
+Do not copy generic `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/agents/`, or
+`.github/instructions/` files into child repositories. Link to the organization
+guidance when a short project-specific `AGENTS.md` is genuinely required.
+
+Use organization issue and pull-request templates by default. Add a child
+template only when the repository has a specific intake field that the shared
+template cannot express.
+
+## Step 3 — Add the artifact structure
+
+### Plugin
+
+```text
+zsh-<name>.plugin.zsh
+functions/                 # only when autoloaded functions are needed
+lib/                       # only when sourced helpers are needed
+docs/                      # short repository-local usage only
+```
+
+Follow the entry-point, `ZERO`, `Plugins`, guarded `fpath`, and unload patterns
+in `PATTERNS.md` and the Z-Shell Plugin Standard. The unload function must
+reverse plugin-owned side effects.
+
+### Annex
+
+```text
+z-a-<name>.plugin.zsh
+functions/
+docs/                      # short repository-local usage only
+```
+
+Keep annex handlers in `functions/`, start them with strict Zsh emulation, and
+register only implemented handlers. Document durable ecosystem usage in the
+wiki and link to it from the repository.
+
+### Compiled module
+
+Compiled modules require a design issue before scaffolding because toolchains
+and loader contracts vary. The issue must define:
+
+- source and generated-file layout
+- supported Zsh versions and platforms
+- build and test commands
+- install and load path
+- release artifact and semantic-tag policy
+
+Do not invent a reusable module template from a single implementation. Add one
+to this repository only after the shape is verified in multiple module repos.
+
+## Step 4 — Install CI from canonical templates
+
+Start from the organization workflow templates:
+
+- `workflow-templates/zsh-ci.yml` for Zsh syntax and smoke validation
+- `workflow-templates/trunk.yml` for Trunk Code Quality
+- `workflow-templates/project-tracker.yml` when repository issues must be
+  enrolled in the organization tracker
+
+Follow `PATTERNS.md`: pin action and reusable-workflow references to immutable
+commit SHAs with readable version or branch comments. Declare top-level
+permissions and concurrency for push and pull-request workflows.
+
+Add release automation only when the release class requires it. Plugins and
+annexes consumed directly from Git usually need validation only.
+
+## Step 5 — Verify before publication
+
+Before opening the bootstrap pull request:
+
+1. Run `git diff --check`.
+2. Parse every workflow YAML file.
+3. Run the repository's syntax and smoke checks.
+4. Confirm action references are immutable SHAs.
+5. Confirm no generic AI orchestration files, secrets, local paths, or generated
+   output were added.
+6. Link the tracker issue and leave an `Agent handoff` comment for deferred
+   template or release work.
+
+## Deferred template assets
+
+Keep this runbook as the source of truth until repeated bootstrap work proves a
+stable scaffold. Create dedicated template repositories only through separate
+tracked issues; do not grow this public meta-repository into a generated source
+tree prematurely.
+
+## See also
+
+- `AGENTS.md`
+- `PATTERNS.md`
+- `runbooks/labels.md`
+- `runbooks/project-tracker.md`
+- `runbooks/release.md`
+- `runbooks/triage.md`