kovagoadi/hunfabric
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add FAST Prerequisites Skill and Gemini Skill Test Harness (#3979)

Browse Source 
* initial version of a FAST pre-install skill

* first round of testing

* Update fast-0-org-setup-prereqs skill with improved UX and local path handling

- Add explicit lockout warning and stop condition if the user is not a member of the provided Admin Principal group.
- Streamline bootstrap project selection to only prompt for an override if the active gcloud project is rejected.
- Restrict dataset discovery strictly to the `fast/stages/0-org-setup/datasets/` directory.
- Improve location handling by referencing `defaults.schema.json` for Standard GCP and auto-configuring fixed regions for GCD.
- Add comprehensive `local_path` management: prompt for customization, create directories, move `defaults.yaml` to the local data folder, and symlink `0-org-setup.auto.tfvars` back to the stage directory.

* add testing scenarios, implement initial changes for scenario 2

* move skills

* move to a skills/fast subfolder

* Refactor fast-0-org-setup prereqs skill

* Add skill-turn-harness utility tool

* Use relative markdown links for skill references

* Use descriptive titles for markdown links in skill references

* Add descriptions to each phase in the prerequisites workflow map

* Use backslash for markdown line breaks in skill map

* Update README security warning to mention default .gitignore

* shebang

* Update fast prereqs skill rules to force sequential question flow and refine harness tool with proper ctrl+c handling and slugified log paths

* Move playbook-gcp-dev.yaml to fast/prerequisites/gcp-dev.yaml and update fast prerequisites

* docs(skill-turn-harness): detail autonomous pond testing approach

* docs(skill-turn-harness): add final_state_checks to pond architecture and update toc

* Refine fast prereqs SKILL and gcp-dev playbook to strictly align with one-question-at-a-time rule

* feat(skill-turn-harness): update playbook schema for autonomous persona mode

* feat(skill-turn-harness): implement autonomous persona testing mode and fallback logic

* docs(skill-turn-harness): document the three modes of testing and update ToC

* implement timeout, schema validation, configurable cli

* chore: remove accidentally committed log files

* chore: ignore logs directory

* feat(skill-harness): implement tool execution interception, configurable workspace, and modularized validation

* feat(skill-harness): add model configuration and update README

* fix(skill-harness): automatically inject -y flag to gemini commands

* docs(skill-harness): add TODO.md with analysis for skill environment dependencies

* feat(skill-harness): add working_dir support and clean up fixtures

- Implement working_dir in harness to run tests in specific directories.
- Rename test fixtures and playbooks to be more descriptive.
- Add E2E test for working_dir.
- Apply code quality improvements to harness.py (imports, linting).
- Update README with working directory considerations and usage notes.
- Update phase3-bootstrap-and-iam.md skill doc to add execution rule against creating temp scripts.

* fix: capture customer_id and respect relative paths

* Implement isolated temp workspace sandboxing with symlinks in test harness

* Configure GCD manual autonomous playbook and align Phase 3/4 steps order

* Fix linting and schema tests failures

- Add missing license headers to tools/skill-turn-harness files.

- Fix trailing spaces and newlines in playbooks.

- Ignore tools directory in schema tests workflow.

TAG=agy

CONV=1bb75453-c3e2-448b-bae9-8e332a068012

* Fix Python formatting with yapf

TAG=agy

CONV=1bb75453-c3e2-448b-bae9-8e332a068012

* Refactor skill-turn-harness to use Antigravity SDK

- Migrated harness from gemini-cli subprocesses to Antigravity SDK.
- Implemented real-time step streaming and console logging.
- Added color-coded terminal output (dark gray headers, blue inputs, pink outputs).
- Collapsed excessive newlines in streamed thoughts.
- Excluded harness codebase from workspace copy to prevent agent cheating.
- Enabled skills folder copy to resolve agent lookup loops.
- Added key validation and CLI --debug flag.

* Fix autonomous turn layout: print Turn ID before execution

- Moved the [Autonomous Turn X] header print to before running the agent turn.
- This groups the real-time thinking and tool calls under the correct Turn ID block, instead of displaying them before the label.

* Remove obsolete .log.md from prerequisites skill directory
This commit is contained in:
Ludovico Magnocavallo
2026-05-22 19:16:54 +02:00
committed by GitHub
parent 1594a01c6f
commit 81f72e8068
32 changed files with 2653 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
skills/fast/prerequisites/SKILL.md Normal file
View File

@@ -0,0 +1,54 @@
---
name: fast-0-org-setup-prereqs
description: Guides the user step-by-step through the prerequisites for the FAST 0-org-setup stage, supporting both Standard GCP and Google Cloud Dedicated (GCD) environments. Use when a user asks to prepare or run prerequisites for 0-org-setup or bootstrap the FAST landing zone.
---
# FAST 0-org-setup Prerequisites Guide
## Core Principles & Execution Rules
> [!CRITICAL]
> **Understanding Turn Boundaries:** You are running in a turn-based execution environment.
> - You receive one user message, then you can think and run tools.
> - Once you decide you need input from the user (e.g. to choose an environment or confirm a principal), you MUST output your question in a text response and **STOP execution immediately (do not call more tools)**.
> - You **CANNOT** receive the user's answer in the same turn.
> - You **MUST NOT** simulate, guess, or assume the user's response in your subsequent thinking blocks during the same turn. You must wait for the next turn to receive the actual input.
>
> **Do NOT Skip Steps or Make Assumptions:** You MUST NOT skip any phases or steps, even if you think they are redundant or if you find information on the system (like active credentials) that suggests a step is already complete. You MUST execute every step sequentially, in order, and wait for explicit user input/confirmation at each step boundary.
>
> **Strictly One Question at a Time:** You MUST NOT bundle multiple questions or steps together in a single response. Ask exactly one question, wait for the user's answer, and only then proceed to the next question or action.
>
> **Step-by-Step Execution:** Never implement a single "magical" flow. Go through each step one at a time, explaining context and asking for confirmation.
3. **Execution Choice:** Respect the user's execution preference (automatic via `run_shell_command` vs. manual copy/paste) throughout the entire workflow unless the user explicitly instructs you to change it. This preference will be gathered during Phase 1.
4. **File Modifications:** Always use `replace` or `write_file`. **Never** use opaque shell commands (like `sed`, `echo >>`, or `cat <<EOF >>`). Show proposed edits and ask for confirmation before applying them so the user can see what we're doing.
5. **YAML Validation:** Validate generated YAML using `yamllint -c .yamllint --no-warnings <file>`. If the command is not available, ask the user if they prefer to a) install it, b) have you install it (`pip install yamllint`), or c) skip validation.
6. **Resuming Mid-Flow:** If the user is resuming a previously interrupted session, ask them which Phase or Step they left off at, or assess the current state by reading previously generated files (e.g., `defaults.yaml`, `0-org-setup.auto.tfvars`). Read the corresponding reference file for the identified phase and resume execution directly from that point.
## Workflow Map
Guide the user through the following sequence strictly in order. **Before starting a phase, read its corresponding reference document to get the exact instructions, commands, and logic.**
### Phase 1: Environment & Authentication
*Description:* Determine the target environment (Standard GCP or GCD) and ensure the user is properly authenticated.\
*Reference: [Environment & Authentication](references/phase1-env-and-auth.md)*
- **Step 1:** Environment Assessment & Initialization (Standard vs GCD)
- **Step 2:** Authentication
### Phase 2: Admin Principal & Baseline Info
*Description:* Define the core administrative identity and gather essential baseline data like Organization and Billing IDs.\
*Reference: [Admin Principal & Baseline Info](references/phase2-admin-and-baseline.md)*
- **Step 3:** Admin Principal Definition (Group vs Single User)
- **Step 4:** Baseline Information Gathering (Org ID, Billing ID, Billing Access Scenarios)
### Phase 3: Bootstrap Project & IAM
*Description:* Assign the necessary organization-level IAM roles and set up a temporary project for API quota tracking.\
*Reference: [Bootstrap Project & IAM](references/phase3-bootstrap-and-iam.md)*
- **Step 5:** IAM Role Assignments
- **Step 6:** Bootstrap Project Setup (Creation and API enablement)
### Phase 4: Configuration & Wrap-up
*Description:* Generate the FAST dataset configuration, handle existing organization policies, and prepare for the final Terraform apply.\
*Reference: [Configuration & Wrap-up](references/phase4-config-and-wrapup.md)*
- **Step 7:** Configuration Generation (Datasets, defaults.yaml, local paths)
- **Step 8:** Organization Policy Import Check
- **Step 9:** Wrap-up & Apply

