alku 0.5.0__tar.gz

alku-0.5.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.idea/
+dist/
+__pycache__/
+*.py[cod]
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.pypirc

alku-0.5.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+## 0.5.0 - 2026-09-04
+
+- Defined the user-facing skill catalog from the root README as exactly
+  `alku-workflow`, `alku-auto`, `alku-brainstorm`, `alku-docs`, and
+  `alku-architecture`.
+- Added project-growth brainstorming and separated periodic repository-wide
+  documentation and architecture maintenance from per-feature workflow review.
+- Moved research, development, review, feature documentation reconciliation,
+  and feature architecture review into managed private references consumed
+  only by `alku-workflow`.
+- Extended managed skill validation, installation, refresh, generation, and
+  live-agent evaluation routing to include private workflow resources without
+  exposing helper skill entrypoints.
+- Made `alku init` install OpenAI and Anthropic skills together, with
+  provider-native workflow, research, review, and workload-scaled development
+  profiles carrying explicit model and effort settings.
+- Replaced the monolithic initialization function table with inheritable
+  pipeline-step classes, interactive optional-feature questions, and resumable
+  blocking external-agent handoffs.
+- Added an ordered `alku.migrations` framework that updates already-initialized
+  user projects during `alku init` with idempotent, versioned, multi-file
+  migrations, strict registry validation, structured outcomes, and
+  compensating rollback.
+- Replaced duplicated Claude workflow gates with Claude's native `@AGENTS.md`
+  import while preserving authored text outside proven legacy managed blocks.
+
+## 0.4.0 - 2026-09-04
+
+- Reset the installation baseline to current Alku projects: initialization and
+  generation no longer recognize or migrate former gate, generated-index,
+  configuration, or unmarked skill formats.
+- Removed deprecated duplicate initialization output fields and the obsolete
+  dependency-migration reporting step; recommendations now expose only their
+  message, shell-free argument vector, and working directory.
+- Required an explicit record kind for `alku docs list` and `alku docs show`,
+  and renamed invalid query payloads from `invalid_features` to
+  `invalid_records`.
+- Kept current-sentinel managed-file refresh and transactional proposal-width
+  normalization as the extension mechanisms for future format changes.
+
+## 0.3.0 - 2026-09-04
+
+- Made initialization and bundled-skill synchronization idempotently resumable
+  with docs-scaffold and skill-catalog collision preflights plus
+  interrupted-file cleanup.
+- Added `alku --version`, a single Hatch version source, verified post-install
+  self-updates, explicit artifact exclusions, and security/release guidance.
+- Added reusable large-repository regressions for 100,000 documentation and
+  code lines, 1,000 features, and 1,000 proposals.
+- Made dependency-cycle validation iterative, removed the fixed generated-index
+  word ceiling, and rejected repository-local feature symlinks.
+- Rejected symlinked initialization roots, preflighted documentation scaffold
+  collisions before writes, and normalized malformed PyPI JSON failures.
+- Added conditional agent recommendations for migrating a root
+  `requirements.txt` to `pyproject.toml`.
+- Added self-update as the first managed workflow action and require `alku init`
+  to be rerun after an update.
+- Added a conditional Ruff/ty workflow step for projects with root
+  `pyproject.toml` and removed the `alku-quality` command.
+- Bundled Holvi's autonomous backlog skill as `alku-auto` and install it during
+  initialization.
+- Prevented delegated feature owners from recursively treating `alku-auto` as
+  their governing workflow or starting another backlog-orchestration loop.
+- Moved the reusable agent procedure into a provider-neutral `alku-workflow`
+  skill, reduced managed instruction files to a self-repairing loader gate,
+  and made Alku-owned skill checks and upgrades fail-closed, root-anchored, and
+  transactional.
+- Added focused `alku-research`, `alku-develop`, and `alku-review` contracts,
+  routed them through the managed workflow, and removed the autonomous
+  orchestrator's hardcoded feature-owner model.
+- Added conditional read-only architecture review and final documentation
+  reconciliation skills, with objective risk triggers, recoverable autonomous
+  stage ordering, and deterministic orchestration regressions.
+- Replaced the open-ended documentation tree with strict product, feature, and
+  proposal record collections; rejected unknown nodes, generated indexes for
+  all three collections, and added kind-aware documentation queries.
+- Added record-kind orientation to `alku docs --help` and a complete
+  initialized documentation-tree guide with role-selection advice.
+- Reconciled the guides with the public command behavior, made pre-release
+  blockers explicit, and removed duplicated collection and implementation
+  contracts.
+- Restricted legacy index migration to files with proven generated ownership
+  and reported unreadable documentation nodes without uncaught exceptions.
+- Started proposal sequences at three digits and added transactional,
+  collection-wide widening at `1000`, `10000`, and later decimal boundaries,
+  with exact structured-reference edits, stale-input refusal, and compensating
+  rollback for generated indexes and managed gates.
+
+## 0.2.0 - 2026-09-04
+
+- Split the CLI into `alku init`, `alku docs …`, and `alku self update`.
+- Replaced project YAML configuration with an authoritative, extensible docs
+  structure and automatic `scripts/`/`tools/` discovery.
+- Made initialization non-agentic: it reports a manual command and prompt,
+  checks `codebase-memory-mcp`, and mirrors managed instructions into both
+  `AGENTS.md` and `CLAUDE.md`.
+- Added safe PyPI version checking and user-tool self-update behavior.
+- Migrated the complete test suite to pytest and pytest-cov with a required
+  100% line-coverage gate.
+- Documented user-level installation and PATH setup.

