Metadata-Version: 2.4
Name: ariadne-skill
Version: 0.1.3
Summary: Skill-first local delegation workflow for Codex and Claude Code.
Author: Albert ZHANG
License: Apache-2.0
Project-URL: Homepage, https://github.com/albertc9/Ariadne
Project-URL: Repository, https://github.com/albertc9/Ariadne
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: questionary>=2.0
Dynamic: license-file

# Ariadne

Your AI coding agent delegates mechanical tasks to a cheap local worker — Aider + DeepSeek — on a separate branch. The agent reviews the patch before anything merges. You never touch the CLI.

## How it works

1. Tell the agent once: *"use Ariadne for this session"*
2. The agent runs preflight, creates a worker branch, invokes Aider, and shows you the patch
3. You decide whether to merge

The agent reads the skill file and handles everything. No CLI knowledge required.

## Requirements

- Python 3.10+
- git
- [Aider](https://aider.chat/): `pip install aider-chat`
- A [DeepSeek API key](https://platform.deepseek.com/) — most tasks cost under $0.01

**Supported platforms:** Linux and macOS.

## Setup

**1. Install Ariadne**

```bash
pip install ariadne-skill
```

**2. Install Aider**

```bash
pip install aider-chat
```

**3. Get a DeepSeek API key**

Sign up at [platform.deepseek.com](https://platform.deepseek.com/) and create an API key. Top up a small amount — most tasks cost under $0.01.

Export the key in your shell:

```bash
export DEEPSEEK_API_KEY="sk-..."
```

Add that line to `~/.zshrc` or `~/.bashrc` to persist across sessions.

**4. Install the skill into your agent**

```bash
ariadne install-skill
```

Detects which agents you have installed (Claude Code, Codex) and asks where to install — globally for all projects, or locally for the current repo. Follow the prompts.

Trigger with `/ariadne` in Claude Code, or say *"use Ariadne"*.

That's it.

## Quick test

At the start of a conversation, tell the agent once:

> "Use Ariadne for delegation tasks in this session."

Then just describe your work:

> "Write unit tests for `src/foo.py`."

The agent recognises suitable tasks and triggers Ariadne automatically. You can also trigger explicitly at any time with `/ariadne`.

## What Ariadne handles well

These patterns cover the majority of mechanical coding work in a typical project. If a task has a clear scope and a defined target file, Ariadne is the right tool.

**Testing**
- Write unit tests for an existing module
- Add parametrised or property-based test cases
- Generate test fixtures and mock factories

**Documentation and types**
- Add or improve docstrings
- Add type annotations to an existing module
- Translate inline comments to English

**Refactoring**
- Rename symbols consistently within a file
- Extract constants from magic numbers or repeated strings
- Convert imperative loops to comprehensions or functional style
- Add input validation or error handling to existing functions

**Implementation**
- Fill in a stub or scaffold that is already defined
- Implement a small interface or abstract base class
- Add logging to an existing module
- Convert synchronous functions to async (or vice versa)

**Not suited for:** architectural decisions, bug diagnosis requiring cross-system tracing, changes spanning many unrelated files, or tasks requiring external context the worker has not been given.

## Works especially well with TDD

TDD's red-green-refactor loop maps directly onto Ariadne's delegation model. Each slice is bounded, has a clear success criterion, and touches one file at a time — exactly the conditions under which the worker performs best.

A typical TDD loop with Ariadne:

1. **Red** — delegate test writing: `--editable tests/test_foo.py --readonly src/foo.py`
2. **Green** — delegate the implementation: `--editable src/foo.py --readonly tests/test_foo.py`
3. **Refactor** — delegate cleanup under the now-passing tests

The worker never makes architectural decisions. The test suite keeps it honest. Each patch is small enough to review in seconds. That's the loop.

If you are not already using TDD with your agent, the **[/tdd skill](https://github.com/mattpocock/skills)** from Matt Pocock's skills collection is a practical starting point. It codifies a red-green-refactor loop and works well alongside Ariadne.

## Environment variables

Only needed if you want to change default behaviour:

| Variable | Default | When to change |
|---|---|---|
| `ARIADNE_AIDER_MODEL` | `deepseek/deepseek-chat` | If DeepSeek renames the model |
| `ARIADNE_AIDER_IDLE_TIMEOUT` | `90` | Slow API responses |
| `ARIADNE_AIDER_MAX_RUNTIME` | `600` | Very large tasks |
| `ARIADNE_CHECK_TIMEOUT` | `120` | Slow test suites used as a quality gate |

## Security

Ariadne never writes your API key to any file. `DEEPSEEK_API_KEY` must come from your shell environment only.

Run artifacts (patches, logs, metadata) are written to `.ariadne/` inside the target repository. That directory is git-ignored and never committed. What you build stays local.

## Development

Run the test suite — no API key or Aider required:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```

Architecture decisions live in `docs/adr/`. Skill files live in `.claude/skills/ariadne/` and `.codex/skills/ariadne/`.

## License

Apache-2.0. See `LICENSE`.