67
skills/fast/prerequisites/TESTING.md Normal file
View File

@@ -0,0 +1,67 @@
# FAST 0-org-setup Prerequisites - Testing Workflows
This document outlines the various testing workflows and combinations for the `fast-0-org-setup-prereqs` skill to ensure all branches of the skill's logic are covered.
## Core Variables & Decision Points
1. **Environment:** Standard GCP vs. Google Cloud Dedicated (GCD)
2. **GCD Universe (if applicable):** S3NS (France), Berlin (Germany), or Custom
3. **Execution Mode:** Auto (Gemini CLI runs commands) vs. Manual (Output commands for user)
4. **Authentication State:** Already authenticated vs. Needs authentication
5. **Admin Principal Approach:** Group (Approach A) vs. Single User (Approach B)
6. **Billing Account Access Level:** Billing Administrator vs. Billing User vs. No Access
7. **Bootstrap Project:** Pre-existing (with or without API check) vs. New project created by user
8. **Configuration / Dataset:** Standard GCP datasets vs. `classic-gcd` dataset
9. **Org Policy Import Check:** Pre-existing policies found vs. No policies found
## Comprehensive Test Scenarios
### Scenario 1: Standard GCP - The "Simple User" Flow
* **Environment:** Standard GCP
* **Execution Mode:** Manual
* **Authentication:** Needs authentication (Standard auth flow)
* **Admin Principal:** Single User (current authenticated user)
* **Information Gathering:** Direct input of Org ID and Billing ID
* **Billing Access:** Billing Administrator
* **Bootstrap Project:** New project (user creates, CLI outputs full API enable command)
* **Configuration:** Default local path, standard dataset, additional context added
* **Org Policies:** Some policies exist (to test tfvars update)
### Scenario 2: Standard GCP - The "Developer" Flow
* **Environment:** Standard GCP
* **Execution Mode:** Auto
* **Authentication:** Already authenticated
* **Admin Principal:** Group (`foo-owners@example.com`)
* **Information Gathering:** Uses "list" to fetch Org ID and Billing ID
* **Billing Access:** Billing User (requires disabling billing YAML)
* **Bootstrap Project:** Pre-existing project (auto-check and enable missing APIs)
* **Configuration:** Custom local path, standard dataset, no additional context
* **Org Policies:** Some policies exist (to test tfvars update)
#### Notes
### Scenario 3: GCD (S3NS) - Automated Setup
* **Environment:** Google Cloud Dedicated (GCD)
* **Universe:** S3NS (France)
* **Execution Mode:** Auto
* **Authentication:** Needs authentication (WIF login flow)
* **Admin Principal:** Group
* **Billing Access:** Billing Administrator
* **Bootstrap Project:** Pre-existing project (skip API check, enable all)
* **Configuration:** `classic-gcd` dataset (fixed), auto-mapped universe regions, providers.tf generated
* **Org Policies:** No policies exist
### Scenario 4: GCD (Custom) - Manual Setup with Restrictions
* **Environment:** Google Cloud Dedicated (GCD)
* **Universe:** Custom (manually input all 5 variables)
* **Execution Mode:** Manual
* **Authentication:** Already authenticated
* **Admin Principal:** Single User
* **Billing Access:** No Access (requires warning and manual continuation)
* **Bootstrap Project:** New project
* **Configuration:** `classic-gcd` dataset, custom local path
* **Org Policies:** Some policies exist