alku-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ragnaruk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alku-0.5.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: alku
+Version: 0.5.0
+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.
+
+## 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
+
+Until a public release exists, install Alku from a checkout:
+
+```console
+uv tool install --force .
+uv tool update-shell
+```
+
+Restart the shell if `uv tool update-shell` changes `PATH`. After publication,
+`uv tool install alku` will install the packaged release.
+
+## Quick start
+
+To add Alku to the project run `alku init`, it will:
+
+1. Run applicable versioned migrations for an existing Alku project;
+2. Create the `docs` directory;
+3. Update the managed `AGENTS.md` gate and make `CLAUDE.md` import it;
+4. Install bundled skills for OpenAI and Claude;
+5. Install provider-native named agent profiles with role-specific effort;
+6. Ask about optional integrations and external-agent handoffs when interactive;
+
+After that, launch a new agent session and you're done.
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Command reference](docs/product/api/README.md)
+- [Architecture](docs/product/architecture/README.md)
+- [Operations](docs/product/operations/README.md)
+- [Development](docs/product/development/README.md)
+- [Release readiness](docs/product/release/README.md)
+
+Alku manages product, feature, and proposal records beneath `docs/`. The
+[collection model](docs/features/structured_document_collections/README.md)
+defines the record kinds, and the
+[validation contract](docs/features/repository_validation/design.md) defines
+their allowed structure and integrity rules.
+
+## Development
+
+```console
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check --extra-search-path src .
+uv build
+```
+
+The test configuration requires 100% line coverage. See the
+[development guide](docs/product/development/README.md) for the change workflow
+and explicit large-repository regression command.

alku-0.5.0/README.md

@@ -0,0 +1,69 @@
+# Alku
+
+Alku is a meta-framework for modern autonomous agentic development.
+
+## 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
+
+Until a public release exists, install Alku from a checkout:
+
+```console
+uv tool install --force .
+uv tool update-shell
+```
+
+Restart the shell if `uv tool update-shell` changes `PATH`. After publication,
+`uv tool install alku` will install the packaged release.
+
+## Quick start
+
+To add Alku to the project run `alku init`, it will:
+
+1. Run applicable versioned migrations for an existing Alku project;
+2. Create the `docs` directory;
+3. Update the managed `AGENTS.md` gate and make `CLAUDE.md` import it;
+4. Install bundled skills for OpenAI and Claude;
+5. Install provider-native named agent profiles with role-specific effort;
+6. Ask about optional integrations and external-agent handoffs when interactive;
+
+After that, launch a new agent session and you're done.
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Command reference](docs/product/api/README.md)
+- [Architecture](docs/product/architecture/README.md)
+- [Operations](docs/product/operations/README.md)
+- [Development](docs/product/development/README.md)
+- [Release readiness](docs/product/release/README.md)
+
+Alku manages product, feature, and proposal records beneath `docs/`. The
+[collection model](docs/features/structured_document_collections/README.md)
+defines the record kinds, and the
+[validation contract](docs/features/repository_validation/design.md) defines
+their allowed structure and integrity rules.
+
+## Development
+
+```console
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check --extra-search-path src .
+uv build
+```
+
+The test configuration requires 100% line coverage. See the
+[development guide](docs/product/development/README.md) for the change workflow
+and explicit large-repository regression command.

