---
description: A meta-skill for KCC Greenfield resources that describes the steps we need to take to get them to be "production ready" direct controllers at v1alpha1 at least.
name: checklist-for-kind
schedule: never
mode: workflow
---

# Checklist for KCC Greenfield Resource Migration

This is a meta-skill describing the steps to migrate a KCC greenfield resource kind to a production-ready direct controller at `v1alpha1`.
Greenfield resources are API resources that have not yet been implemented in KCC, they can be part of a brand new API or new resources in an existing API. 
Compare to Brownfield resources which are already implemented in KCC.

Instead of doing the coding yourself under this skill, you will coordinate and orchestrate:
1. Planning the migration steps.
2. Opening GitHub issues for each step, labeling them with `overseer`, and leaving them unassigned (or assigning them to the current bot user).
3. Monitoring progress of the Pull Requests.
4. Opening subsequent issues once the prior steps are successfully completed.

> [!IMPORTANT]
> **Safety Guardrails (Strict Enforcement)**:
> - **Do NOT write code or create PRs directly**: You must **never** checkout code, write code, run builds/tests, commit changes, or run `gh pr create` to send/push PRs. Your role under this skill is strictly limited to planning, progress tracking, and orchestration. All code implementation, CI fixing, and triage work must be delegated to coder and reviewer bots by creating child issues or assigning PRs back to their author bots.
> - **Do NOT comment on child Pull Requests**: You must **never** comment directly on the child Pull Requests. The watch daemon will automatically monitor and handle PR review feedback and CI check failures. If you need to request action or re-trigger a run, do so only by assigning the PR to the PR author bot (using `gh pr edit <pr> --add-assignee <author>` or assigning via `gh` CLI). However, if the PR has the `overseer/giving-up` label, you MUST NOT assign the PR back to the bot, as this indicates the retry limit was reached and human OWNER intervention is required.
> - **Do NOT approve, LGTM, or label PRs**: You must **never** approve, LGTM, or add approval/merging labels (such as `lgtm`, `approved`, or `automerge`) to any Pull Requests. These actions require human OWNER review and approval.
> - **Do NOT work on closed Pull Requests**: If a PR is closed but not merged, dont assign bots to the PR.

## Journaling and Progress Tracking

To track the progress of each resource kind, maintain a journal file in `.agents/workflows/greenfield-checklist-for-kind/journal/{kind}.md` (using the CamelCase Kind name).

The journal should contain:
1. The current step of the migration.
2. A table tracking:
   * Step Number and Name
   * GitHub Issue link/number
   * GitHub Pull Request link/number
   * Status (e.g. `Open`, `PR Created`, `Merged`, `Completed`)
   * Date Started and Date Completed

Only proceed to the next step once the PR for the current step is merged successfully.

3. In addition to the local journal file, **update the parent issue description** (using the issue ID/number extracted from `${SESSION_ID#issue-}`) or fall back to updating a comment:
   * **Formatting the GitHub Description/Comment**: To keep the parent GitHub issue clean and avoid excessively chatty updates, the body posted to GitHub (description or comment) must **only** include the current step, the progress tracking table, and **at most the 3 most recent status update notes**. Do not include the entire historical list of check logs or updates under the table in the GitHub description/comment; all older history must remain in the local journal file on the branch only.
   * Edit/create the description or comment using the `gh` CLI:
     ```bash
     gh issue edit ${SESSION_ID#issue-} --body "<updated_body>"
     ```
     If editing the issue description fails (due to write permissions on public repositories), **fall back to updating a comment**:
     * Search the comments on the issue for an existing comment posted by yourself (check for author match with your GITHUB_USER_ID) that contains the text `Migration Progress`.
     * If such a comment exists, edit it with the updated progress using:
       ```bash
       gh issue comment edit <comment-id> --body "<updated_comment_body>"
       ```
     * If no such comment exists, create a new comment:
       ```bash
       gh issue comment create ${SESSION_ID#issue-} --body "<updated_comment_body>"
       ```
4. Once all steps of the migration for the resource kind are successfully completed and verified merged, update the parent issue description to show completion, and close the parent issue:
   ```bash
   gh issue close ${SESSION_ID#issue-}
   ```

