angreal-init

name	angreal-init
description	This skill should be used when the user asks to "create an angreal project", "initialize angreal", "set up angreal", "add angreal to project", "start new angreal project", "create .angreal directory", "scaffold into existing project", "angreal init --in-place", "add angreal to existing repo", or needs guidance on setting up angreal in a new or existing project (hand-rolled `.angreal/` or via an official template), or the initial task file structure.
version	2.8.7

Initializing Angreal Projects

Set up angreal task automation in a new or existing project.

What is an Angreal Project?

An angreal project is any directory containing a .angreal/ subdirectory with task files. Angreal provides development task automation - think of it as your project's make or npm run.

Quick Setup

Option A: Scaffold from an official template (recommended)

For a fresh project or to add angreal to a directory you've already created, use one of the official templates:

# Fresh project (creates a new subdirectory)
angreal init python

# Add angreal into an existing project root (no extra subdir)
cd my-existing-project
angreal init python --in-place

--in-place / -i strips the template's top-level templated directory and renders directly into the current working directory — this is the canonical path for "add angreal to my existing repo." Add --force if existing files would be overwritten, --defaults to skip prompts, or --values <file> to supply variables non-interactively. See the angreal-templates skill for the full template catalog (python, python-gh, python-gl, rust, data-science, airflow, …).

Option B: Hand-roll the .angreal directory

If no template matches or you want full control:

mkdir .angreal

2. Create Your First Task File

# .angreal/task_dev.py
import angreal

@angreal.command(name="hello", about="Test angreal setup")
def hello():
    print("Angreal is working!")
    return 0

3. Verify Setup

angreal tree    # Should show: hello - Test angreal setup
angreal hello   # Should print: Angreal is working!

Recommended Project Structure

Minimal Setup

my-project/
├── .angreal/
│   └── task_dev.py      # Start with one task file
├── src/
└── ...

Standard Setup

my-project/
├── .angreal/
│   ├── task_dev.py      # Development utilities
│   ├── task_test.py     # Testing commands
│   ├── task_build.py    # Build commands
│   └── task_docs.py     # Documentation commands
├── src/
└── ...

With Shared Utilities

my-project/
├── .angreal/
│   ├── utils.py         # Shared helper functions
│   ├── task_dev.py
│   ├── task_test.py
│   └── task_build.py
├── src/
└── ...

Starter Templates

Development Utilities

# .angreal/task_dev.py
import angreal
import subprocess
import os

@angreal.command(name="check-deps", about="Verify development tools")
def check_deps():
    """Check that required tools are installed."""
    tools = ["python", "git"]
    missing = []

    for tool in tools:
        result = subprocess.run(
            ["which", tool],
            capture_output=True
        )
        if result.returncode != 0:
            missing.append(tool)

    if missing:
        print(f"Missing tools: {', '.join(missing)}")
        return 1

    print("All tools available!")
    return 0

@angreal.command(name="setup", about="Set up development environment")
def setup():
    """Initialize development environment."""
    project_root = angreal.get_root().parent

    # Example: Create virtual environment
    venv_path = project_root / ".venv"
    if not venv_path.exists():
        print("Creating virtual environment...")
        subprocess.run(["python", "-m", "venv", str(venv_path)])

    print("Development environment ready!")
    return 0

Testing Commands

# .angreal/task_test.py
import angreal
import subprocess

test = angreal.command_group(name="test", about="Testing commands")

@test()
@angreal.command(name="all", about="Run all tests")
def test_all():
    project_root = angreal.get_root().parent
    result = subprocess.run(
        ["pytest", "-v"],
        cwd=project_root
    )
    return result.returncode

@test()
@angreal.command(name="unit", about="Run unit tests only")
def test_unit():
    project_root = angreal.get_root().parent
    result = subprocess.run(
        ["pytest", "tests/unit", "-v"],
        cwd=project_root
    )
    return result.returncode

Build Commands

# .angreal/task_build.py
import angreal
import subprocess

@angreal.command(
    name="build",
    about="Build the project",
    tool=angreal.ToolDescription("""
        Build project artifacts.

        ## When to use
        - Before releasing
        - Testing production builds

        ## Examples
        ```
        angreal build
        angreal build --release
        ```
        """, risk_level="safe")
)
@angreal.argument(
    name="release",
    long="release",
    is_flag=True,
    takes_value=False,
    help="Build in release mode"
)
def build(release=False):
    project_root = angreal.get_root().parent
    cmd = ["python", "-m", "build"]

    print(f"Building {'release' if release else 'debug'}...")
    result = subprocess.run(cmd, cwd=project_root)
    return result.returncode

Shared Utilities Module

# .angreal/utils.py
import angreal
import subprocess
from pathlib import Path

def get_project_root() -> Path:
    """Return the project root directory."""
    return angreal.get_root().parent

def run_command(cmd, check=True, capture=False):
    """Run a command in the project root."""
    result = subprocess.run(
        cmd,
        cwd=get_project_root(),
        capture_output=capture,
        text=True
    )
    if check and result.returncode != 0:
        raise subprocess.CalledProcessError(
            result.returncode, cmd
        )
    return result

def file_exists(relative_path: str) -> bool:
    """Check if a file exists relative to project root."""
    return (get_project_root() / relative_path).exists()

Adding Angreal to Existing Projects

1. Create .angreal/ directory at project root
2. Add task files for existing workflows
3. Migrate shell scripts or Makefile targets to angreal tasks
4. Add .angreal/ to version control

Migrating from Makefile

Before (Makefile):

test:
    pytest tests/

build:
    python -m build

After (.angreal/task_build.py):

import angreal
import subprocess

@angreal.command(name="test", about="Run tests")
def test():
    return subprocess.run(["pytest", "tests/"]).returncode

@angreal.command(name="build", about="Build package")
def build():
    return subprocess.run(["python", "-m", "build"]).returncode

Best Practices

File Naming

• Use task_<domain>.py pattern
• One domain per file: task_test.py, task_build.py
• Shared code in utils.py or helpers.py

Initial Tasks to Create

1. check-deps - Verify development tools are installed
2. setup - Initialize development environment
3. test - Run the test suite
4. build - Build artifacts

Version Control

Add to .gitignore:

# Don't ignore .angreal/ - it should be versioned
# But ignore any generated files within it
.angreal/__pycache__/
.angreal/*.pyc

Verification Checklist

After setup, verify:

• angreal tree shows your commands
• angreal <command> executes correctly
• Tasks find project files using angreal.get_root().parent
• Task files are in version control