diff --git a/commands/conductor/newTrack.toml b/commands/conductor/newTrack.toml index af631fe5..13adf31e 100644 --- a/commands/conductor/newTrack.toml +++ b/commands/conductor/newTrack.toml @@ -109,6 +109,24 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai > "Does this plan look correct and cover all the necessary steps based on the spec and our workflow? Please suggest any changes or confirm." Await user feedback and revise the `plan.md` content until confirmed. +### 2.3.1 Platform Guide Check (GCP) + +1. **Analyze Context:** + * Check if the **Specification** or **Implementation Plan** mentions "GCP", "Google Cloud", "Cloud Run", "GKE", "App Engine", "Firebase", "BigQuery", "Cloud Storage", "GCS", "Cloud SQL", or any other Google Cloud service. + * Check for the existence of `conductor/platform_guides/google-cloud-platform.md`. + +2. **Conditional Offer:** + * **IF** (GCP, Google Cloud, or any related service is mentioned) **AND** (the guide is MISSING): + * Ask the user: + > "I noticed this track involves Google Cloud Platform, but the GCP Best Practices guide is missing from your project. Would you like to add it now? + > A. Yes, add the guide. + > B. No, skip for now. + > Please enter your choice (A or B)." + * **If 'A' (Yes):** + * Create the directory `conductor/platform_guides/`. + * Copy `~/.gemini/extensions/conductor/templates/platform_guides/google-cloud-platform.md` to `conductor/platform_guides/google-cloud-platform.md`. + * Announce: "Added GCP Best Practices guide to `conductor/platform_guides/`." + ### 2.4 Create Track Artifacts and Update Main Plan 1. **Check for existing track name:** Before generating a new Track ID, resolve the **Tracks Directory** using the **Universal File Resolution Protocol**. List all existing track directories in that resolved path. Extract the short names from these track IDs (e.g., ``shortname_YYYYMMDD`` -> `shortname`). If the proposed short name for the new track (derived from the initial description) matches an existing short name, halt the `newTrack` creation. Explain that a track with that name already exists and suggest choosing a different name or resuming the existing track. diff --git a/commands/conductor/review.toml b/commands/conductor/review.toml index 17304f12..cd9fc15e 100644 --- a/commands/conductor/review.toml +++ b/commands/conductor/review.toml @@ -50,6 +50,8 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai - Read `product-guidelines.md` and `tech-stack.md`. - **CRITICAL:** Check for the existence of `conductor/code_styleguides/` directory. - If it exists, list and read ALL `.md` files within it. These are the **Law**. Violations here are **High** severity. + - **CRITICAL:** Check for the existence of `conductor/platform_guides/` directory. + - If it exists, list and read ALL `.md` files within it. Ensure code adheres to these platform best practices. 2. **Load Track Context (if reviewing a track):** - Read the track's `plan.md`. - **Extract Commits:** Parse `plan.md` to find recorded git commit hashes (usually in the "Completed" tasks or "History" section). @@ -73,13 +75,16 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai **Perform the following checks on the retrieved diff:** 1. **Intent Verification:** Does the code actually implement what the `plan.md` (and `spec.md` if available) asked for? -2. **Style Compliance:** +2. **Product Guidelines Compliance:** - Does it follow `product-guidelines.md`? +3. **Code Style Compliance:** - Does it strictly follow `conductor/code_styleguides/*.md`? -3. **Correctness & Safety:** +4. **Platform Guide Compliance:** + - Does it adhere to `conductor/platform_guides/*.md` (if exists and is applicable)? +5. **Correctness & Safety:** - Look for bugs, race conditions, null pointer risks. - **Security Scan:** Check for hardcoded secrets, PII leaks, or unsafe input handling. -4. **Testing:** +6. **Testing:** - Are there new tests? - Do the changes look like they are covered by existing tests? - *Action:* **Execute the test suite automatically.** Infer the test command based on the codebase languages and structure (e.g., `npm test`, `pytest`, `go test`). Run it. Analyze the output for failures. @@ -94,7 +99,9 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai ## Verification Checks - [ ] **Plan Compliance**: [Yes/No/Partial] - [Comment] -- [ ] **Style Compliance**: [Pass/Fail] +- [ ] **Product Guidelines Compliance**: [Pass/Fail] +- [ ] **Code Style Compliance**: [Pass/Fail] +- [ ] **Platform Guide Compliance**: [Pass/Fail/NA] - [ ] **New Tests**: [Yes/No] - [ ] **Test Coverage**: [Yes/No/Partial] - [ ] **Test Results**: [Passed/Failed] - [Summary of failing tests or 'All passed'] diff --git a/commands/conductor/setup.toml b/commands/conductor/setup.toml index 2f6850c3..9f7537da 100644 --- a/commands/conductor/setup.toml +++ b/commands/conductor/setup.toml @@ -23,8 +23,9 @@ CRITICAL: When determining model complexity, ALWAYS select the "flash" model, re - If `STEP` is "2.1_product_guide", announce "Resuming setup: The Product Guide (`product.md`) is already complete. Next, we will create the Product Guidelines." and proceed to **Section 2.2**. - If `STEP` is "2.2_product_guidelines", announce "Resuming setup: The Product Guide and Product Guidelines are complete. Next, we will define the Technology Stack." and proceed to **Section 2.3**. - If `STEP` is "2.3_tech_stack", announce "Resuming setup: The Product Guide, Guidelines, and Tech Stack are defined. Next, we will select Code Styleguides." and proceed to **Section 2.4**. - - If `STEP` is "2.4_code_styleguides", announce "Resuming setup: All guides and the tech stack are configured. Next, we will define the project workflow." and proceed to **Section 2.5**. - - If `STEP` is "2.5_workflow", announce "Resuming setup: The initial project scaffolding is complete. Next, we will generate the first track." and proceed to **Phase 2 (3.0)**. + - If `STEP` is "2.4_code_styleguides", announce "Resuming setup: Code Styleguides are configured. Next, we will check for Platform Guides." and proceed to **Section 2.5**. + - If `STEP` is "2.5_platform_guides", announce "Resuming setup: Platform Guides are checked. Next, we will define the project workflow." and proceed to **Section 2.6**. + - If `STEP` is "2.6_workflow", announce "Resuming setup: The initial project scaffolding is complete. Next, we will generate the first track." and proceed to **Section 2.7**. - If `STEP` is "3.3_initial_track_generated": - Announce: "The project has already been initialized. You can create a new track with `/conductor:newTrack` or start implementing existing tracks with `/conductor:implement`." - Halt the `setup` process. @@ -94,6 +95,7 @@ CRITICAL: When determining model complexity, ALWAYS select the "flash" model, re - Programming Language - Frameworks (frontend and backend) - Database Drivers + - Cloud Providers (e.g., Google Cloud, AWS) 3. **Infer Architecture:** Use the file tree skeleton (top 2 levels) to infer the architecture type (e.g., Monorepo, Microservices, MVC). 4. **Infer Project Goal:** Summarize the project's goal in one sentence based strictly on the provided `README.md` header or `package.json` description. - **Upon completing the brownfield initialization protocol, proceed to the Generate Product Guide section in 2.1.** @@ -220,7 +222,7 @@ CRITICAL: When determining model complexity, ALWAYS select the "flash" model, re 2. **Ask Questions Sequentially:** Ask one question at a time. Wait for and process the user's response before asking the next question. Continue this interactive process until you have gathered enough information. - **CONSTRAINT:** Limit your inquiry to a maximum of 5 questions. - **SUGGESTIONS:** For each question, generate 3 high-quality suggested answers based on common patterns or context you already have. - - **Example Topics:** programming languages, frameworks, databases, etc + - **Example Topics:** programming languages, frameworks, databases, cloud providers (GCP, AWS, Azure), etc * **General Guidelines:** * **1. Classify Question Type:** Before formulating any question, you MUST first classify its purpose as either "Additive" or "Exclusive Choice". * Use **Additive** for brainstorming and defining scope (e.g., users, goals, features, project guidelines). These questions allow for multiple answers. @@ -272,8 +274,8 @@ CRITICAL: When determining model complexity, ALWAYS select the "flash" model, re `{"last_successful_step": "2.3_tech_stack"}` 8. **Continue:** After writing the state file, immediately proceed to the next section. -### 2.4 Select Guides (Interactive) -1. **Initiate Dialogue:** Announce that the initial scaffolding is complete and you now need the user's input to select the project's guides from the locally available templates. +### 2.4 Select Code Style Guides (Interactive) +1. **Initiate Dialogue:** Announce that the initial scaffolding is complete and you now need the user's input to select the project's CODE STYLE guides from the locally available templates. 2. **Select Code Style Guides:** - List the available style guides by running `ls ~/.gemini/extensions/conductor/templates/code_styleguides/`. - For new projects (greenfield): @@ -291,10 +293,27 @@ CRITICAL: When determining model complexity, ALWAYS select the "flash" model, re A) Yes, I want to proceed with the suggested code style guides. B) No, I want to add more code style guides. - **Action:** Construct and execute a command to create the directory and copy all selected files. For example: `mkdir -p conductor/code_styleguides && cp ~/.gemini/extensions/conductor/templates/code_styleguides/python.md ~/.gemini/extensions/conductor/templates/code_styleguides/javascript.md conductor/code_styleguides/` - - **Commit State:** Upon successful completion of the copy command, you MUST immediately write to `conductor/setup_state.json` with the exact content: + - **Commit State:** After handling the code style guides, you MUST immediately write to `conductor/setup_state.json` with the exact content: `{"last_successful_step": "2.4_code_styleguides"}` - -### 2.5 Select Workflow (Interactive) + - **Continue:** Proceed to the next section. + +### 2.5 Detect and Select Platform Guides (Interactive) +1. **Detect and Select Platform Guides (GCP):** + - **Check Context:** Analyze the `tech-stack.md` and `products.md` contents or the `setup` conversation history to check if Google Cloud Platform (GCP), Google Cloud, or related services are mentioned. + - **Conditional Logic:** + - **IF GCP DETECTED:** + - Announce: "I noticed this project involves Google Cloud Platform. I have a GCP Best Practices template available." + - Ask: "Would you like to include the GCP Best Practices guide?" + A) Yes, include it. + B) No, skip it. + - **If 'Yes':** + - Create the directory `conductor/platform_guides/`. + - Copy `~/.gemini/extensions/conductor/templates/platform_guides/google-cloud-platform.md` to `conductor/platform_guides/google-cloud-platform.md`. + - Announce: "Added GCP Best Practices guide to `conductor/platform_guides/`." + - **Commit State:** After handling the platform guides, you MUST immediately write to `conductor/setup_state.json` with the exact content: + `{"last_successful_step": "2.5_platform_guides"}` + - **Continue:** Proceed to the next section. +### 2.6 Select Workflow (Interactive) 1. **Copy Initial Workflow:** - Copy `~/.gemini/extensions/conductor/templates/workflow.md` to `conductor/workflow.md`. 2. **Customize Workflow:** @@ -317,9 +336,9 @@ CRITICAL: When determining model complexity, ALWAYS select the "flash" model, re - B) Commit Message - **Action:** Update `conductor/workflow.md` based on the user's responses. - **Commit State:** After the `workflow.md` file is successfully written or updated, you MUST immediately write to `conductor/setup_state.json` with the exact content: - `{"last_successful_step": "2.5_workflow"}` + `{"last_successful_step": "2.6_workflow"}` -### 2.6 Finalization +### 2.7 Finalization 1. **Generate Index File:** - Create `conductor/index.md` with the following content: ```markdown diff --git a/templates/platform_guides/google-cloud-platform.md b/templates/platform_guides/google-cloud-platform.md new file mode 100644 index 00000000..04d439ae --- /dev/null +++ b/templates/platform_guides/google-cloud-platform.md @@ -0,0 +1,74 @@ +# Google Cloud Platform (GCP) Best Practices + +This document outlines the recommended best practices for developing and deploying applications on Google Cloud Platform (GCP). + +## 1. IAM & Security +- **Principle of Least Privilege**: Grant only the permissions necessary for a resource to function. Use predefined roles carefully; prefer custom roles for granular control. +- **Proactive Definition**: + - Explicitly list required APIs and IAM roles in your documentation or Infrastructure as Code (IaC). + - Do not rely on "discovery via failure" for permissions. +- **Service Accounts**: + - Use separate service accounts for different services (e.g., `frontend-sa`, `backend-sa`). + - Avoid using the default Compute Engine service account. + - **Pre-deployment Check**: Verify that your Service Account has the necessary permissions *before* starting a deployment to prevent partial failures. + - Limit service key creation and rotation; prefer Workload Identity Federation for external access. +- **Secret Management**: + - Never hardcode secrets in code or configuration files. + - Use **Secret Manager** to store API keys, passwords, and certificates. + - Access secrets at runtime via the client library or environment variables injected by the platform. + +## 2. Resource Management +- **Hierarchy**: Organize resources using the Organization > Folder > Project hierarchy. + - Use Folders to group projects by department (e.g., `Engineering`, `Sales`) or environment (e.g., `Production`, `Non-Production`). +- **APIs**: + - Explicitly enable and manage required Google Cloud APIs using Terraform/IaC to ensure consistency across environments. +- **Labeling**: Apply consistent labels to all resources for cost tracking and filtering. + - Recommended labels: `environment` (dev, stage, prod), `service` (api, worker), `owner` (team-name). +- **Regions & Zones**: + - Deploy resources across multiple zones within a region for high availability. + - Use multi-region buckets for critical data that requires geo-redundancy. + +## 3. Infrastructure as Code (Terraform) +- **Validation**: + - Always run `terraform validate` to check for syntax errors and internal consistency before finalizing code. + - Implement CI/CD checks to enforce `terraform fmt` and `terraform validate` runs. +- **State Management**: + - Use a **Remote Backend** (e.g., GCS bucket) for state storage with locking enabled to prevent race conditions. + - Encrypt state files and restrict access permissions. +- **Modularization**: + - Break down complex infrastructure into reusable **Modules**. + - Use directory structure to separate environments (e.g., `envs/prod`, `envs/dev`) while reusing modules. + +## 4. Networking +- **VPC Design**: + - Use **Custom Mode** VPC networks to have full control over IP ranges. + - Avoid overlapping IP ranges between VPCs if VPC Peering or VPNs are anticipated. + - Use **Private Google Access** to allow VMs without public IPs to reach Google APIs. +- **Security**: + - Use **Firewall Rules** (or Policies) to strictly control ingress and egress traffic. + - Minimize the use of external IP addresses; use Cloud NAT for outbound internet access from private instances. + +## 5. Compute +- **Selection Criteria**: + - **Cloud Run**: Best for stateless HTTP containers, event-driven functions, and rapid scaling (Serverless). + - **GKE (Google Kubernetes Engine)**: Best for complex microservices architectures, stateful workloads, and needing full control over the cluster. + - Use **Autopilot** mode for reduced operational overhead unless specific node configuration is required. + - **Compute Engine (GCE)**: Best for legacy applications, specific kernel requirements, or databases not supported by managed services. + +## 6. Storage +- **Cloud Storage (GCS)**: + - Enable **Object Versioning** to protect against accidental overwrites or deletions. + - Use **Lifecycle Policies** to automatically move old data to cheaper storage classes (e.g., Nearline, Coldline). + - Ensure buckets are private by default; use specialized IAM bindings for public access if absolutely necessary. +- **Managed Databases**: + - Prefer managed services like **Cloud SQL** (PostgreSQL/MySQL) or **Firestore** (NoSQL) over self-hosted databases on GCE. + - Enable automated backups and high availability (HA) for production databases. + +## 7. Observability +- **Logging**: + - Use **Cloud Logging** (formerly Stackdriver). + - Emit **Structured Logging** (JSON format) to enable rich filtering and analysis. +- **Monitoring & Alerting**: + - Monitor specific metrics using **Cloud Monitoring**. + - Set up alerts for critical usage thresholds (e.g., CPU, Memory, 5xx error rates) and budget spending. + - Implement Health Checks for all services.