---
name: templates
description: |
  Template gallery for sharing workflows, team presets, archetypes, domain configs, and complete
  setup bundles across ArcheFlow projects. Supports init-from-template, save-as-template, and
  clone-from-project operations.
  <example>User: "archeflow init writing-short-story"</example>
  <example>User: "archeflow template save my-backend-setup"</example>
  <example>User: "archeflow template list"</example>
  <example>User: "archeflow init --from ../book.giesing-gschichten"</example>
---

# Template Gallery — Shareable ArcheFlow Configurations

Workflows, team presets, custom archetypes, and domain configs should be reusable across projects. This skill defines the template system that makes ArcheFlow setups portable and shareable.

## Template Storage

Templates live in two locations, with project-local overriding global:

| Location | Scope | Precedence |
|----------|-------|------------|
| `.archeflow/templates/` | Project-local | Higher (checked first) |
| `~/.archeflow/templates/` | Global (user-wide) | Lower (fallback) |

### Directory Structure

```
~/.archeflow/templates/
├── workflows/
│   ├── kurzgeschichte.yaml
│   ├── feature-implementation.yaml
│   └── security-review.yaml
├── teams/
│   ├── story-development.yaml
│   ├── backend.yaml
│   └── fullstack.yaml
├── archetypes/
│   ├── story-explorer.md
│   ├── story-sage.md
│   └── db-specialist.md
├── domains/
│   ├── writing.yaml
│   ├── code.yaml
│   └── research.yaml
└── bundles/
    ├── writing-short-story/
    │   ├── manifest.yaml
    │   ├── team.yaml
    │   ├── workflow.yaml
    │   ├── archetypes/
    │   │   ├── story-explorer.md
    │   │   └── story-sage.md
    │   └── domain.yaml
    └── backend-feature/
        ├── manifest.yaml
        ├── team.yaml
        ├── workflow.yaml
        └── domain.yaml
```

Individual templates (workflows/, teams/, archetypes/, domains/) are single files that can be used standalone. Bundles are complete setups that include everything a project needs.

---

## Bundle Manifest

Every bundle has a `manifest.yaml` that declares what it contains, what it requires, and what variables it exposes.

```yaml
name: writing-short-story
description: "Complete setup for short fiction writing with ArcheFlow"
version: 1
domain: writing
includes:
  team: story-development.yaml
  workflow: kurzgeschichte.yaml
  archetypes:
    - story-explorer.md
    - story-sage.md
  domain: writing.yaml
requires:
  - colette.yaml    # Project must have this file
variables:
  target_words: 6000       # Default, can be overridden at init time
  max_cycles: 2            # Default, can be overridden at init time
```

### Manifest Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Bundle identifier (used in `archeflow init <name>`) |
| `description` | Yes | Human-readable description |
| `version` | No | Bundle version (integer, default 1) |
| `domain` | No | Domain this bundle is designed for |
| `includes` | Yes | Map of file types to filenames within the bundle |
| `requires` | No | List of files that must exist in the target project |
| `variables` | No | Key-value pairs with defaults, overridable at init |

### Includes Types

| Key | Target location in `.archeflow/` | Accepts |
|-----|----------------------------------|---------|
| `team` | `teams/<filename>` | Single YAML file |
| `workflow` | `workflows/<filename>` | Single YAML file |
| `archetypes` | `archetypes/<filename>` | List of Markdown files |
| `domain` | `domains/<filename>` | Single YAML file |
| `hooks` | `hooks.yaml` | Single YAML file |

---

## Operations

### `archeflow init <bundle-name>`

Initialize a project's `.archeflow/` directory from a named bundle.

**Procedure:**

1. Search for the bundle:
   - `.archeflow/templates/bundles/<name>/manifest.yaml` (project-local)
   - `~/.archeflow/templates/bundles/<name>/manifest.yaml` (global)
   - If not found: error with list of available bundles
2. Read `manifest.yaml`
3. Check `requires`:
   - For each required file, verify it exists in the project root
   - If missing: error with `"Required file not found: <file>. This bundle requires it."`
4. Check for existing `.archeflow/` setup:
   - If `.archeflow/teams/`, `.archeflow/workflows/`, etc. already contain files: warn and ask before overwriting
   - Never silently overwrite existing configuration
5. Copy files from bundle to `.archeflow/`:
   - `team` → `.archeflow/teams/<filename>`
   - `workflow` → `.archeflow/workflows/<filename>`
   - `archetypes` → `.archeflow/archetypes/<filename>` (each file)
   - `domain` → `.archeflow/domains/<filename>`
   - `hooks` → `.archeflow/hooks.yaml`
6. Create `.archeflow/config.yaml` with variables from manifest:
   ```yaml
   # Generated by archeflow init from bundle: <name>
   bundle: <name>
   bundle_version: <version>
   initialized: <timestamp>
   variables:
     target_words: 6000
     max_cycles: 2
   ```
7. Print setup summary:
   ```
   ArcheFlow initialized from bundle: <name>
     Team:       <team filename> → .archeflow/teams/
     Workflow:   <workflow filename> → .archeflow/workflows/
     Archetypes: <count> files → .archeflow/archetypes/
     Domain:     <domain filename> → .archeflow/domains/
     Config:     .archeflow/config.yaml (variables: target_words=6000, max_cycles=2)
   
   Ready to run: archeflow:run
   ```

