Imported from gzocche/levi (AGENTS.md). Install upstream with npx skills add gzocche/levi. Copyright stays with the author.

AGENTS.md

Status

This repository currently contains only .git. Use this file as the starter engineering contract for agents working here. No .cursor/rules/, .cursorrules, or .github/copilot-instructions.md files were found. If any are added later, merge their guidance into this file.

Planning files in this repo:

1. idea.md for the broad product direction and high-level ideas.
2. .features/README.md for the feature-planning workflow.
3. .features/<feature-name>/feature.md for concrete feature design and implementation notes.
4. .features/<feature-name>/tasks.md for an execution checklist when needed.
5. .features/<feature-name>/runbook.md for a repeatable implementation workflow when needed.

Before substantial implementation work, agents should read idea.md and the relevant .features/ entries. If a feature includes tasks.md or runbook.md, read those too.

Goal

Build a cross-platform developer tool with:

1. A TUI orchestrator for local dev services and scripts.
2. Real-time stdout and stderr streaming in the UI.
3. Plugin-based extensibility.
4. Async execution of multiple tasks.
5. Start, stop, and restart support.
6. Clear separation between UI, orchestration, and execution.

Preferred stack: Python with uv, pwsh, JSON or YAML.

Architecture

Use Python as the orchestration source of truth and PowerShell as an execution adapter.

Important command-system rule:

1. Custom product commands such as run, status, restart, logs, check, and doctor belong in Python.
2. TUI behaviors such as split views belong in the UI layer, not in PowerShell.
3. PowerShell should be used for thin task execution wrappers, not for orchestration, state management, or command routing.

Layers:

1. ui/: Textual app, widgets, log panes, keybindings, status views.
2. application/: orchestration use cases, scheduling, lifecycle, dependency handling.
3. domain/: task models, states, dependency graph, interfaces, typed errors.
4. infrastructure/: subprocess execution, stream readers, config parsing, plugin loading.
5. plugins/: builtin task providers and external extensions.

Boundary rules:

1. UI must not spawn processes directly.
2. Domain must not know about Textual or shell syntax.
3. Infrastructure implements interfaces defined by domain or application.
4. PowerShell scripts stay thin; orchestration logic belongs in Python.
5. Prefer structured args and env vars over large inline shell scripts.

Suggested layout:

src/levi/
  app.py
  cli.py
  domain/
  application/
  infrastructure/
    shell/
    config/
    plugins/
  ui/
  plugins/builtin/
tests/
  unit/
  integration/
scripts/
docs/

Planning layout:

idea.md
.features/
  README.md
  cli-command-system/
    feature.md
  runtime-supervisor/
    feature.md
    tasks.md
    runbook.md

Build, Lint, Test

The repo is empty today, so these are target default commands agents should preserve when scaffolding.

uv venv
uv sync --all-extras --dev
uv run python -m levi
uv run ruff format .
uv run ruff check .
uv run ruff check . --fix
uv run mypy src
uv run pytest
uv run pytest tests/unit/test_task_runner.py
uv run pytest tests/unit/test_task_runner.py::test_runs_dependencies_before_task
uv run pytest -k dependency
uv run pytest tests/integration

Code Style

Imports:

1. Group imports: standard library, third-party, local.
2. Separate groups with one blank line.
3. Use absolute imports from levi.
4. Avoid wildcard imports.

Formatting:

1. Use ruff format as the source of truth.
2. Target line length 100 unless config says otherwise.
3. Do not hand-format against the formatter.

Types:

1. Type all public functions and methods.
2. Use from __future__ import annotations in new modules.
3. Prefer dataclass, Protocol, TypedDict, and Literal over loose dicts.
4. Avoid Any unless unavoidable.

Project tooling:

1. Use uv for environment setup, dependency installation, and running project commands.
2. Keep dependency metadata in pyproject.toml.
3. Prefer uv run <tool> over activating a virtual environment in automation.

Naming:

1. snake_case for variables, functions, modules.
2. PascalCase for classes.
3. UPPER_SNAKE_CASE for constants.
4. Prefer explicit names like task_definition, not data.

Errors and async:

1. Raise typed exceptions for domain and infrastructure failures.
2. Never swallow exceptions silently.
3. Include task name, command, and exit code in failures when relevant.
4. Treat cancellation as distinct from failure.
5. Prefer async end-to-end for orchestration and process management.
6. Use asyncio.create_subprocess_exec for long-running tasks.
7. Stream stdout and stderr incrementally.
8. Avoid blocking the Textual event loop.

Config and plugins:

1. Load YAML or JSON into typed config models.
2. Validate config eagerly at startup.
3. Keep config declarative.
4. Prefer composition and registration over inheritance-heavy plugin designs.
5. New task types should extend the orchestrator through interfaces, not UI branching.

Core Abstractions

1. TaskRunner: resolve dependencies, schedule tasks, emit lifecycle events.
2. ProcessManager: spawn processes, stream logs, stop processes, return exit status.
3. PluginSystem: discover plugins, validate compatibility, register task providers.
4. ConfigLoader: parse config, validate schema, resolve defaults, return typed models.

Command-related design guidance:

1. Expose product commands through a Python CLI or package API.
2. Keep command handlers thin; they should delegate to application services.
3. Share the same runner and state model between CLI and TUI.

Event flow:

1. UI dispatches command to application.
2. Application asks the dependency graph for an execution plan.
3. Task runner delegates execution to process manager.
4. Process manager emits stream events and state changes.
5. UI renders events without owning process state.

Spikes

1. Async subprocess streaming. Goal: verify separate stdout and stderr streaming with cancellation. Output: prototype runner plus tests.

2. Textual multi-log rendering. Goal: confirm UI remains responsive with several noisy tasks. Output: benchmark or demo screen.

3. Dependency graph semantics. Goal: validate ordering, restart rules, and failure propagation. Output: domain model plus unit tests.

4. Plugin discovery. Goal: validate simple registration and version checks. Output: minimal plugin loader.

5. pwsh portability. Goal: verify command invocation on Windows and Unix-like systems. Output: compatibility notes and wrapper implementation.

Roadmap

1. MVP: config loader, async process runner, dependency execution, log streaming, basic TUI.
2. V1: restart support, better error UX, plugin API, persistent log history.
3. V2: Docker and Azure CLI task types, richer plugin packaging, metrics or tracing.

Risks and mitigations:

1. Cross-platform shell differences: isolate shell logic in one adapter.
2. UI lag under heavy output: batch UI updates and test with noisy processes.
3. Overengineered plugin API: start with builtin plugins and one narrow extension point.

Tradeoffs

pwsh vs bash:

1. pwsh is the better default for Windows-first cross-platform scripting.
2. Bash is common on Unix-like systems but less uniform on Windows.

Python orchestration vs full PowerShell:

1. Python is better for async scheduling, testing, TUI composition, and plugins.
2. PowerShell is better as an execution target for existing scripts.

Sync vs async:

1. Sync is simpler but weak for concurrent services and live logs.
2. Async is the right default here.

Extensibility

1. Discover plugins from a known module path or entry points.
2. Require a manifest with name, version, and capabilities.
3. Register task factories instead of allowing plugins to mutate core state directly.
4. Define a common task spec with command, env, cwd, dependencies, and restart policy.
5. Implement adapters for process, docker, az, or custom providers.

Feature-planning guidance:

1. Put new major work in .features/<feature-name>/feature.md before implementation.
2. Use idea.md for broad ideas, product direction, and future concepts.
3. Use feature files for scope, design, validation, and open questions.
4. Add tasks.md when the work benefits from a checkbox-style execution list.
5. Add runbook.md when the work needs a standard sequence of implementation and verification steps.

Minimal Examples

async def run_command(*cmd: str) -> int:
    proc = await asyncio.create_subprocess_exec(*cmd, stdout=PIPE, stderr=PIPE)
    ...

async def run_task(task, tasks, seen=None):
    ...

Testing Expectations

1. Unit test graph logic and state transitions.
2. Integration test subprocess execution and pwsh wrappers.
3. Add regression tests for bug fixes.
4. Cover cancellation, restart, dependency ordering, and stream handling.

Agent Behavior

1. Prefer simple, observable implementations over speculative abstractions.
2. Keep layers separate.
3. Add new abstractions only when two real use cases need them.
4. Update this file when tooling or conventions become real in the repo.