56
skills/fast/prerequisites/references/phase1-env-and-auth.md Normal file
View File

@@ -0,0 +1,56 @@
# Phase 1: Environment & Authentication
### Step 1: Environment Assessment & Initialization
> [!IMPORTANT]
> **Do NOT Automate Environment Choice**: You MUST explicitly ask the user to clarify their target environment (Standard GCP or GCD) and wait for their response. Do NOT assume or guess based on local config files or active credentials.
>
> **Do NOT Automate Command Execution Preference**: You MUST ask how they prefer to run commands (automatic vs manual) and wait for their response.
1. Ask the user to clarify their target environment: **Standard GCP** or **Google Cloud Dedicated (GCD)**. **Wait for their response.**
2. Once the environment is confirmed, ask how they prefer to run commands: Should you (Gemini CLI) run them automatically, or should you output them for manual execution? **Remember this preference for the rest of the workflow. Wait for their response.**
3. *If GCD is selected*, ask the user if they are working in one of the known universes: **S3NS (France)** or **Berlin (Germany)**.
- *If S3NS:* Pre-fill the following values:
- Universe Web Domain: `cloud.s3nscloud.fr`
- Universe API Domain: `s3nsapis.fr`
- Universe Name: `s3ns`
- Universe Prefix: `s3ns`
- Universe Region: `u-france-east1`
- *If Berlin:* Pre-fill the following values:
- Universe Web Domain: `cloud.berlin-build0.goog`
- Universe API Domain: `apis-berlin-build0.goog`
- Universe Name: `berlin`
- Universe Prefix: `eu0`
- Universe Region: `u-germany-northeast1`
- *If neither (Custom):* Gather the 5 universe-specific details manually from the user.
- *Action:* Present the final list of the 5 universe values to the user for review. Ask for explicit confirmation and offer them the opportunity to change any of the values before proceeding.
### Step 2: Authentication
1. Ask the user if they are already authenticated with Google Cloud using the correct principal.
- *If yes:* Run (or ask the user to run) `gcloud config list account --format="value(core.account)"` to retrieve the current authenticated principal. Show this principal to the user and explicitly ask them to confirm if this is the correct identity they want to use.
- *If they confirm:* Proceed directly to Phase 2 (Step 3).
- *If they do not confirm:* Proceed with the authentication steps below.
- *If no:* Proceed with the authentication steps below.
2. *Standard GCP:* Provide or execute the command:
```bash
gcloud auth login
gcloud auth application-default login
```
3. *GCD:* Automate or guide the user through WIF login. Ask for the workforce pool audience string first, then generate the configuration:
```bash
# (Use the gathered GCD variables to fill placeholders)
gcloud config configurations create <UNIVERSE_NAME>
gcloud config configurations activate <UNIVERSE_NAME>
gcloud config set universe_domain <UNIVERSE_API_DOMAIN>
gcloud iam workforce-pools create-login-config <AUDIENCE> \
--universe-cloud-web-domain="<UNIVERSE_WEB_DOMAIN>" \
--universe-domain="<UNIVERSE_API_DOMAIN>" \
--output-file="/tmp/wif-login-config-<UNIVERSE_NAME>.json" \
--activate
gcloud auth login --login-config=/tmp/wif-login-config-<UNIVERSE_NAME>.json --no-launch-browser
gcloud auth application-default login --login-config=/tmp/wif-login-config-<UNIVERSE_NAME>.json
```
4. Explicitly ask the user to confirm they have successfully authenticated before moving to the next phase.

