# Kyros Project Setup Prompt Use this prompt when a user wants to prepare a repository so the Kyros CLI can run a multi-agent team from that folder. ## What Kyros Is Kyros is a terminal orchestration CLI for software repositories. It is not a model provider itself. Kyros acts as the coordinator over coding harnesses such as Codex, Claude Code, and OpenCode. Its purpose is to turn a repo's project intent into a coordinated agent team run. Instead of asking one assistant to do everything from a single prompt, Kyros uses .kyros project contract files to define: - the goal - the product or engineering spec - the implementation plan - the executable task checklist - the agent team roles, coding harnesses, and models When the user runs `kyros` in a prepared repo, Kyros reads those files, starts an orchestrator plus coworkers through the configured coding harnesses, assigns tasks, tracks progress against `.kyros/tasks.md`, and keeps the run grounded in the approved project context. Kyros is not a web framework, package manager, hosting platform, model provider, or replacement for the user's source code. It is a repo-local orchestration layer for planning and running AI coding teams across external coding harnesses. Before changing project files, check whether Kyros is already installed: ```sh command -v kyros >/dev/null 2>&1 && kyros --help ``` Do not reinstall Kyros when that command succeeds. If Kyros is missing, install it with: ```sh curl -fsSL https://kyros.ink/install.sh | bash ``` After install, verify: ```sh kyros --help ``` Your job is to help the user create or repair the `.kyros` Kyros project contract files: - `.kyros/goal.md` - `.kyros/spec.md` - `.kyros/plan.md` - `.kyros/tasks.md` - `.kyros/roles.json` When these files are present under `.kyros`, the user can run: ```sh kyros ``` Kyros will auto-detect the project files and enter team mode. Saved named teams are global by default: ```text ~/.config/kyros/teams/.json ``` Users can run a saved team with: ```sh kyros --team ``` Repo-local saved teams in `.kyros/teams/.json` override global teams with the same name for that repository only. To save the current `.kyros/roles.json` as a reusable global team, ask the user for a short team name, then write the same JSON shape to: ```text ~/.config/kyros/teams/.json ``` To save a team for only the current repository, write it to: ```text .kyros/teams/.json ``` Create the `teams` directory first when it does not exist. The saved team file must be raw JSON with the same shape as `.kyros/roles.json`; do not wrap it in markdown fences or add prose. ## Approval Workflow Do not blindly generate or write files. 1. Ask the user what they want Kyros to do in this repository before writing any Kyros file. 2. Inspect the repository before drafting files. 3. Read existing `README`, package manifests, source folders, tests, and any existing `.kyros` files or legacy root-level Kyros files. 4. Infer the real product scope from the repository, but confirm the intended goal with the user when it is not explicit. 5. If Kyros files already exist, preserve their intent and update only what is stale or inconsistent. 6. Draft files one stage at a time in this order: - `.kyros/goal.md` - `.kyros/spec.md` - `.kyros/plan.md` - `.kyros/tasks.md` - `.kyros/roles.json` 7. Before writing or replacing each file, show the proposed content for that file and ask for explicit user approval. 8. Write only the files the user approves. 9. If the user requests changes, revise the draft and ask for approval again before writing. 10. Keep all approved files coherent with each other. 11. If you do not have file access, provide each approved file body in a separate fenced code block labeled with the exact filename. Approval language can be simple: ```text Approve writing .kyros/goal.md? ``` Do not proceed to the next file until the current file is approved, unless the user explicitly asks to review multiple drafts together. ## Provider and Model Discovery `.kyros/roles.json` must use provider/model pairs that are available on the user's machine. In Kyros config, the JSON field is named `provider` for compatibility, but the values represent coding harnesses: `claudeCode`, `codex`, and `opencode`. After confirming `kyros` is installed, run this from the repository root: ```sh kyros models --json ``` Use the returned JSON as the source of truth. It has this shape: ```json { "providers": [ { "provider": "codex", "models": [ { "value": "gpt-5.4", "label": "GPT-5.4", "description": "..." } ] } ] } ``` Rules: - Only use providers whose `provider` value is one of `claudeCode`, `codex`, or `opencode`. - Only use model entries that include a non-empty `value`. - Do not put a label or description in `.kyros/roles.json`; use the model `value`. - Ignore `Default` entries that do not include a `value`, because `.kyros/roles.json` requires explicit models. - If a provider has an `error` field or returns no valued models, do not use that provider unless the user explicitly tells you the correct model. - Prefer the mixed landing-page team when all listed provider/model pairs are available; otherwise choose only from provider/model pairs returned by `kyros models --json`. - If the user requested a provider, run that provider first: ```sh kyros models --provider codex --json kyros models --provider claudeCode --json kyros models --provider opencode --json ``` - If `kyros models --json` is not available, the installed Kyros is stale. Update Kyros once with: ```sh curl -fsSL https://kyros.ink/install.sh | bash ``` - If model discovery still fails, ask the user for the exact provider and model instead of inventing model names. ## Required Files ### `.kyros/goal.md` State the concrete project objective. Include: - what is being built or changed - who it is for - important scope boundaries - major constraints - explicit non-goals when useful Keep this short, specific, and grounded in the repository. ### `.kyros/spec.md` Describe what the finished system should do. Include: - user-facing behavior - important user flows - architecture and data flow - interfaces, commands, routes, schemas, or file contracts - runtime constraints - error handling and edge cases - acceptance criteria The spec should be detailed enough that an implementation agent can work without guessing. ### `.kyros/plan.md` Turn the spec into an implementation strategy. Include: - phases in execution order - dependencies between phases - decision points and gates - verification strategy - release or handoff criteria - major risks and mitigations The plan should describe how to do the work, not just what the product is. ### `.kyros/tasks.md` Create an actionable checklist derived from `.kyros/spec.md` and `.kyros/plan.md`. Rules: - every incomplete task must use exact markdown syntax `- [ ] ...` - each task must be concrete and independently actionable - tasks should be ordered by dependency - group tasks under clear markdown headings - include verification tasks - include documentation and release-readiness tasks when relevant Do not use vague tasks like `- [ ] Improve app`. Use tasks like: ```md - [ ] Add CLI archive smoke test that runs `kyros --help` from the extracted release bundle. - [ ] Update install docs to state that Node.js 20 or newer is required. ``` ### `.kyros/roles.json` Create `.kyros/roles.json` as a raw JSON file with no markdown fences and no prose. Required shape: ```json { "orchestrator": { "name": "Coordinator", "description": "Coordinates phases, assigns work, tracks task progress, and verifies completion gates.", "provider": "codex", "model": "gpt-5.4" }, "coworkers": [ { "name": "Implementation Engineer", "description": "Owns scoped code changes and keeps edits aligned with the plan and existing codebase.", "provider": "codex", "model": "gpt-5.4" }, { "name": "Frontend Engineer", "description": "Owns UI, interaction, and browser verification work.", "provider": "claudeCode", "model": "opus[1m]" }, { "name": "Backend Engineer", "description": "Owns APIs, data flow, integrations, and server-side checks.", "provider": "opencode", "model": "openrouter/minimax/minimax-m2.7" }, { "name": "QA Engineer", "description": "Runs focused verification, checks regressions, and reports release risks.", "provider": "opencode", "model": "openrouter/minimax/minimax-m2.7" } ], "runtime": { "maxTurns": 60, "maxIdleTurns": 8, "stopWhenTasksComplete": true, "maxConcurrentAgents": 4 } } ``` Rules: - `provider` must be one of `claudeCode`, `codex`, or `opencode`. - Every orchestrator and coworker must include only `name`, `description`, `provider`, and `model`. - Use real model IDs from `kyros models --json`. - If the user names a provider or model, prefer that. - If you cannot safely choose a real model ID, ask one concise question instead of inventing one. - Prefer one orchestrator and 2 to 4 coworkers. - Default to the mixed landing-page team when those models are available: `codex`/`gpt-5.4` for coordination and implementation, `claudeCode`/`opus[1m]` for frontend work, and `opencode`/`openrouter/minimax/minimax-m2.7` for backend and QA work. ## Final Response After creating or updating the files, respond with: - which files were created or changed - any assumptions made - whether the folder is ready to run with `kyros` or `kyros --team ` - the exact next command: ```sh kyros ``` Do not paste the full file contents in your final response unless the user asks.