kelos-dev/kelos

Problem As a new user following the Quick Start guide, the ordering of steps is confusing and can lead to errors. The current flow is: Install the CLI Install Axon (axon install) Initialize Your Config (axon init) Run Your First Task However, the Demo section (lines 22-35) appears BEFORE the Quick Start and shows: # Initialize your config $ axon init # Edit ~/.axon/config.yaml with your token and workspace This creates confusion because: New users may try to run axon init before installing Axon to the cluster, which works (it's just a local file operation), but then they might not realize they still need to run axon install The axon init command output provides helpful next steps (see internal/cli/init.go:44-62) including "Install Axon (if not already installed): axon install", but this conflicts with the Quick Start ordering The logical flow for a new user is: install CLI → initialize config with credentials → install to cluster → run first task Evidence from Code Looking at

Problem The "Auto-fix GitHub issues with TaskSpawner" example in the README shows: apiVersion: axon.io/v1alpha1 kind: TaskSpawner metadata: name: fix-bugs spec: when: githubIssues: labels: [bug] state: open taskTemplate: workspaceRef: name: my-workspace A new user reading this example would reasonably ask: "Which GitHub repository is this watching for issues?" The answer is non-obvious: the repository is derived from the Workspace's repo URL. This critical connection is documented in the code comments (api/v1alpha1/taskspawner_types.go:39-41) but not in the README. Why This is Confusing The githubIssues section has no repo field The connection to workspaceRef is not explained Users might assume they need to configure the repository elsewhere The Workspace is shown as a separate resource for cloning code, not for identifying the GitHub repo to poll Current State The actual behavior (from the code): // GitHubIssues discovers issues from a GitHub reposito

Problem The README prominently mentions that Axon supports three agent types: Claude Code OpenAI Codex Google Gemini However, all documentation and examples only show Claude Code usage. There are no examples demonstrating how to use Codex or Gemini. Current State The README line 9 says: "runs AI coding agents (Claude Code, OpenAI Codex, Google Gemini)" The README line 68 says: "Currently supported agents: Claude Code, OpenAI Codex, and Google Gemini." All examples in the README use Claude Code: Quick Start uses oauthToken (Claude Code specific) All TaskSpawner examples use claude-code type Config file template shows Claude credentials only The agent implementations exist (codex/ and gemini/ directories with Dockerfiles and entrypoints) The agent-image-interface.md doc mentions the environment variables (CODEX_API_KEY, GEMINI_API_KEY) but provides no usage examples Why This is a Problem Discovery gap: Users don't know how to actually use these agents Credibility gap: Pr

Problem The `axon run` command accepts an empty string for the required `--prompt` flag, creating invalid Tasks that will fail at the API level. Current Behavior # Empty prompt is accepted axon run -p "" --secret dummy --dry-run # Output: apiVersion: axon.io/v1alpha1 kind: Task metadata: name: task-twq97 spec: prompt: "" # Empty! ... If submitted to the cluster (without `--dry-run`), this would fail at the Kubernetes API validation level, but only after: The task resource is attempted to be created Network round-trip to the API server API-level validation runs Why This is a Problem Late failure: Error happens at API submission, not immediately Poor error location: Users don't get helpful context about which CLI flag is the problem Wasted resources: Unnecessary API call for an obvious client-side issue Incomplete client validation: The CLI marks `--prompt` as required (`cmd.MarkFlagRequired("prompt")`) but doesn't validate it's non-empty Expected Behavior The CLI should valid