ariadne-skill 0.1.0

Skill-first local delegation workflow for Codex and Claude Code.

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: pip install aider-chat
• A DeepSeek API key — most tasks cost under $0.01

Supported platforms: Linux and macOS.

Setup

1. Install Ariadne

pip install ariadne-skill

2. Install Aider

pip install aider-chat

3. Get a DeepSeek API key

Sign up at 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:

export DEEPSEEK_API_KEY="sk-..."

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

4. Install the skill into your agent

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 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:

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.