Metadata-Version: 2.5
Name: alku
Version: 0.5.2
Summary: Meta-framework for modern autonomous agentic development
Author-email: Ragnaruk <ima1365@me.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click<9,>=8.1.8
Requires-Dist: markdown-it-py<5,>=3
Requires-Dist: packaging<27,>=24
Requires-Dist: pyyaml<7,>=6
Description-Content-Type: text/markdown

# Alku

Alku is a meta-framework for modern autonomous agentic development.

Right now it supports only Codex and Claude.

## Features

Alku bundles and installs several skills:
1. `alku-workflow` — main entrypoint; responsible for a complete plan-to-implementation workflow for a single feature. Automatically added to AGENTS.md.
2. `alku-auto` — autonomous long-term development; takes all planned features and sequentially launches `alku-workflow` subagents for each one.
3. `alku-brainstorm` — check current project features and create plans for future project growth; launch when you have no idea what to do with the project.
4. `alku-docs` — generate, check, and reconcile documentation with code; should be run periodically (every 3 features as a baseline) to avoid mess and drift in documentation.
5. `alku-architecture` — check high-level project structure; should be run periodically (every 3 features as a baseline) to avoid project structure from becoming a mess.

Alku takes completely ownership on the root `docs` directory and uses it for project documentation.

## Install

To install use these commands:

```console
uv tool install alku
uv tool update-shell
alku --version
```

Restart the shell if `uv tool update-shell` changes `PATH`.

## Quick start

Run Alku from the repository you want it to manage:

```console
cd /path/to/repository
alku init
alku docs check
```

Initialization creates the documentation scaffold, updates the managed
`AGENTS.md` workflow gate, makes `CLAUDE.md` import that shared policy, and
installs the bundled skills and provider-native agent profiles. Restart active
Codex or Claude sessions afterward so they discover the new files.

Preview initialization without writing anything:

```console
alku init --dry-run --json
```

## Routine maintenance

```console
alku docs generate
alku docs check
alku self check
alku self update
```

- `docs generate` refreshes generated indexes and stale Alku-owned projections.
- `docs check` performs read-only validation.
- `self check` reports whether PyPI has a newer release.
- `self update` explicitly installs a newer release and verifies the command.

Run `alku --help` or `alku COMMAND --help` for the complete command surface.

## Development from source

```console
uv sync --locked
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run ty check --extra-search-path src .
uv build
```

Install the current checkout for local testing with:

```console
uv tool install --force .
```