35
skills/fast/prerequisites/references/phase2-admin-and-baseline.md Normal file
View File

@@ -0,0 +1,35 @@
# Phase 2: Admin Principal & Baseline Info
### Step 3: Admin Principal Definition
1. Explain the concept of the **Admin Principal**. This is the identity (or group of identities) that will be granted the necessary FAST roles to deploy the foundation and manage critical organization-level configurations and policies thereafter.
2. Determine the Admin Principal approach by asking the user to choose between two options:
- **Approach A (Preferred): Use a pre-created Group.**
- *Action:* Explain that using a group (e.g., `group:gcp-organization-admins@example.com`) is the standard and preferred way. **Crucially, clarify that the group provided MUST be a group that the user's current authenticated identity belongs to**, otherwise they will lock themselves out.
- *Action:* Ask the user to provide the group email address.
- *Action:* Explicitly ask the user to confirm that their current identity (the one they just authenticated with) is already a member of this group.
- *Action:* If the user answers "No" to the membership confirmation, **DO NOT PROCEED**. Inform the user that proceeding will lock them out. Ask them to either authenticate with an identity that *is* a member of the group (and restart the authentication step), or provide a different group that their current identity belongs to.
- **Approach B (Fallback): Use a Single User.**
- *Action:* Explain that this flow uses a single user as the sole GCP Org Admin, but more can be added later.
- *Action:* Run (or ask the user to run) `gcloud config list account --format="value(core.account)"` to retrieve their current authenticated principal.
- *Action:* Show the user their current principal and explicitly ask them to confirm this is the identity they want to use as the Admin Principal.
### Step 4: Baseline Information Gathering
1. Gather baseline information required for `0-org-setup`:
- Organization ID (and the associated Directory Customer ID, which is important for Standard GCP but not required for GCD)
- Billing Account ID (Mandatory for subsequent stages, even if not required for the GCD temporary project)
*Action:* When prompting the user for the Organization ID and Billing Account ID, explicitly instruct them in the prompt/question that they can leave the field blank (or type "list") to have you automatically run the relevant `gcloud` command (`gcloud organizations list --format="json"` or `gcloud beta billing accounts list`). Also, instruct them that they can type a keyword to filter the list.
*Action:* If the user leaves the field blank or types "list", run the `gcloud` command without filters. If the user types a keyword that is not a valid Organization ID (numeric) or Billing Account ID (e.g., `012345-6789AB-CDEF01`), run the `gcloud` command and use that keyword to filter the results using a **case-insensitive** regex match. Ensure the regex pattern is enclosed in single quotes within the filter argument (e.g., `--filter="displayName~'(?i)KEYWORD'"`). Do NOT use `*` wildcards in the filter.
*Action:* If the filtered `gcloud` command returns no results, inform the user and use the `ask_user` tool to ask if they want to provide a different keyword or fetch all items (run without a filter).
*Action:* Once you have results for Organizations (filtered or unfiltered), extract the Organization ID, the Display Name (domain), and the Directory Customer ID (found in `owner.directoryCustomerId` in the JSON output). Sort them alphabetically by the display name, and then output the sorted results as a clearly formatted numbered list in the chat. Then, use the `ask_user` tool (type: text) to ask the user to enter the number corresponding to their selection. Note the Organization ID, Domain, and Customer ID for Phase 4. For Billing Accounts, do the same sorting and prompting.
2. Determine the **Admin Principal's** access level to the provided Billing Account ID. Ask which of the following three scenarios applies to the Admin Principal (not necessarily the current user):
- **Scenario 1 (Billing Administrator):** The Admin Principal has `roles/billing.admin`.
- *Action:* Ask a follow-up question: "Is your billing account managed by the same organization where we are installing FAST, or outside of it? (You can check this in the Google Cloud Console by going to Billing -> using the organization picker on top -> checking if the account is listed under this organization)."
- *If Inside the Org:* Note that `roles/billing.admin` WILL be assigned at the Organization level in Step 6. Instruct the user that we will deactivate the billing factories path for now, but if account-level IAM also needs to be managed via FAST later, they can reactivate the path and use the billing YAML to do it.
- *If Outside the Org:* Note that `roles/billing.admin` WILL NOT be assigned at the Organization level in Step 6.
- **Scenario 2 (Billing User):** The Admin Principal has `roles/billing.user` but NOT admin rights.
- *Action:* Note that `roles/billing.admin` WILL NOT be assigned at the Organization level in Step 6. Either disable the billing YAML via the `factories_config` variable or comment it out, since the Admin Principal cannot control IAM on the account.
- *Action:* **Explain to the user:** The service accounts for IaC (and therefore the provider switch and subsequent stages, except for VPC-SC) will not be operative until the correct billing permissions have been assigned to them outside of FAST.
- **Scenario 3 (No Access):** The Admin Principal has absolutely no rights on the billing account.
- *Action:* **Clearly state:** This scenario is mostly used for development purposes, is strongly discouraged, and requires advanced Terraform skills and FAST knowledge to proceed.