alku-0.5.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "alku"
+dynamic = ["version"]
+description = "Meta-framework for modern autonomous agentic development"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ragnaruk", email = "ima1365@me.com" }]
+requires-python = ">=3.11"
+dependencies = ["click>=8.1.8,<9", "markdown-it-py>=3,<5", "packaging>=24,<27", "PyYAML>=6,<7"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.scripts]
+alku = "alku.cli:cli"
+
+[tool.hatch.version]
+path = "src/alku/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/alku", "CHANGELOG.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/alku"]
+
+[dependency-groups]
+dev = ["pytest>=8.4,<10", "pytest-cov>=6,<8", "ruff", "ty"]
+
+[tool.pytest.ini_options]
+addopts = ["--cov=alku", "--cov-report=term-missing", "--cov-fail-under=100"]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["alku"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = true
+
+[tool.uv]
+exclude-newer = "1 week"

alku-0.5.0/src/alku/__init__.py

@@ -0,0 +1,3 @@
+"""Alku repository bootstrapper and documentation maintainer."""
+
+__version__ = "0.5.0"

alku-0.5.0/src/alku/__main__.py

@@ -0,0 +1,4 @@
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

alku-0.5.0/src/alku/agent_configs.py

@@ -0,0 +1,269 @@
+"""Managed project-scoped agent profiles for supported model providers."""
+
+from __future__ import annotations
+
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from .providers import profile_for
+
+
+class AgentConfigSyncError(ValueError):
+    """A managed agent profile cannot be synchronized safely."""
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    name: str
+    description: str
+    model: str
+    effort: str
+    instructions: str
+    read_only: bool = False
+
+
+@dataclass(frozen=True)
+class AgentConfigSyncReport:
+    state: str
+    copied: tuple[str, ...] = ()
+
+
+def _agent_specs(provider: str) -> tuple[AgentSpec, ...]:
+    """Build native agent specs from the packaged model matrix."""
+    profile = profile_for(provider)
+    if provider == "openai":
+        workflow_instructions = (
+            "Read and follow .agents/skills/alku-workflow/SKILL.md. Own one bounded "
+            "feature, retain architecture and documentation context, and return a "
+            "verified result to the parent agent."
+        )
+        research_instructions = (
+            "Read and follow .agents/skills/alku-workflow/references/research.md. "
+            "Stay within the delegated question and return concise, cited evidence."
+        )
+        review_instructions = (
+            "Read and follow .agents/skills/alku-workflow/references/review.md. "
+            "Review the post-generation artifact independently and lead with concrete "
+            "findings."
+        )
+        develop_instructions = (
+            "Read and follow .agents/skills/alku-workflow/references/develop.md. "
+            "Implement only the assigned files and acceptance criteria, preserve "
+            "unrelated changes, and report targeted verification."
+        )
+    else:
+        workflow_instructions = (
+            "Follow the preloaded alku-workflow skill. Own one bounded feature, retain "
+            "architecture and documentation context, and return a verified result to "
+            "the parent agent."
+        )
+        research_instructions = (
+            "Read .claude/skills/alku-workflow/references/research.md. Stay within the "
+            "delegated question and return concise, cited evidence."
+        )
+        review_instructions = (
+            "Read .claude/skills/alku-workflow/references/review.md. Review the "
+            "post-generation artifact independently and lead with concrete findings."
+        )
+        develop_instructions = (
+            "Read .claude/skills/alku-workflow/references/develop.md. Implement only "
+            "the assigned files and acceptance criteria, preserve unrelated changes, "
+            "and report targeted verification."
+        )
+
+    specs = [
+        AgentSpec(
+            "alku-workflow",
+            "Own one bounded Alku feature from approved plan through verification.",
+            profile.model_for("workflow"),
+            profile.effort_for("workflow"),
+            workflow_instructions,
+        ),
+        AgentSpec(
+            "alku-research",
+            "Investigate a bounded question and return evidence without editing code.",
+            profile.model_for("research"),
+            profile.effort_for("research"),
+            research_instructions,
+            True,
+        ),
+        AgentSpec(
+            "alku-review",
+            "Independently review a completed Alku change for material risks.",
+            profile.model_for("review"),
+            profile.effort_for("review"),
+            review_instructions,
+            True,
+        ),
+    ]
+    specs.extend(
+        AgentSpec(
+            f"alku-develop-{effort}",
+            f"Implement bounded Alku work at {effort} reasoning effort.",
+            profile.model_for(f"develop-{effort}"),
+            profile.effort_for(f"develop-{effort}"),
+            develop_instructions,
+        )
+        for effort in ("low", "medium", "high")
+    )
+    return tuple(specs)
+
+
+OPENAI_AGENT_SPECS = _agent_specs("openai")
+ANTHROPIC_AGENT_SPECS = _agent_specs("anthropic")
+
+
+def _kind(path: Path) -> str:
+    try:
+        mode = path.lstat().st_mode
+    except FileNotFoundError:
+        return "missing"
+    except OSError:
+        return "other"
+    if stat.S_ISLNK(mode):
+        return "symlink"
+    if stat.S_ISREG(mode):
+        return "file"
+    if stat.S_ISDIR(mode):
+        return "directory"
+    return "other"
+
+
+def _safe_parent(root: Path, path: Path) -> bool:
+    try:
+        relative = path.parent.relative_to(root)
+    except ValueError:
+        return False
+    current = root
+    for part in relative.parts:
+        current /= part
+        if _kind(current) in {"symlink", "file", "other"}:
+            return False
+    return True
+
+
+def _toml(spec: AgentSpec) -> str:
+    sandbox = 'sandbox_mode = "read-only"\n' if spec.read_only else ""
+    return (
+        "# alku:managed-agent\n"
+        f'name = "{spec.name}"\n'
+        f'description = "{spec.description}"\n'
+        f'model = "{spec.model}"\n'
+        f'model_reasoning_effort = "{spec.effort}"\n'
+        f"{sandbox}"
+        'developer_instructions = """\n'
+        f"{spec.instructions}\n"
+        '"""\n'
+    )
+
+
+def _markdown(spec: AgentSpec) -> str:
+    permission = "\npermissionMode: plan" if spec.read_only else ""
+    skills = "\nskills:\n  - alku-workflow" if spec.name == "alku-workflow" else ""
+    return (
+        "---\n"
+        f"name: {spec.name}\n"
+        f"description: {spec.description}\n"
+        f"model: {spec.model}\n"
+        f"effort: {spec.effort}"
+        f"{permission}{skills}\n"
+        "---\n"
+        "<!-- alku:managed-agent -->\n\n"
+        f"{spec.instructions}\n"
+    )
+
+
+def agent_config_outputs(root: Path) -> tuple[tuple[Path, str], ...]:
+    """Return every provider-native project agent profile."""
+    outputs = [
+        (root / ".codex" / "agents" / f"{spec.name}.toml", _toml(spec))
+        for spec in OPENAI_AGENT_SPECS
+    ]
+    outputs.extend(
+        (root / ".claude" / "agents" / f"{spec.name}.md", _markdown(spec))
+        for spec in ANTHROPIC_AGENT_SPECS
+    )
+    return tuple(outputs)
+
+
+def _managed(path: Path, content: str) -> bool:
+    if path.suffix == ".toml":
+        return content.startswith("# alku:managed-agent\n")
+    if not content.startswith("---\n"):
+        return False
+    end = content.find("\n---\n", 4)
+    return end >= 0 and content[end + 5 :].startswith("<!-- alku:managed-agent -->\n")
+
+
+def sync_agent_configs_report(
+    root: Path, *, dry_run: bool = False
+) -> AgentConfigSyncReport:
+    """Synchronize both provider profile sets with whole-file ownership checks."""
+    planned: list[tuple[Path, str, str | None]] = []
+    for path, content in agent_config_outputs(root):
+        if not _safe_parent(root, path):
+            raise AgentConfigSyncError(f"unsafe managed agent parent: {path.parent}")
+        kind = _kind(path)
+        if kind == "missing":
+            planned.append((path, content, None))
+            continue
+        if kind != "file":
+            raise AgentConfigSyncError(f"unsafe managed agent collision: {path}")
+        try:
+            actual = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as error:
+            raise AgentConfigSyncError(
+                f"cannot read managed agent {path}: {error}"
+            ) from error
+        if actual == content:
+            continue
+        if not _managed(path, actual):
+            raise AgentConfigSyncError(
+                f"fail-closed agent collision: unmarked/user-owned file: {path}"
+            )
+        planned.append((path, content, actual))
+    if not dry_run:
+        for path, content, original in planned:
+            if not _safe_parent(root, path):
+                raise AgentConfigSyncError(
+                    f"concurrent managed agent parent update: {path.parent}"
+                )
+            path.parent.mkdir(parents=True, exist_ok=True)
+            if original is None:
+                if _kind(path) != "missing":
+                    raise AgentConfigSyncError(
+                        f"concurrent managed agent update: {path}"
+                    )
+                with path.open("x", encoding="utf-8", newline="") as stream:
+                    stream.write(content)
+                continue
+            if _kind(path) != "file":
+                raise AgentConfigSyncError(f"concurrent managed agent update: {path}")
+            try:
+                current = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError) as error:
+                raise AgentConfigSyncError(
+                    f"cannot recheck managed agent {path}: {error}"
+                ) from error
+            if current != original or not _managed(path, current):
+                raise AgentConfigSyncError(f"concurrent managed agent update: {path}")
+            temporary = path.with_name(path.name + ".alku-new")
+            if _kind(temporary) == "missing":
+                with temporary.open("x", encoding="utf-8", newline="") as stream:
+                    stream.write(content)
+            elif (
+                _kind(temporary) != "file"
+                or temporary.read_text(encoding="utf-8") != content
+            ):
+                raise AgentConfigSyncError(
+                    f"unsafe managed agent staging collision: {temporary}"
+                )
+            if _kind(path) != "file" or path.read_text(encoding="utf-8") != original:
+                temporary.unlink(missing_ok=True)
+                raise AgentConfigSyncError(f"concurrent managed agent update: {path}")
+            temporary.replace(path)
+    return AgentConfigSyncReport(
+        "copied" if planned else "unchanged",
+        tuple(str(path.relative_to(root)) for path, _, _ in planned),
+    )