koushal2018/kirocrew-project-setup-skill

Kiro Crew Project Setup

Build a project-specific crew that is useful without silently widening its authority. Treat this skill as a setup and operations workflow, not as permission to publish, deploy, merge, change repository settings, or enable unattended work.

Requires local shell access. Kiro Crew and Kiro CLI commands vary by installed version. GitHub automation additionally requires git and an authenticated GitHub CLI.

Start with discovery

1. Identify the repository root and read its instructions (AGENTS.md, CLAUDE.md, .kiro/steering/, contribution docs, and CI configuration).

2. Inspect the worktree before changing it. Preserve unrelated user changes.

3. Inspect installed commands instead of assuming a Kiro Crew version:

   kirocrew --version
   kirocrew --help
   kirocrew agent --help
   kirocrew workspace --help
   kiro-cli --version
   kiro-cli agent --help
   

4. Run the bundled read-only preflight from this skill directory:

   python3 scripts/kirocrew_preflight.py --repo /absolute/path/to/repository
   

5. Separate read-only discovery from state-changing setup. Get explicit authorization before installing a service, changing GitHub settings or labels, enabling an unattended crew, publishing, deploying, merging, or sending external messages.

Route to the relevant guide

Read only the references needed for the requested mode:

• Designing an operating guide, specialists, delegation, or a development-and-content team: team-design.md
• Processing opt-in GitHub issues into draft pull requests: github-issue-radar.md
• Diagnosing a failing gateway or system service: service-troubleshooting.md
• Installing or sharing this skill across assistants: installation.md

Use the files under assets/ as starting points. Copy them into the target repository, replace every {{PLACEHOLDER}}, remove irrelevant rules, and validate the result. Do not edit a template in place and call it project-ready.

Apply the setup in layers

1. Write one project operating guide that defines scope, decision rights, quality gates, prohibited actions, and handoffs.

2. Create narrowly scoped Kiro agents. Give each agent only the tools, paths, commands, and delegated agents it needs.

3. Keep irreversible or public actions behind explicit human gates. Editorial approval does not imply deployment permission; code permission does not imply publication permission.

4. Validate every custom agent:

   kiro-cli agent validate --path .kiro/agents/AGENT.json
   kiro-cli agent list
   

5. Smoke-test the agent directly with a harmless prompt that forbids browsing, delegation, tools, and file changes. Confirm it states the expected boundaries.

6. If Kiro Crew agents or workspaces are needed, inspect the installed subcommand help, then create or update them. In the currently tested CLI family, the relevant commands are:

   kirocrew workspace create --name PROJECT
   kirocrew agent create --name COORDINATOR --kiro-agent KIRO_AGENT --workspace PROJECT
   kirocrew agent list
   kirocrew workspace list
   

7. Start either a foreground gateway or the service, never both on the same port. Use the foreground gateway for first-run testing and the service only after the setup works.

8. Re-run the preflight and targeted smoke tests from the same runtime context that will execute scheduled or Issue Radar work.

Enforce autonomy with defense in depth

For unattended issue work, enforce the same boundaries at multiple layers:

• Selection: a dedicated opt-in label; an empty label set must never mean “all issues.”
• Concurrency: begin with one open task.
• Agent policy: draft PRs only; no merge, ready-for-review transition, deployment, publication, default-branch push, force-push, secret access, or CI-gate edits.
• Filesystem and shell permissions: allow only the required paths and commands; explicitly deny dangerous commands and sensitive paths.
• Forge settings: keep automatic merging disabled as an independent backstop.
• Human gates: escalate unclear requirements, architectural changes, authentication, billing, security-sensitive work, major dependencies, deployment, and editorial decisions.

Do not trust a saved dashboard flag by itself. Verify runtime behavior from logs, the actual gateway workspace, the generated branch/PR state, and repository settings.

Finish with evidence

Report:

• Files created or changed and whether they are project-local, user-level, or system-level.
• Exact validation and smoke-test results.
• Gateway/service state and which process owns the configured port.
• GitHub automation scope, labels, concurrency, and merge protections.
• External actions deliberately not taken.
• Any version-specific behavior or unresolved material risk.

Never describe the crew as autonomous or production-ready until a real opt-in test issue has completed safely through a draft pull request without crossing a human gate.