43
skills/fast/prerequisites/references/phase3-bootstrap-and-iam.md Normal file
View File

@@ -0,0 +1,43 @@
# Phase 3: Bootstrap Project & IAM
### Step 5: IAM Role Assignments
1. Grant the following roles to the chosen Admin Principal at the Organization level. **CRITICAL:** Only include `roles/billing.admin` in this list if the user selected Scenario 1 (Billing Administrator) AND confirmed the billing account is managed Inside the Organization in Step 4.
**CRITICAL EXECUTION RULE:** Do NOT create temporary bash scripts (e.g., `assign_roles.sh`) to execute this loop. You MUST execute the `for` loop inline directly using the `run_shell_command` tool, or output the exact inline loop for the user to copy/paste.
```bash
# Roles to assign:
# [roles/billing.admin] <-- CONDITIONAL (See above)
# roles/logging.admin
# roles/iam.organizationRoleAdmin
# roles/orgpolicy.policyAdmin
# roles/resourcemanager.folderAdmin
# roles/resourcemanager.organizationAdmin
# roles/resourcemanager.projectCreator
# roles/resourcemanager.tagAdmin
# roles/owner
# Loop example for the user or tool execution:
for role in [ROLES_LIST]; do
gcloud organizations add-iam-policy-binding <ORG_ID> \
--member="<ADMIN_PRINCIPAL>" --role="$role" --condition=None
done
```
### Step 6: Bootstrap Project Setup
1. Explain that a temporary bootstrap project is required to track API quota before organization policies are fully established.
2. Ask the user if they already have a suitable project they can use for this purpose.
- *If yes:* Ask if this project is already configured as the active project in `gcloud`. If the user does not know, run `gcloud config list project --format="value(core.project)"` to check for them.
- If it is already configured, fetch the Project ID using `gcloud config list project --format="value(core.project)"`. Explicitly ask the user to confirm if this fetched Project ID is the one they want to use. **Only if they answer "No" to this confirmation**, ask them to provide the correct Project ID.
- If it is not configured, ask the user to provide the Project ID.
- *If no:* Ask the user to use the Cloud Console to create a temporary project (must be linked to the billing account). Ask them to provide the new Project ID once created.
3. Once the Project ID is provided or fetched, ensure it is set as the default project. If it is not already set, run:
```bash
gcloud config set project <TEMP_PROJECT_ID>
```
4. Enable the required baseline APIs on the project:
- The required APIs are: `bigquery.googleapis.com`, `cloudbilling.googleapis.com`, `cloudresourcemanager.googleapis.com`, `essentialcontacts.googleapis.com`, `iam.googleapis.com`, `logging.googleapis.com`, `orgpolicy.googleapis.com`, `serviceusage.googleapis.com`.
- *If the project was pre-existing:* Ask the user if they want you to check which services are already enabled.
- *If yes:* Run `gcloud services list --enabled --format="value(config.name)"` to get the current list. Compute the delta between the enabled services and the required list. Only run `gcloud services enable <MISSING_APIS>` for the ones that are missing.
- *If no:* Run the full `gcloud services enable` command for all required APIs.
- *If the project is new:* Run the full `gcloud services enable` command for all required APIs.

