angreal-templates

What this skill does

# Creating Angreal Templates

Create reusable project templates that others can consume via `angreal init <template>`.

## What Templates Are For

Templates let you create reusable project scaffolds. Users initialize new projects with:

```bash
angreal init https://github.com/user/my-template
angreal init /path/to/local/template
```

This is different from `angreal-init` (adding angreal to existing projects) - templates create entirely new projects from scratch.

## Official Templates

The angreal team maintains a set of ready-to-use templates in the
[github.com/angreal](https://github.com/angreal) organization. A **bare name**
passed to `angreal init` resolves to `https://github.com/angreal/<name>`, so
these can be used directly:

```bash
angreal init python      # Python project template
angreal init rust        # Rust project template
```

| Template | `angreal init` | What it scaffolds |
|----------|----------------|-------------------|
| `python` | `angreal init python` | Standard Python project |
| `python-gh` | `angreal init python-gh` | Python project wired for GitHub (Actions CI) |
| `python-gl` | `angreal init python-gl` | Python project wired for GitLab (GitLab CI) |
| `rust` | `angreal init rust` | Rust project: workspace layout, unified versioning, CI/CD, optional Tauri v2 desktop UI |
| `data-science` | `angreal init data-science` | Modern data-science project with epoch-based notebook organization and scientific computing patterns |
| `airflow` | `angreal init airflow` | Apache Airflow project scaffold |
| `airflow-provider` | `angreal init airflow-provider` | Apache Airflow provider package |

This list changes over time — browse [github.com/angreal](https://github.com/angreal)
for the current, authoritative catalog (any non-fork repo containing an
`angreal.toml` is a consumable template).

Resolution order for `angreal init <name>`:
1. A local path, if it exists
2. A cached template in `~/.angrealrc/`, if present
3. The GitHub repo `https://github.com/angreal/<name>`

## Rendering In Place

By default a template's single top-level templated directory (e.g.
`{{ project_name }}/`) becomes a **new** project root inside the current
directory. The `--in-place` / `-i` flag strips that top-level directory and
renders its contents **directly into the current working directory** — useful
for scaffolding into a folder you've already created (such as an existing git
repository or a directory of planning notes):

```bash
mkdir my-project && cd my-project
angreal init python --in-place        # contents land in ./, no extra root dir
```

In-place rendering requires the template to have **exactly one** top-level
templated directory (it errors clearly on zero or multiple). Collisions with
existing files reuse `--force` semantics: the command aborts unless `--force`
is passed.

### `angreal init` flags

| Flag | Short | Effect |
|------|-------|--------|
| `--force` | `-f` | Render even if target paths/files already exist (overwrite) |
| `--defaults` | `-d` | Use default values from `angreal.toml` without prompting |
| `--in-place` | `-i` | Strip the template's top-level directory; render into the current directory |
| `--values <FILE>` | | Supply values from a file, bypassing interactive prompts |

## Template Structure

Every angreal template follows this structure:

```
my-template/
├── angreal.toml              # Template configuration (required)
├── {{ project_name }}/       # Templated directories
│   ├── src/
│   └── tests/
├── README.md                 # Templated files
├── static_file.txt           # Static files (copied as-is)
└── .angreal/                 # Optional: post-init tasks
    ├── init.py               # Post-initialization script
    └── task_*.py             # Template-specific tasks
```

## Template Configuration (angreal.toml)

The `angreal.toml` file defines template variables at the root level:

```toml
# Variables with defaults - users will be prompted for these
project_name = "my-project"
author_name = "Anonymous"
description = "A new project"
license = "MIT"
use_docker = false
python_version = "3.11"

# Optional: Custom prompts for better UX
[prompt]
project_name = "Enter your project name"
author_name = "Enter your name"
license = "Choose a license (MIT, Apache-2.0, GPL-3.0)"

# Optional: Validation rules
[validation]
project_name.not_empty = true
project_name.length_min = 3
license.allowed_values = ["MIT", "Apache-2.0", "GPL-3.0"]
```

### Variable Types

```toml
# String variables
project_name = "default-name"
author = "Your Name"

# Boolean variables
use_docker = false
include_tests = true

# Numeric variables
port = 8080

# List variables
dependencies = ["requests", "click", "pydantic"]
```

### Custom Prompts ([prompt] section)

Customize what users see when providing values:

```toml
[prompt]
project_name = "Enter your project name (lowercase, no spaces)"
author_email = "Your email address"
use_docker = "Include Docker support? (y/n)"
```

### Validation Rules ([validation] section)

Validate user input with these options:

```toml
[validation]
# Required field
project_name.not_empty = true

# String length
username.length_min = 3
username.length_max = 20

# Numeric range
port.type = "integer"
port.min = 1024
port.max = 65535

# Allowed values
license.allowed_values = ["MIT", "Apache-2.0", "GPL-3.0"]

# Regex pattern
email.regex_match = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
```

## Tera Templating Engine

Angreal uses [Tera](https://keats.github.io/tera/docs/) (similar to Jinja2) for templating.

### Variable Substitution

```markdown
# {{ project_name }}

{{ description }}

Created by {{ author_name }}
```

### Conditionals

```markdown
# {{ project_name }}

{% if use_docker %}
## Docker

Build and run with Docker:

```bash
docker build -t {{ project_name }} .
docker run {{ project_name }}
```
{% endif %}

{% if include_tests %}
## Testing

```bash
pytest tests/
```
{% endif %}
```

### Loops

```python
# requirements.txt
{% for dep in dependencies %}
{{ dep }}
{% endfor %}
```

### Filters

```markdown
# {{ project_name | title }}

Package: {{ project_name | lower | replace(from=" ", to="-") }}
Class: {{ project_name | title | replace(from=" ", to="") }}
```

Common filters:
- `upper` / `lower` - Change case
- `title` - Title case
- `replace(from="x", to="y")` - Replace text
- `trim` - Remove whitespace

## Templated Names

### Directory Names

```
my-template/
└── {{ project_name }}/
    ├── {{ project_name }}/
    │   └── __init__.py
    └── tests/
```

With `project_name = "my-app"` creates:
```
my-app/
├── my-app/
│   └── __init__.py
└── tests/
```

### File Names

```
{{ project_name }}.py
test_{{ project_name }}.py
```

## Escaping Template Syntax

Use `{% raw %}` to preserve template syntax in output files:

```
{% raw %}
{
  "name": "{{ package_name }}",
  "scripts": {
    "test": "jest"
  }
}
{% endraw %}
```

This outputs the literal `{{ package_name }}` without substitution. Use for:
- JSON files with curly braces
- Jinja/Tera templates you want to include in generated projects
- Documentation showing template examples

## Conditional File/Directory Creation

Control which files and directories are created based on template variables.

### Conditional File Content (Empty = No File)

Create files that are empty (and thus effectively skipped) when conditions aren't met:

```
{# Dockerfile - only has content if use_docker is true #}
{% if use_docker %}
FROM python:{{ python_version }}
WORKDIR /app
COPY . .
RUN pip install -e .
CMD ["python", "-m", "{{ project_name }}"]
{% endif %}
```

### Conditional Directories via Post-Init Script

Use `.angreal/init.py` to create or remove directories based on variables:

```python
# .angreal/init.py
import shutil
import os
import angreal

def init():
    context = angreal.get_context()
    project = context.get('project_name', 'project')

    # Conditionally create directories
    if context.get('include_docs', False):
        os.makedirs(f"{projec