### Verifying PR CI Checks Status
When checking if all CI check-runs have passed for a pull request, do NOT rely on a single unpaginated `gh api .../check-runs` call (since GitHub defaults to 30 items per page and might hide failing runs). Instead, use the `--paginate` option to ensure all runs are checked:
```bash
gh api repos/GoogleCloudPlatform/k8s-config-connector/commits/<head-sha>/check-runs --paginate --jq '.check_runs[] | select(.conclusion != "success" and .conclusion != "neutral" and .conclusion != "skipped") | {name: .name, conclusion: .conclusion}'
```
Or check via GitHub CLI:
```bash
gh pr checks <pr-number> --repo GoogleCloudPlatform/k8s-config-connector
```
Only declare the PR as fully passed/verified if no failures are returned across all pages of checks.

## Steps


### Step 1: Direct API Types and Identity and Reference Types Pattern

Open a GitHub issue to coordinate the implementation of direct KRM types, identity files, and reference files for a specific Kubernetes resource.

**GitHub Issue Details for Greenfield Resource:**
*   **Title:** `Greenfield: Implement direct KRM types, identity, and generate.sh for {kind}`
*   **Assignee:** (leave unassigned or assign to the current bot)
*   **Labels:** `overseer`, `greenfield`,`step/gen-types`
*   **Body:**
    ```
    Please follow the skill `.gemini/skills/kcc-direct-greenfield-types-implementer/SKILL.md` for generating types for {kind}.
    Please follow the skill `.gemini/skills/kcc-identity-reference/SKILL.md` for generating identity for {kind}.

    Validate your changes locally by:
     * Running scripts/validate-prereqs.sh, if the script fails the output will contain agent hints for fixing the errors.
     * Running ./dev/ci/presubmits/tests-e2e-fixtures-<kind_lowercase>

    If you find any shortcomings in the skill (that likely apply to other resources), you may update SKILL.md. Also keep a journal of any less general observations etc. To avoid git merge conflicts, use a file under .gemini/skills/kcc-direct-greenfield-types-implementer/journal/, named after the kind or a similarly unique name. You may grep journal entries to identify learnings from other resources; if you find an important pattern by doing that you may also update the SKILL.md itself.
    ```

### Step 2: Direct Controller, E2E fixtures and Fuzzer

Open a GitHub issue to coordinate the implementation of the direct controller and E2E fixtures for a specific Kubernetes resource.

**GitHub Issue Details:**
*   **Title:** `Greenfield: Implement direct controller, E2E fixtures, and fuzzer for {kind}`
*   **Assignee:** (leave unassigned or assign to the current bot)
*   **Labels:** `overseer`, `greenfield`, `step/controller`
*   **Body:**
    ```
    Please follow the skills:
    - .gemini/skills/kcc-direct-controller-implementer/SKILL.md
    - .gemini/skills/kcc-direct-controller-logic-implementer/SKILL.md
    to implement the direct controller and record/verify E2E fixtures for {kind}.

    The direct controller must be implemented to manage reconciliation logic (Adapter: Find, Create, Update, Delete) and E2E fixtures must be created and recorded against real GCP to verify functionality.

    If you find any shortcomings in these skills (that likely apply to other resources), you may update them. Also keep a journal of any less general observations etc. To avoid git merge conflicts, use a file under their respective journal/ folders, named after the kind or a similarly unique name.
    ```

### Step 3: mockGCP generation

Open a GitHub issue to coordinate the implementation of the mockGCP for a specific Kubernetes resource.

**GitHub Issue Details for Greenfield Resource:**
*   **Title:** `Greenfield: Implement MockGCP and Alignment for {kind}`
*   **Assignee:** (leave unassigned or assign to the current bot)
*   **Labels:** `overseer`, `greenfield`,`step/mockgcp`
*   **Body:**
    ```
    Please follow the skill `.gemini/skills/kcc-direct-mockgcp-implementer/SKILL.md` to implement Phase 3 (MockGCP and Alignment) for {kind} to verify behavioral correctness against the simulated GCP services.
    ```

### Step 4: MockGCP Alignment with RealGCP

Open a GitHub issue to coordinate the alignment of MockGCP logs with RealGCP output to ensure high fidelity.

**GitHub Issue Details:**
*   **Title:** `Greenfield: Align MockGCP logs with RealGCP for {kind}`
*   **Assignee:** (leave unassigned or assign to the current bot)
*   **Labels:** `overseer`, `greenfield`, `step/mockgcp-alignment`
*   **Body:**
    ```
    Please follow the skill `.gemini/skills/match-mockgcp-with-realgcp/SKILL.md` to align the MockGCP logs with the RealGCP output for {kind}.
    ```