### `archeflow init --from <project-path>`

Clone another project's ArcheFlow setup into the current project.

**Procedure:**

1. Verify `<project-path>/.archeflow/` exists
2. Copy these subdirectories (if they exist):
   - `teams/`
   - `workflows/`
   - `archetypes/`
   - `domains/`
   - `config.yaml`
   - `hooks.yaml`
3. Do NOT copy (run-specific data):
   - `events/`
   - `artifacts/`
   - `context/` (generated by colette-bridge, project-specific)
   - `templates/` (project-local templates stay local)
4. Warn if target `.archeflow/` already has files
5. Print summary of what was copied

### `archeflow template save <name>`

Save the current project's `.archeflow/` setup as a reusable template bundle.

**Procedure:**

1. Verify `.archeflow/` exists and has content
2. Create bundle directory: `~/.archeflow/templates/bundles/<name>/`
   - If it already exists: warn and ask before overwriting
3. Copy from `.archeflow/` to bundle:
   - `teams/*.yaml` → bundle `team` (first file, or prompt if multiple)
   - `workflows/*.yaml` → bundle `workflow` (first file, or prompt if multiple)
   - `archetypes/*.md` → bundle `archetypes/`
   - `domains/*.yaml` → bundle `domain` (first file, or prompt if multiple)
   - `hooks.yaml` → bundle (if exists)
4. Generate `manifest.yaml`:
   ```yaml
   name: <name>
   description: "Saved from <project directory name>"
   version: 1
   domain: <from domain yaml if present>
   includes:
     team: <filename>
     workflow: <filename>
     archetypes: [<filenames>]
     domain: <filename>
   requires: []
   variables: <from config.yaml variables section if present>
   ```
5. Print summary:
   ```
   Template saved: <name>
     Location: ~/.archeflow/templates/bundles/<name>/
     Files: <count> files
     Use with: archeflow init <name>
   ```

### `archeflow template list`

List all available templates — both individual files and bundles, from both global and project-local locations.

**Output format:**

```
ArcheFlow Templates
====================

Bundles:
  writing-short-story    Complete setup for short fiction writing     [global]
  backend-feature        Backend feature implementation               [global]
  my-project-setup       Saved from book.giesing-gschichten          [global]

Individual Templates:
  Workflows:
    kurzgeschichte.yaml           [global]
    feature-implementation.yaml   [global]
  Teams:
    story-development.yaml        [global]
    backend.yaml                  [global]
  Archetypes:
    story-explorer.md             [global]
    story-sage.md                 [global]
  Domains:
    writing.yaml                  [global]
    code.yaml                     [global]
```

### `archeflow template share <name> <path>`

Export a template bundle to a directory for sharing (e.g., via git, email, file share).

**Procedure:**

1. Find the bundle (global or local)
2. Copy the entire bundle directory to `<path>/<name>/`
3. Print the path and a one-liner for importing:
   ```
   Exported: <path>/<name>/
   To import: cp -r <path>/<name> ~/.archeflow/templates/bundles/
   ```

---

## Variable Substitution

Bundle manifests can define variables with defaults. These are stored in `.archeflow/config.yaml` after init and can be overridden:

- At init time: `archeflow init writing-short-story --set target_words=8000`
- After init: edit `.archeflow/config.yaml` directly

Variables are available to workflows and the run skill via config:

```yaml
# In a workflow, reference variables:
phases:
  do:
    description: |
      Draft the story. Target: ${target_words} words.
```

Variable substitution happens at run time, not at init time. The workflow file contains the `${variable}` placeholder; the run skill reads `.archeflow/config.yaml` and substitutes before passing to agents.

---

## Individual Template Usage

Not everything needs a bundle. Individual templates can be copied directly:

```bash
# Copy a single workflow
cp ~/.archeflow/templates/workflows/kurzgeschichte.yaml .archeflow/workflows/

# Copy a single archetype
cp ~/.archeflow/templates/archetypes/story-explorer.md .archeflow/archetypes/

# Copy a team preset
cp ~/.archeflow/templates/teams/story-development.yaml .archeflow/teams/
```

The `archeflow init` command handles bundles. For individual files, manual copy or the helper script (`lib/archeflow-init.sh`) can be used.

---

## Integration with Other Skills

- **`archeflow:run`** — Reads `.archeflow/config.yaml` for variables, applies them during run initialization
- **`archeflow:domains`** — Domain YAML from templates is loaded like any other domain config
- **`archeflow:custom-archetypes`** — Archetype .md files from templates work identically to hand-written ones
- **`archeflow:workflow-design`** — Workflow YAML from templates follows the same schema
- **`archeflow:colette-bridge`** — Bundle `requires: [colette.yaml]` ensures the bridge has what it needs

---

## Design Principles

1. **Bundles are self-contained.** Everything needed to set up a project is in the bundle directory. No external dependencies beyond `requires`.
2. **Never silently overwrite.** Init warns before replacing existing files. Templates are helpers, not bulldozers.
3. **Global + local layering.** Project-local templates override global ones. This allows per-project customization without polluting the global registry.
4. **Skip run data.** Events, artifacts, and context are run-specific. Templates carry only configuration.
5. **Variables are late-bound.** Substitution happens at run time, not template time. This keeps templates generic.
6. **Plain files, no magic.** Templates are just directories of YAML and Markdown files. No databases, no registries, no lock files.