54
skills/fast/prerequisites/references/phase4-config-and-wrapup.md Normal file
View File

@@ -0,0 +1,54 @@
# Phase 4: Configuration & Wrap-up
### Step 7: Configuration Generation
1. **Explain Datasets:** Briefly explain to the user that FAST uses "datasets" (collections of YAML files) that fully describe the design, architecture, resources, and policies applied.
2. **Select the Dataset:** Ask the user to select the dataset they want to use for their landing zone design.
- *If GCD:* Explicitly state that the `classic-gcd` dataset must be used for GCD installations.
- *If Standard GCP:* Offer the available datasets and ask them to choose one. **Crucially, only search for available datasets within the `fast/stages/0-org-setup/datasets/` directory.** Do not search across the entire repository or other FAST stages. Provide a one-line description below each dataset when presenting the options (e.g., "classic: The standard FAST landing zone architecture", "hardened: A more restrictive, hardened landing zone architecture").
3. **Explain Defaults Configuration:** Explain to the user that we are starting the configuration of the `defaults.yaml` file, which drives the static configuration of the dataset by providing the Org ID, Billing ID, user-specified locations, and any static values they need to bring in from the outside (like additional IAM principals used in the YAML files to assign IAM roles).
4. **Determine Locations:** FAST uses a set of locations for different services.
- *If GCD:* The region is fixed based on the universe selected in Phase 1. Set the `logging` location to `global` and all other required locations to the Universe Region. Do not ask the user to choose; simply show them the configured locations.
- *If Standard GCP:* Check the `fast/stages/0-org-setup/schemas/defaults.schema.json` to identify the required location keys (e.g., `bq`, `gcs`, `logging`, `pubsub`). First, ask the user to provide a "base location" (e.g., `europe-west1`), explaining that submitting without answering will confirm the default value. Even if the user confirms the base location, you must then ask if they need to override the location for any individual services.
5. **Determine Local Path:** Explain to the user that FAST generates provider configurations and other files that need to be stored outside the repository. This is defined by the `output_files.local_path` setting. Propose a default path based on the chosen prefix (e.g., `~/fast-config/<prefix>`) and ask the user to confirm or provide a different path. **Crucially, if the user provides a relative path (e.g., `custom-fast-config` or `./custom-fast-config`), use it exactly as provided relative to the current working directory. Do not automatically prepend `~/` to their input.** Once confirmed, create this directory using `mkdir -p <LOCAL_PATH>`.
6. **Ask for Additional Context:** Ask the user if there are any other static values they want to bring in from outside to be referenced in the YAML files. Show them the available context keys (excluding `condition_vars`). Provide examples showing that prefixes are mandatory for IAM principals (e.g., `user:foo@example.com`, `group:bar@example.com`). For GCD, also show a `principalSet:` example. **Do not use shell commands like `echo` or `cat` to show this list; output it directly in your chat message or the `ask_user` prompt.**
7. **Create Local Directories and Copy Defaults:**
- Create the `data/0-org-setup/` and `providers/` directories inside the confirmed `local_path` (`mkdir -p <LOCAL_PATH>/data/0-org-setup/ <LOCAL_PATH>/providers/`).
- **Copy** (do not move) the `defaults.yaml` from the chosen dataset folder to `<LOCAL_PATH>/data/0-org-setup/defaults.yaml` using `cp`.
8. **Edit the Copied Defaults File:** Use the `replace` tool to edit the *copied* `<LOCAL_PATH>/data/0-org-setup/defaults.yaml` file.
- Populate `global.billing_account`, `global.organization.id`, `global.organization.domain`, and `global.organization.customer_id` (using the values gathered in Phase 2). Note that `customer_id` may not be present for GCD.
- Populate `context.iam_principals.gcp-organization-admins` (using the Admin Principal determined in Phase 2).
- Populate the service-specific locations gathered in the previous step into the `context.locations` block and map them appropriately in `projects.defaults.locations`.
- Populate `output_files.local_path` with the confirmed path.
- If additional context was provided, add it to the `context` block.
- *If GCD*, ensure the `overrides.universe` block is present with `domain`, `prefix`, and specific identity overrides.
9. Run YAML validation: `yamllint -c .yamllint --no-warnings <LOCAL_PATH>/data/0-org-setup/defaults.yaml`. Handle missing tool errors as described in the Core Principles.
10. **Create Configuration Files:**
- Use `write_file` to create `0-org-setup.auto.tfvars` inside the `local_path` (`<LOCAL_PATH>/0-org-setup.auto.tfvars`).
- In `0-org-setup.auto.tfvars`, set the `factories_config` variable. The `dataset` should point to the original dataset folder (e.g., `"datasets/classic"`), but the `paths.defaults` must point to the absolute path of the copied defaults file.
- *If GCD*, also: Create a temporary `0-org-setup-providers.tf` file containing the specific `universe_domain` configuration using `write_file` at `<LOCAL_PATH>/providers/0-org-setup-providers.tf`.
### Step 8: Organization Policy Import Check
1. Explain that pre-existing organization policies can cause `409 Conflict` errors during the first apply if not imported.
2. Execute (or provide) the command to list current policies.
```bash
gcloud org-policies list --organization="<ORG_ID>" --format="value(constraint)"
```
3. **Update `0-org-setup.auto.tfvars`:** If any policies are returned, capture the output, format it as an HCL list in memory, and use the `replace` tool to append the `org_policies_imports` variable to the `0-org-setup.auto.tfvars` file. **ABSOLUTELY NEVER use shell redirection like `echo >>`, `awk >>`, or `cat <<EOF >>` to edit files.** Explain to the user that this tells Terraform to import these existing policies rather than attempting to recreate them.
### Step 9: Wrap-up & Apply
1. **Link Configuration:** Instruct the user to link the final configuration files to the stage directory using the `fast-links.sh` script. They should navigate to `fast/stages/0-org-setup/` and run:
```bash
../../fast-links.sh <LOCAL_PATH>
```
Explain that they should then copy and run the commands printed by the script to create the links.
**Note:** If they are not on GCD, they can ignore the provider file linking command printed by the script for the first run.
2. Remind the user that the prerequisite phase is complete.
3. Instruct them to run `terraform init` and `terraform apply`.
4. Remind them to delete the temporary project and reset their gcloud default project to `iac-0` after a successful apply. Provide the exact commands for them to copy and use later:
```bash
gcloud projects delete <TEMP_PROJECT_ID>
gcloud config set project <IAC_PROJECT_ID>
```