pi-allium-port/README.md

# Allium for Pi.dev

Port of [Allium](https://github.com/juxt/allium) (v3) to [pi.dev](https://pi.dev) skills.

This README was written by a coding agent. The [draft blogpost](/pi-allium-port/src/branch/main/blog-post-draft.md) has a pre-amble with some motivation written by me.

Allium is a formal language for capturing software behaviour at the domain level. It sits between informal feature descriptions and implementation, providing a precise way to specify what software does without prescribing how it's built.

## What this is

This repository ports Allium's AI skills from the Claude Code plugin format to pi.dev skills, while keeping upstream content referenced by symlink rather than copied. The goal: stay in sync with upstream Allium without maintaining a full fork.

## Skills

| Skill | Invocation | Purpose |
|-------|------------|---------|
| **allium** | `/skill:allium` | Root skill — routing table and language reference |
| **elicit** | `/skill:elicit` | Elicit requirements and design decisions from stakeholders |
| **distill** | `/skill:distill` | Extract a `.allium` spec from existing code |
| **propagate** | `/skill:propagate` | Generate test obligations from a `.allium` spec |
| **tend** | `/skill:tend` | Maintain and evolve `.allium` specs (ported from Claude agent) |
| **weed** | `/skill:weed` | Check spec-code alignment (ported from Claude agent) |

## Directory layout

```
pi-allium-port/
├── allium-main/            ← git clone of juxt/allium (upstream)
├── .pi/
│   └── skills/
│       ├── allium/
│       │   ├── SKILL.md    ← adapted frontmatter + upstream content
│       │   └── references/ → ../../../allium-main/references/
│       ├── elicit/
│       │   ├── SKILL.md
│       │   └── references/ → symlinks to allium-main/
│       ├── distill/
│       │   ├── SKILL.md
│       │   └── references/ → symlinks to allium-main/
│       ├── propagate/
│       │   ├── SKILL.md
│       │   └── references/ → symlinks to allium-main/
│       ├── tend/
│       │   ├── SKILL.md
│       │   └── references/ → symlinks to allium-main/
│       └── weed/
│           ├── SKILL.md
│           └── references/ → symlinks to allium-main/
├── turn-limit/             ← test target (pi-turn-limit extension)
└── README.md               ← this file
```

## Symlink strategy

Each skill's `references/` directory contains symlinks pointing into `allium-main/`. This means:

- **Upstream updates propagate automatically** — when `allium-main` is updated (e.g., `git pull`), all referenced content is current.
- **No content duplication** — the port maintains only the SKILL.md frontmatter adapters, not copies of reference documents.
- **Relative paths** — symlinks use relative paths so the structure is portable (as long as `allium-main/` stays in the same relative position).

### Staying in sync

```bash
cd allium-main
git pull origin main
```

That's it. The symlinks ensure all skills see the updated content immediately.

## Prerequisites

- [pi.dev](https://pi.dev) installed and configured
- [Allium CLI](https://juxt.github.io/allium/installation) installed (for `allium check` validation)
- Clone this repository with `allium-main/` present

## Usage

1. Open pi in this directory: `pi -p`
2. Invoke skills with `/skill:allium`, `/skill:elicit`, `/skill:distill`, `/skill:propagate`, `/skill:tend`, `/skill:weed`
3. Skills guide the model through Allium workflows

## Known limitations vs Claude Code version

| Feature | Claude Code | Pi.dev port | Notes |
|---------|-------------|-------------|-------|
| **Model selection** | Agents run on specific models (e.g., Opus for tend/weed) | Runs on default model | Pi has no native agent model selection |
| **Tool restrictions** | Agents have scoped tool permissions | No tool scoping | Skills can use any tool the model has |
| **Auto-trigger** | `auto_trigger` activates skills on file patterns/keywords | Manual invocation only | Pi uses `disable-model-invocation` instead |
| **Post-write hooks** | `allium-check.mjs` runs automatically after Edit/Write | Manual `allium check` instruction in skills | Skills instruct the model to run validation, but it's not automatic |
| **Rules** | `.claude/rules/` with glob-based activation | Content folded into SKILL.md or references | No glob-based rule activation in pi |
| **Syntax rules** | Dedicated rules file with anti-patterns | Symlinked into `references/allium-rules.md` | Same content, different delivery mechanism |

## Tested against

The [pi-turn-limit](https://gitea.apps.sustainabledelivery.com/QWAN/monotonic-pi-extensions) extension served as the test target:

- **Distill**: Extracted `.allium` spec from existing code
- **Propagate**: Generated 30+ test obligations from the spec
- **Elicit**: Explored "disable turn limit" feature requirements
- **TDD cycle**: Red → Green using propagate-generated tests

## License

Allium is licensed under the [MIT License](https://opensource.org/licenses/MIT), copyright (c) 2026 JUXT Ltd.

This port adapts the Allium skills for pi.dev. The upstream Allium content (reference documents, skill methodologies) remains the intellectual property of JUXT Ltd under the MIT License. The port adapter files (SKILL.md frontmatter) are also released under MIT.

See [LICENSE](./LICENSE) for full terms.

## Attribution

- **Allium**: [juxt/allium](https://github.com/juxt/allium) by JUXT Ltd
- **Allium documentation**: [juxt.github.io/allium](https://juxt.github.io/allium/)
- **Pi.dev**: [pi.dev](https://pi.dev)

## Contributing

If you find issues with the port or have improvements, please open an issue or pull request. For Allium language questions, refer to the [upstream repository](https://github.com/juxt/allium).