Metadata-Version: 2.5
Name: alku
Version: 0.5.5
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` — audit or reconcile documentation within the requested scope; broader audits follow evidence of drift or a chosen maintenance interval.
5. `alku-architecture` — review project boundaries after consequential structural changes, on request, or at a chosen maintenance interval.

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. It also creates
a comments-only `.alku.yml` for optional model overrides. 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.

## Configure models

Alku bundles model and reasoning defaults for both providers. The project-root
`.alku.yml` overrides only the values you specify. Leave it empty to inherit the
installed version's defaults. For example:

```yaml
providers:
  openai:
    models:
      balanced: gpt-5.6-terra
    roles:
      auto: {model: premium, effort: low}
      develop-medium: {model: balanced, effort: medium}
      workflow: {effort: medium}
```

`model` names an alias from `models`: OpenAI defaults include `main` (Sol),
`efficient` (Luna), and `premium` (Astra). Add aliases or change their model IDs;
changing an alias affects every role referencing it. Each role can independently
override `model` and `effort` (`low`, `medium`, `high`, or `xhigh`). The provider
must support the selected model and effort.

Role keys are `auto`, `workflow`, `design`, `vision`, `research`, `review`,
`review-critical`, `develop-low`, `develop-medium`, `develop-high`, `brainstorm`,
`architecture`, `architecture-wide`, and `docs`. Their native profiles prepend
`alku-`. The legacy `implementation` and `mechanical` keys configure model
reporting; developer profiles use the separate `develop-*` assignments.

The workflow delegates visual interpretation to `alku-vision`, which defaults to
Astra/high for OpenAI and main/high for Anthropic. It inspects images and rendered
pages and returns visual evidence; feature owners retain acceptance and route
repairs to implementers. Image or browser access must be available to perform
the assigned inspection.

Run `alku init` after changing overrides, then restart active provider sessions.
Select the corresponding named agent to use its model configuration; loading a
skill alone does not switch the current agent's model. Remove an override to
inherit the latest bundled default on the next init.

Init warns when an effective model or effort override differs from the installed
defaults, showing both values while keeping your override. This comparison runs
on every init, including after upgrades; it does not require stored history.
Matching overrides and inherited defaults produce no warning.

The leading `# alku:config:begin` / `# alku:config:end` comments are managed help.
Init replaces that block as guidance evolves and preserves your YAML and comments
outside it. Keep your settings outside the block. Invalid YAML or ambiguous
markers stop initialization before it changes project content.

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