angreal-authoring

# Authoring Angreal Tasks

Create task files within an existing angreal project. For initializing new projects, see the angreal-init skill.

## Task File Location

Task files live in `.angreal/` at your project root:

```
my-project/
├── .angreal/
│   ├── task_dev.py       # Development tasks
│   ├── task_test.py      # Testing tasks
│   ├── task_docs.py      # Documentation tasks
│   └── utils.py          # Shared utilities (optional)
├── src/
└── ...
```

**Naming convention**: Files must be named `task_*.py` to be discovered.

## The @command Decorator

Every task needs the `@command` decorator:

```python
import angreal

@angreal.command(
    name="build",              # Command name (kebab-case)
    about="Build the project"  # Short description for --help
)
def build():
    print("Building...")
    return 0  # Success
```

### Name Inference

If you omit `name`, it derives from the function:

```python
@angreal.command(about="Check dependencies")
def check_deps():  # Creates command "check-deps"
    pass
```

## Command Groups

Organize related commands with groups:

```python
import angreal

# Create reusable group decorator
test = angreal.command_group(name="test", about="Testing commands")

@test()  # Group decorator FIRST
@angreal.command(name="all", about="Run all tests")
def test_all():
    pass

@test()
@angreal.command(name="unit", about="Run unit tests")
def test_unit():
    pass
```

Creates: `angreal test all`, `angreal test unit`

### Nested Groups

```python
docker = angreal.command_group(name="docker", about="Docker commands")
compose = angreal.command_group(name="compose", about="Compose commands")

@docker()
@compose()
@angreal.command(name="up", about="Start services")
def docker_compose_up():
    pass
```

Creates: `angreal docker compose up`

## Getting Project Root

**Important**: `get_root()` returns `.angreal/` directory, not project root:

```python
import angreal

@angreal.command(name="build", about="Build project")
def build():
    an