extensibility enhancements (template and rule packs)

.kiro/specs/custom-template-packs/.config.kiro

@@ -0,0 +1 @@
+{"specId": "5b110807-2f47-49e3-9fed-9967cc499c4b", "workflowType": "requirements-first", "specType": "feature"}

README.md

@@ -20,6 +20,9 @@ Steergen is a .NET CLI tool that maintains a single set of steering and constitu
 - [Supported Targets](#supported-targets)
 - [Command Reference](#command-reference)
 - [Configuration](#configuration)
+- [Template Packs](#template-packs)
+- [Rules Packs](#rules-packs)
+- [Authoring a Rules Pack](docs/authoring-rules-packs.md)
 - [Exit Codes](#exit-codes)
 - [Contributing](#contributing)
 - [Troubleshooting](#troubleshooting)
@@ -118,18 +121,22 @@ steergen target remove kiro
 |---|---|
 | `steergen init [root] [--target <id>...]` | Bootstrap config and target folders |
 | `steergen run [options]` | Generate output files for all registered targets |
-| `steergen validate [options]` | Validate source documents; exits non-zero on errors |
-| `steergen inspect [options]` | Print the resolved steering model as JSON |
-| `steergen target add <id>` | Register a new target |
+| `steergen validate [options]` | Validate source documents and template packs |
+| `steergen inspect [--templates] [--rules]` | Print resolved model, template chain, or rules pack info |
+| `steergen target add <id>` | Register a new target (built-in or pack-provided) |
 | `steergen target remove <id>` | Unregister a target |
 | `steergen purge [options]` | Remove generated files managed by steergen |
-| `steergen update [--version <v>] [--preview]` | Update `templatePackVersion` in the config file |
+| `steergen update [--templates] [--rules] [--force]` | Re-download configured packs |
+| `steergen template-pack add <source> [--ref <ref>] [--path <localPath>]` | Add a template pack |
+| `steergen template-pack remove` | Remove the configured template pack |
+| `steergen rules-pack add <source> [--ref <ref>] [--path <subdir>] [--scope <scope>]` | Add a rules pack |
+| `steergen rules-pack remove <name>` | Remove a rules pack by name |
+| `steergen rules-pack list` | List configured rules packs with status |
 
 **Commonly used `run` options:**
 
 ```
 --config <path>     Path to steergen.config.yaml
---global <dir>      Override globalRoot
 --project <dir>     Override projectRoot
 --output <dir>      Override generationRoot
 --target <id>       Generate for one target only (repeatable)
@@ -146,29 +153,219 @@ Steergen looks for `steergen.config.yaml` in the current directory (or the path
 A minimal config file:
 
 ```yaml
-globalRoot: steering/global
 projectRoot: steering/project
 generationRoot: .
 registeredTargets:
   - kiro
   - copilot-agent
 ```
 
+A config with template pack and rules packs:
+
+```yaml
+projectRoot: steering/project
+generationRoot: .
+
+templatePack:
+  source: "github:acme-corp/steergen-templates"
+  ref: "v2.1.0"
+
+rulesPacks:
+  - source: "github:acme-corp/baseline-rules"
+    ref: "abc123def456789012345678901234567890abcd"
+    scope: global
+  - source: "github:acme-corp/team-rules"
+    ref: "v1.0.0"
+    path: "backend-team"
+
+registeredTargets:
+  - kiro
+  - copilot-agent
+```
+
 Key fields:
 
 | Field | Purpose |
 |---|---|
-| `globalRoot` | Source folder for organisation-wide steering docs |
 | `projectRoot` | Source folder for project-specific steering docs |
 | `generationRoot` | Base folder for all generated output |
 | `registeredTargets` | List of targets to generate by default |
+| `templatePack` | Template pack source configuration (see [Template Packs](#template-packs)) |
+| `rulesPacks` | List of rules pack entries (see [Rules Packs](#rules-packs)) |
 | `activeProfiles` | Profile names (legacy; retained for backward compatibility) |
-| `templatePackVersion` | Template pack version (managed by `steergen update`) |
+
+> **Note:** The `globalRoot` field has been removed. If your config still contains `globalRoot`, Steergen will report error CFG001 and exit with code 2. See the [migration guide](docs/migration-globalroot.md) for how to convert existing global rules to a rules pack.
 
 For full configuration options and advanced routing, see [Section 5](docs/getting-started.md#5-controlling-where-generated-files-end-up-roots) and [Section 6](docs/getting-started.md#6-controlling-which-rules-go-where-routing) of the Getting Started guide.
 
 ---
 
+## Template Packs
+
+Template packs let you override the built-in Scriban templates that Steergen uses to render output, or provide complete target definitions for new external targets. Packs can be sourced from a local directory or a public GitHub repository.
+
+### Adding a template pack from GitHub
+
+```bash
+steergen template-pack add github:acme-corp/steergen-templates --ref v2.1.0
+```
+
+This writes the source to `steergen.config.yaml` and downloads the pack to the local cache at `~/.steergen/packs/acme-corp/steergen-templates/v2.1.0/`.
+
+### Adding a local template override path
+
+```bash
+steergen template-pack add --path ./custom-templates
+```
+
+Local overrides take the highest precedence in the resolution chain.
+
+### Template resolution precedence
+
+When rendering, Steergen resolves templates in this order:
+
+1. **Local override path** (`templatePack.localPath`) — highest precedence
+2. **Cached GitHub pack** (`templatePack.source`) — middle precedence
+3. **Built-in embedded templates** — fallback
+
+### Updating a template pack
+
+Re-download the configured GitHub pack to pick up changes:
+
+```bash
+steergen update --templates
+```
+
+On success, displays the pack name, version, and number of template files. If the pack is pinned to a 40-character SHA, re-download is skipped unless `--force` is specified:
+
+```bash
+steergen update --templates --force
+```
+
+If no template pack is configured, the command exits with code 0 and reports that no pack source is configured.
+
+### Inspecting the template chain
+
+See which templates come from which source:
+
+```bash
+steergen inspect --templates
+```
+
+Displays the active resolution chain showing the source (local override, cached GitHub pack, or built-in) for each template.
+
+### Removing a template pack
+
+```bash
+steergen template-pack remove
+```
+
+Removes the template pack configuration from `steergen.config.yaml`.
+
+### Configuration reference
+
+```yaml
+templatePack:
+  source: "github:acme-corp/steergen-templates"  # GitHub source
+  ref: "v2.1.0"                                   # Tag, branch, or 40-char SHA
+  # OR use a local path instead:
+  # localPath: "./custom-templates"
+```
+
+---
+
+## Rules Packs
+
+Rules packs are shared governance rule sets published to GitHub repositories. They let teams share steering documents across projects without copying files. Each pack declares a scope that determines its merge precedence relative to project-local rules.
+
+> To create and publish your own rules pack, see the **[Authoring a Rules Pack](docs/authoring-rules-packs.md)** guide.
+
+### Adding a rules pack
+
+```bash
+steergen rules-pack add github:acme-corp/baseline-rules --ref v1.0.0 --scope global
+```
+
+Options:
+
+| Option | Purpose |
+|---|---|
+| `--ref <ref>` | Git tag, branch, or 40-character SHA |
+| `--path <subdir>` | Subdirectory within the repo (for multi-pack repos) |
+| `--scope <scope>` | Override the pack's manifest scope (`global`, `supplemental`, or `project`) |
+
+The command appends the pack to the `rulesPacks` list in `steergen.config.yaml` and downloads it to `~/.steergen/rules/{owner}/{repo}/{ref}/`.
+
+### Scope-based merge precedence
+
+When multiple rule sources define the same rule ID, Steergen resolves conflicts using scope-based precedence:
+
+1. **Project-local rules** — highest precedence (your `projectRoot` documents)
+2. **Project-scoped packs** — rules packs with `scope: project`
+3. **Supplemental-scoped packs** — rules packs with `scope: supplemental`
+4. **Global-scoped packs** — rules packs with `scope: global` (lowest precedence)
+
+Within the same scope level, packs declared earlier in the `rulesPacks` list take precedence. Duplicate rule IDs at the same scope emit a diagnostic warning.
+
+The `--scope` option on `rules-pack add` overrides the scope declared in the pack's own manifest, letting consumers elevate or demote a pack's precedence.
+
+### Listing configured rules packs
+
+```bash
+steergen rules-pack list
+```
+
+Displays all configured rules packs with their source, ref, scope, and cache status.
+
+### Updating rules packs
+
+Re-download all configured rules packs:
+
+```bash
+steergen update --rules
+```
+
+SHA-pinned packs are skipped unless `--force` is specified:
+
+```bash
+steergen update --rules --force
+```
+
+### Inspecting rules packs
+
+```bash
+steergen inspect --rules
+```
+
+Displays all configured rules packs with their name, version, source, scope, and number of rules loaded.
+
+### Removing a rules pack
+
+```bash
+steergen rules-pack remove acme-baseline-rules
+```
+
+Removes the matching entry from the `rulesPacks` list in `steergen.config.yaml`.
+
+### Configuration reference
+
+```yaml
+rulesPacks:
+  - source: "github:acme-corp/baseline-rules"
+    ref: "abc123def456789012345678901234567890abcd"  # Pinned SHA (recommended)
+    scope: global
+  - source: "github:acme-corp/team-rules"
+    ref: "v1.0.0"
+    path: "backend-team"                             # Subdirectory within repo
+  - source: "github:acme-corp/security-rules"
+    ref: "main"                                      # Branch (pinning recommended)
+    scope: supplemental
+```
+
+> **Tip:** Pin rules packs to a tag or full SHA for deterministic builds. Branch refs work but Steergen will recommend pinning in diagnostic output.
+
+---
+
 ## Exit Codes
 
 | Code | Meaning |
@@ -207,7 +404,7 @@ Ensure `~/.dotnet/tools` (Linux/macOS) or `%USERPROFILE%\.dotnet\tools` (Windows
 Run `steergen validate` first — generation is skipped when source documents contain errors.
 
 **Generated files differ between machines**
-Check that `globalRoot` and `projectRoot` point to the same content on each machine. Use `steergen inspect` to compare the resolved model.
+Check that `projectRoot` points to the same content on each machine and that rules packs are pinned to the same ref. Use `steergen inspect` to compare the resolved model.
 
 **Something else?**
 Open an issue at <https://github.com/aabs/steergen/issues>.