Metadata-Version: 2.5
Name: alku
Version: 0.5.3
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 prepares a repository for repeatable, documentation-led development by
autonomous coding agents. It installs project-local workflows for Codex and
Claude, maintains a structured documentation tree, and validates the state
those workflows rely on.

Right now it supports only Codex and Claude.

## Features

Alku bundles and installs five public 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 validates the root `docs/` directory as a closed, structured collection.
It preserves recognized authored records, owns generated indexes and explicitly
marked projections, and reports collisions instead of adopting unmarked files.
Move pre-existing documentation into the supported structure before relying on
`alku docs check`.

## Requirements and install

Alku requires Python 3.11 or newer. The recommended installation path uses
[uv](https://docs.astral.sh/uv/getting-started/installation/), but uv is not a
runtime dependency. Install Alku as a user-level tool:

```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. Preview initialization
first if the repository already contains documentation or agent instructions:

```console
cd /path/to/repository
alku init --dry-run
alku init
alku docs check --json
```

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.

Initialization also appends a concise `Managed by Alku` section to the project
README when that heading is absent. After reviewing the created files and
restarting your agent session, start with one of these prompts:

```text
Use the alku-workflow skill to implement <one bounded feature>.
Use the alku-brainstorm skill to propose the next useful project features.
Use the alku-auto skill to implement all eligible planned features.
Use the alku-docs skill to audit and reconcile the repository documentation.
Use the alku-architecture skill to audit the high-level project structure.
```

`alku-workflow` is the normal entrypoint for one feature. Use `alku-auto` only
after reviewing the planned feature backlog because it delegates every eligible
plan sequentially.

## Command guide

| Command | Purpose |
| --- | --- |
| `alku init [PATH]` | Create or refresh managed documentation, instructions, skills, and agent profiles. |
| `alku init --dry-run --json` | Preview initialization without writes and emit a structured report. |
| `alku docs check [--json]` | Validate documentation and managed project state without writes. |
| `alku docs generate [--json]` | Refresh indexes and managed state; create missing Claude instructions; restore managed skills. |
| `alku docs list --kind KIND` | List product, feature, or proposal records. |
| `alku docs show RECORD --kind KIND` | Read one record or document role. |
| `alku docs search QUERY` | Search visible Markdown sections across record collections. |
| `alku self check` | Check PyPI for a newer release without changing the installation. |
| `alku self update` | Explicitly install and verify a newer release. |

`alku docs generate` can update managed files outside `docs/`, including
`AGENTS.md`, a missing `CLAUDE.md`, and public or private skill files under
`.agents/skills/` and `.claude/skills/`. It refuses to repair a stale or
malformed existing `CLAUDE.md`; rerun `alku init` for that recovery path. It
does not install provider-native agent profiles. Review the complete repository
diff afterward. A zero-diagnostic `docs check` or `docs generate` is silent in
human mode even when generation wrote files; warnings are printed but still
exit successfully. Use `--json` when an explicit result is useful.

## 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 .
```
