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, but uv is not a runtime dependency. Install Alku as a user-level tool:

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:

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:

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:

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, 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.

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

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

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

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:

uv tool install --force .