Planned Implementation

Planned Implementation

Use this skill for complex KAOS changes that span multiple domains, especially backend plus UI work. The goal is to keep working context focused by gathering domain knowledge in staged passes, documenting only the relevant findings, then executing numbered tasks one by one with validation and commits.

IMPORTANT INSRTUCTIONS: This is quite a comprehensive request, so please ensure that before starting you put together a comprehensive plan to move forward, and a design plan on how this will fit the existing codebase. Create a set of tasks from the TODOs outlined below by number, and make sure you carry them out one by one without skipping any, each of them should ensure the tests are validated and passing, and committed with using commits using "comprehensive commit" style with succint and functional descriptions each individual task is done. Ensure that all tests pass. You have access to github CI, so whenever you create a set of commits, make sure to push to a PR (if not there create one) and validate that they all run correctly; if any major refactors make sure that you run the python and golang tests locally, and you have a KIND cluster available so run 1-3 tests locally before pushing to run the end to end tests in the CI; prefer to run the complete set of tests in the CI github actions, but if you see many failing again run 1-3 locally to validate before; be efficient when it comes to testing. We are still in alpha so breaking changes can be done and migration does not need to be documented.

Ground rules

• Do not start implementation before a written plan exists and the user has approved it.
• Use focused context phases. Prefer subagents for broad research; otherwise gather one domain at a time and write compact notes before moving to the next domain.
• Use ./tmp for scratch files and suppressed output. Do not use /tmp unless external-host access is truly required.
• Create or overwrite REPORT.md at the end, but never commit it. Post its contents as a PR comment.
• Commit each numbered TODO separately with a succinct conventional commit message and the required co-author trailer.
• Do not skip validation for a TODO before committing it. If validation cannot run locally, document why in REPORT.md and rely on PR CI.
• Prefer real local validation when the host already has Docker, Kubernetes, KAOS, UI dev servers, or proxy configuration running. Detect and reuse that setup before falling back to mocked tests or CI-only validation.

Phase 0 - Scope and setup

1. Restate the user request in one paragraph.
2. Identify touched domains: Python backend, Go operator, UI, docs, CLI, workflows, or skills.
3. Create scratch space:

mkdir -p ./tmp
touch ./tmp/null

4. Check repository state before editing:

git --no-pager status --short --branch

Stop and ask the user if existing unrelated changes conflict with the requested work.

5. Detect reusable local runtime configuration and record what is available:

{
  echo "## Local validation environment"
  command -v docker >/dev/null && docker ps --format 'docker: {{.Names}} {{.Status}}' || true
  command -v kubectl >/dev/null && kubectl config current-context 2>./tmp/null || true
  command -v kubectl >/dev/null && kubectl cluster-info 2>./tmp/null || true
  command -v kaos >/dev/null && kaos version 2>./tmp/null || true
  curl -sS -o ./tmp/null -w 'ui:%{http_code}\n' http://localhost:8080/ || true
  curl -sS -o ./tmp/null -w 'ui-alt:%{http_code}\n' http://localhost:8081/ || true
  curl -sS -o ./tmp/null -w 'proxy:%{http_code}\n' http://localhost:8010/ || true
} | tee ./tmp/local-validation-context.txt

If the user says a local KAOS cluster is running, treat the local runtime as the primary E2E validation target. Do not skip local E2E solely because CI will run later.

Phase 1 - Backend context

Read only backend-relevant instructions, docs, source, and tests first. Use this mapping:

• pydantic-ai-server/** -> .github/instructions/python.instructions.md
• operator/**/*.go -> .github/instructions/operator.instructions.md
• operator/tests/** -> .github/instructions/e2e.instructions.md
• kaos-cli/** -> Python instructions plus CLI docs/tests

Capture:

• Entry points and public APIs.
• Existing data models and serialization contracts.
• Tests that currently cover the behavior.
• Validation commands and any known gotchas.
• Risks, migration notes, and compatibility decisions.

Do not start UI research until backend notes are complete.

Phase 2 - UI context

Read only UI-relevant instructions, source, and tests:

• .github/instructions/kaos-ui.instructions.md
• .github/instructions/kaos-ui-testing.instructions.md
• .github/instructions/kaos-ui-components.instructions.md when components are touched
• .github/instructions/kaos-ui-kubernetes-types.instructions.md when Kubernetes/CRD types are touched

Capture:

• Component/state ownership.
• Client/API boundaries.
• Existing UX patterns and test selectors.
• Unit, functional, and Playwright validation paths.
• Manual validation needs.

Do not start cross-domain design until UI notes are complete.

Phase 3 - Docs, skills, and workflow context

Read docs and repo instructions that describe the public surface or workflow being changed:

• .github/copilot-instructions.md
• .claude/skills/*/SKILL.md for skill conventions
• .github/instructions/docs.instructions.md for docs changes
• Relevant pages under docs/

Capture:

• Public documentation that must change with the implementation.
• Instruction files that should stay in sync.
• Skill or workflow conventions to preserve.