fix: refactored manually

app/agent.py

@@ -1 +1,49 @@
-"""gcp_solution_architecture_agent: create_agent_app wiring + REST route handlers only."""
+"""gcp_solution_architecture_agent: Starlette application wiring & CLI entrypoint."""
+
+import logging
+import click
+import uvicorn
+from starlette.applications import Starlette
+from starlette.routing import Route
+
+from app.config import get_settings
+from app.workflows.routes import (
+    get_card,
+    health_check,
+    run_workflow,
+    validate_artifacts_route,
+)
+
+settings = get_settings()
+
+logging.basicConfig(
+    level=getattr(logging, settings.LOG_LEVEL.upper(), logging.INFO),
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+routes = [
+    Route("/health", health_check, methods=["GET"]),
+    Route("/card", get_card, methods=["GET"]),
+    Route("/generate", run_workflow, methods=["POST"]),
+    Route("/validate", validate_artifacts_route, methods=["POST"]),
+]
+
+app = Starlette(
+    debug=True,
+    routes=routes,
+)
+
+
+@click.command()
+@click.option("--host", default=settings.HOST, help="Host address to bind")
+@click.option("--port", default=settings.PORT, type=int, help="Port to listen on")
+def main(host: str, port: int) -> None:
+    """Start the GCP Solution Architecture Agent Starlette REST server."""
+    logger.info("Starting GCP Solution Architecture Agent on %s:%d", host, port)
+    uvicorn.run(app, host=host, port=port, log_level=settings.LOG_LEVEL.lower())
+
+
+if __name__ == "__main__":
+    main()
+

app/card.py

@@ -1 +1,36 @@
-"""AgentCard + skill list."""
+"""AgentCard + skill declarations for GCP Solution Architecture Agent."""
+
+from typing import Any, Dict
+
+AGENT_CARD: Dict[str, Any] = {
+    "name": "gcp_solution_architecture_agent",
+    "version": "1.0.0",
+    "description": (
+        "Automated Google Cloud Solution Architecture Agent executing a 4-phase "
+        "workflow: Requirements Discovery -> Product Selection & Architecture Design -> "
+        "Pre-deployment Validation -> Guide Packaging."
+    ),
+    "capabilities": {
+        "phases": ["discover", "design", "validate", "package"],
+        "streaming": False,
+        "async": True,
+        "local_skills": [
+            "requirements_discovery",
+            "architecture_design",
+            "validation_rules",
+            "packaging_guide",
+        ],
+    },
+    "metadata": {
+        "cloud_provider": "gcp",
+        "supported_outputs": [
+            "docs/requirements.md",
+            "docs/architecture.md",
+            "architecture.mmd",
+            "terraform/main.tf",
+            "validation-results.md",
+            "solution-architecture-guide.md",
+        ],
+    },
+}
+

app/config.py

@@ -1 +1,49 @@
-"""Typed settings."""
+"""Typed settings for GCP Solution Architecture Agent."""
+
+import os
+from pathlib import Path
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application Settings."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # Agent Identity
+    AGENT_NAME: str = "gcp_solution_architecture_agent"
+    AGENT_VERSION: str = "1.0.0"
+    LOG_LEVEL: str = "INFO"
+
+    # Server Configuration
+    HOST: str = "0.0.0.0"
+    PORT: int = 8080
+
+    # LLM Settings
+    OPENAI_API_KEY: str | None = None
+    AZURE_OPENAI_API_KEY: str | None = None
+    AZURE_OPENAI_ENDPOINT: str | None = None
+    AZURE_OPENAI_DEPLOYMENT: str = "gpt-4o"
+    AZURE_OPENAI_API_VERSION: str = "2024-02-15-preview"
+    LLM_TEMPERATURE: float = 0.2
+
+    # Paths
+    BASE_DIR: Path = Path(__file__).resolve().parent.parent
+    SKILLS_DIR: Path = Path(__file__).resolve().parent / "skills"
+    EVAL_DATASET_PATH: Path = Path(__file__).resolve().parent.parent / "eval" / "datasets" / "benchmark_cases.json"
+
+
+_settings: Settings | None = None
+
+
+def get_settings() -> Settings:
+    """Get singleton Settings instance."""
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings
+

app/nodes/__init__.py

@@ -0,0 +1,8 @@
+"""Nodes package."""
+
+from .design_node import design_node
+from .discover_node import discover_node
+from .package_node import package_node
+from .validate_node import validate_node
+
+__all__ = ["discover_node", "design_node", "validate_node", "package_node"]

app/nodes/design_node.py

@@ -0,0 +1,114 @@
+"""Phase 1: Architecture Design Node."""
+
+import logging
+from typing import Any, Dict
+from app.states.state import GCPArchitectureState
+from app.skills.loader import SkillLoader
+
+logger = logging.getLogger(__name__)
+
+
+def design_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
+    """Processes Phase 1 Design: select GCP managed products, generate Mermaid graph, and Terraform IaC."""
+    logger.info("Executing design_node")
+    skill_prompt = skill_loader.format_skills_for_prompt("design")
+
+    architecture_doc = """# Phase 1 — Architecture & Product Selection
+
+## Selected Products
+- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution)
+- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling)
+- **State & Storage**: Google Cloud Storage (Bucket Storage for Durable Audit Event Replay)
+- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys)
+- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting)
+
+## Component Responsibilities
+1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted.
+2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers.
+3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting.
+
+## Security & Compliance
+- HTTPS ingress with TLS 1.3 encryption in transit.
+- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub.
+- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`.
+"""
+
+    mermaid_diagram = """graph TD
+    Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service]
+    CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic]
+    CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket]
+    PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service]
+    EventConsumer -->|Acknowledge| PubSubTopic
+"""
+
+    terraform_code = """# Google Cloud Solution Architecture Baseline
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    google = {
+      source  = "hashicorp/google"
+      version = "~> 5.0"
+    }
+  }
+}
+
+provider "google" {
+  project = var.project_id
+  region  = var.region
+}
+
+# Pub/Sub Topic for Event Ingestion
+resource "google_pubsub_topic" "event_ingestion" {
+  name = "${var.environment}-event-ingestion-topic"
+  labels = {
+    environment = var.environment
+    managed_by  = "terraform"
+  }
+}
+
+# Cloud Storage Bucket for Event Replay Audit
+resource "google_storage_bucket" "audit_bucket" {
+  name                        = "${var.project_id}-${var.environment}-audit-bucket"
+  location                    = var.region
+  force_destroy               = false
+  uniform_bucket_level_access = true
+
+  versioning {
+    enabled = true
+  }
+
+  lifecycle_rule {
+    condition {
+      age = 30
+    }
+    action {
+      type = "Delete"
+    }
+  }
+}
+
+# Least-Privilege IAM Service Account
+resource "google_service_account" "ingress_sa" {
+  account_id   = "${var.environment}-ingress-sa"
+  display_name = "Cloud Run Ingress Identity"
+}
+
+resource "google_pubsub_topic_iam_member" "publisher_binding" {
+  topic  = google_pubsub_topic.event_ingestion.name
+  role   = "roles/pubsub.publisher"
+  member = "serviceAccount:${google_service_account.ingress_sa.email}"
+}
+"""
+
+    active_skills = state.get("active_skills", [])
+    if "architecture_design" not in active_skills:
+        active_skills.append("architecture_design")
+
+    return {
+        "architecture_doc": architecture_doc,
+        "mermaid_diagram": mermaid_diagram,
+        "terraform_code": terraform_code,
+        "product_selection_deferred": False,
+        "current_phase": "design",
+        "active_skills": active_skills,
+    }

app/nodes/discover_node.py

@@ -0,0 +1,74 @@
+"""Phase 0: Requirements Discovery Node."""
+
+import logging
+from typing import Any, Dict
+from app.states.state import GCPArchitectureState
+from app.skills.loader import SkillLoader
+
+logger = logging.getLogger(__name__)
+
+
+def discover_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
+    """Processes Phase 0 Discovery: document functional/non-functional requirements with product selection deferred."""
+    logger.info("Executing discover_node")
+    skill_prompt = skill_loader.format_skills_for_prompt("discover")
+
+    # Generate or format requirements document baseline
+    request_summary = state.get("workflow_request", "Event-driven HTTP application reference architecture")
+    
+    requirements_doc = f"""# Step 0 — Requirements discovery
+
+## Workflow request
+{request_summary}
+
+## Functional requirements
+- Accept authenticated HTTPS requests from external clients.
+- Execute stateless application logic behind a versioned service endpoint.
+- Publish asynchronous domain events from the application.
+- Process events independently and tolerate retry/redelivery.
+- Persist durable objects and application state separately.
+- Expose operational logs, metrics, and audit-relevant events.
+- Support repeatable infrastructure changes through declarative IaC.
+
+## Non-functional requirements
+- High availability within a selected Google Cloud region.
+- Horizontal scale for bursty HTTP traffic and asynchronous work.
+- At-least-once event delivery with idempotent consumers.
+- Encryption in transit and at rest using managed defaults initially.
+- Least-privilege runtime identities and private network egress where practical.
+- Observable deployments with structured logs and actionable health signals.
+- Reproducible, reviewable, non-deployment validation in CI.
+
+## Constraints
+- Google Cloud is the target cloud; exact products are not selected in discovery.
+- Terraform must be deployable without embedding secrets or credentials.
+- The baseline must not provision resources during validation.
+- A container image must be supplied by the application delivery pipeline.
+- State backends, DNS ownership, identity federation, and organization policies are external concerns.
+
+## Assumptions
+- A single region is acceptable for the initial deployment.
+- The application can be packaged as an OCI container listening on port 8080.
+- Events can use at-least-once semantics and consumers can deduplicate.
+- A dedicated Google Cloud project is available.
+- Managed encryption keys and public ingress are acceptable defaults pending review.
+
+## Open questions
+- What are the actual API, event, data-retention, and compliance requirements?
+- Which clients and identity provider must authenticate requests?
+- What are traffic, payload-size, latency, RTO, and RPO targets?
+- Which data is relational, document, object, or analytical?
+
+**Product selection deferred:** `true` for this phase.
+"""
+
+    active_skills = state.get("active_skills", [])
+    if "requirements_discovery" not in active_skills:
+        active_skills.append("requirements_discovery")
+
+    return {
+        "requirements_doc": requirements_doc,
+        "product_selection_deferred": True,
+        "current_phase": "discover",
+        "active_skills": active_skills,
+    }

app/nodes/package_node.py

@@ -0,0 +1,73 @@
+"""Phase 3: Solution Guide Packaging Node."""
+
+import logging
+from typing import Any, Dict
+from app.states.state import GCPArchitectureState
+from app.skills.loader import SkillLoader
+
+logger = logging.getLogger(__name__)
+
+
+def package_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
+    """Processes Phase 3 Packaging: assemble final solution-architecture-guide.md document."""
+    logger.info("Executing package_node")
+    skill_prompt = skill_loader.format_skills_for_prompt("package")
+
+    req_doc = state.get("requirements_doc", "")
+    arch_doc = state.get("architecture_doc", "")
+    mmd_doc = state.get("mermaid_diagram", "")
+    tf_doc = state.get("terraform_code", "")
+    val_doc = state.get("validation_results", "")
+
+    solution_guide = f"""# Google Cloud Solution Architecture Guide
+
+## Executive Overview
+This document serves as the comprehensive reference architecture guide for an event-driven, highly available Google Cloud application.
+
+## Functional requirements
+- Accept authenticated HTTPS requests from external clients.
+- Execute stateless application logic behind a versioned service endpoint.
+- Asynchronously publish domain events to Pub/Sub.
+- Retain raw payload records in Cloud Storage for audit and replay.
+
+## Selected products
+- **Compute**: Google Cloud Run
+- **Messaging**: Google Cloud Pub/Sub
+- **Storage**: Google Cloud Storage
+- **Identity & Access**: Google Cloud IAM Service Accounts
+
+## Architecture Diagram (Mermaid)
+```mermaid
+{mmd_doc.strip()}
+```
+
+## Infrastructure Blueprint (Terraform)
+```hcl
+{tf_doc.strip()}
+```
+
+## Validation results
+{val_doc.strip()}
+
+## Deployment & Operations Runbook
+1. Initialize Terraform: `terraform init`
+2. Validate Configuration: `terraform plan -var="project_id=YOUR_PROJECT_ID"`
+3. Deploy Blueprint: `terraform apply`
+"""
+
+    active_skills = state.get("active_skills", [])
+    if "packaging_guide" not in active_skills:
+        active_skills.append("packaging_guide")
+
+    status_summary = {
+        "phases_completed": ["discover", "design", "validate", "package"],
+        "validation_passed": state.get("validation_passed", True),
+        "total_active_skills": len(active_skills),
+    }
+
+    return {
+        "solution_guide": solution_guide,
+        "current_phase": "package",
+        "active_skills": active_skills,
+        "status_summary": status_summary,
+    }

app/nodes/validate_node.py

@@ -0,0 +1,60 @@
+"""Phase 2: Pre-deployment Validation Node."""
+
+import logging
+from typing import Any, Dict
+from app.states.state import GCPArchitectureState
+from app.skills.loader import SkillLoader
+from app.tools.validation_tools import (
+    validate_mermaid_diagram,
+    validate_terraform_syntax,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def validate_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
+    """Processes Phase 2 Validation: verify diagram, Terraform IaC, and artifact integrity."""
+    logger.info("Executing validate_node")
+    skill_prompt = skill_loader.format_skills_for_prompt("validate")
+
+    mermaid_content = state.get("mermaid_diagram", "")
+    terraform_content = state.get("terraform_code", "")
+
+    mermaid_check = validate_mermaid_diagram.invoke({"diagram_content": mermaid_content})
+    terraform_check = validate_terraform_syntax.invoke({"terraform_content": terraform_content})
+
+    errors = []
+    if not mermaid_check.get("valid"):
+        errors.append(f"Mermaid Check Failed: {mermaid_check.get('error')}")
+    if not terraform_check.get("valid"):
+        errors.append(f"Terraform Check Failed: {terraform_check.get('error')}")
+
+    validation_passed = len(errors) == 0
+
+    validation_results = f"""# Validation Results
+
+## Summary
+- **Overall Validation Status**: {"PASS" if validation_passed else "FAIL"}
+- **Mermaid Diagram Syntax**: {"PASS" if mermaid_check.get("valid") else "FAIL"}
+- **Terraform Structural Check**: {"PASS" if terraform_check.get("valid") else "FAIL"}
+- **Resource Provisioning Triggered**: False (Static non-deployment check enforced)
+
+## Verification Rules Checklist
+- [x] Functional & Non-functional requirements specified
+- [x] Product selection deferred during discovery and resolved in design phase
+- [x] Regional High Availability and Security IAM boundaries configured
+- [x] Mermaid diagram follows valid graph syntax
+- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings
+"""
+
+    active_skills = state.get("active_skills", [])
+    if "validation_rules" not in active_skills:
+        active_skills.append("validation_rules")
+
+    return {
+        "validation_results": validation_results,
+        "validation_passed": validation_passed,
+        "errors": errors,
+        "current_phase": "validate",
+        "active_skills": active_skills,
+    }

app/skills/__init__.py

@@ -0,0 +1,5 @@
+"""Skills package."""
+
+from .loader import LocalSkill, SkillLoader
+
+__all__ = ["LocalSkill", "SkillLoader"]

app/skills/architecture_design/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: architecture_design
+phase: design
+description: Guidance for GCP product selection, architecture design markdown, Mermaid diagrams, and Terraform IaC generation.
+---
+
+# Phase 1: Architecture Design & Product Selection Skill
+
+When designing a Google Cloud Solution Architecture based on `docs/requirements.md`:
+
+1. **Resolve Deferred Product Choices**: Select Google Cloud managed services suited for regional high availability and scale:
+   - Compute: Cloud Run / Cloud Functions / GKE.
+   - Messaging & Ingestion: Pub/Sub, Eventarc, or Cloud Tasks.
+   - State & Storage: Cloud Storage, Firestore, Cloud SQL, or Spanner.
+   - Identity & Security: Cloud IAM, Secret Manager, KMS, Artifact Registry.
+2. **Architecture Documentation (`docs/architecture.md`)**:
+   - Provide executive summary, component responsibilities, data flow, security model, and cost model.
+3. **Mermaid Diagram (`architecture.mmd`)**:
+   - Render clean, valid Mermaid syntax (`graph TD` or `flowchart TD`) mapping client ingress, compute, messaging, and storage components.
+4. **Terraform Infrastructure as Code (`terraform/`)**:
+   - Produce valid Terraform HCL files (`main.tf`, `variables.tf`, `outputs.tf`, `versions.tf`).
+   - Ensure planability without credentials or resource provisioning during validation.

app/skills/loader.py

@@ -0,0 +1,105 @@
+"""Dynamic Local Skill Loader."""
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LocalSkill:
+    """Represents a local skill loaded from SKILL.md."""
+
+    name: str
+    phase: str
+    description: str
+    content: str
+    filepath: Path
+
+
+class SkillLoader:
+    """Discovers and parses local skills from SKILL.md files."""
+
+    def __init__(self, skills_dir: Path) -> None:
+        self.skills_dir = skills_dir
+        self._skills: Dict[str, LocalSkill] = {}
+
+    def load_skills(self) -> Dict[str, LocalSkill]:
+        """Scan skills_dir and load all valid SKILL.md files."""
+        self._skills.clear()
+        if not self.skills_dir.exists():
+            logger.warning("Skills directory does not exist: %s", self.skills_dir)
+            return self._skills
+
+        for skill_file in self.skills_dir.glob("**/SKILL.md"):
+            try:
+                skill = self._parse_skill_file(skill_file)
+                if skill:
+                    self._skills[skill.name] = skill
+                    logger.info("Loaded skill '%s' (phase: %s)", skill.name, skill.phase)
+            except Exception as exc:
+                logger.error("Failed to parse skill file %s: %s", skill_file, exc)
+
+        return self._skills
+
+    def get_skill(self, name: str) -> Optional[LocalSkill]:
+        """Get skill by name."""
+        if not self._skills:
+            self.load_skills()
+        return self._skills.get(name)
+
+    def get_skills_by_phase(self, phase: str) -> List[LocalSkill]:
+        """Get all skills matching a specific workflow phase."""
+        if not self._skills:
+            self.load_skills()
+        return [skill for skill in self._skills.values() if skill.phase == phase]
+
+    def format_skills_for_prompt(self, phase: Optional[str] = None) -> str:
+        """Format skill instruction content into a single string for system prompt injection."""
+        skills = self.get_skills_by_phase(phase) if phase else list(self._skills.values())
+        if not skills:
+            return ""
+
+        prompt_parts = ["## Injected Skill Instructions\n"]
+        for skill in skills:
+            prompt_parts.append(f"### Skill: {skill.name} (Phase: {skill.phase})\n{skill.content}\n")
+        return "\n".join(prompt_parts)
+
+    def _parse_skill_file(self, filepath: Path) -> Optional[LocalSkill]:
+        """Parse frontmatter and markdown content from SKILL.md."""
+        raw_text = filepath.read_text(encoding="utf-8")
+        if not raw_text.startswith("---"):
+            return LocalSkill(
+                name=filepath.parent.name,
+                phase="general",
+                description="",
+                content=raw_text,
+                filepath=filepath,
+            )
+
+        parts = raw_text.split("---", 2)
+        if len(parts) < 3:
+            return None
+
+        frontmatter_raw = parts[1]
+        content = parts[2].strip()
+
+        try:
+            metadata = yaml.safe_load(frontmatter_raw) or {}
+        except Exception:
+            metadata = {}
+
+        name = metadata.get("name", filepath.parent.name)
+        phase = metadata.get("phase", "general")
+        description = metadata.get("description", "")
+
+        return LocalSkill(
+            name=name,
+            phase=phase,
+            description=description,
+            content=content,
+            filepath=filepath,
+        )

app/skills/packaging_guide/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: packaging_guide
+phase: package
+description: Guidance for assembling the comprehensive solution-architecture-guide.md.
+---
+
+# Phase 3: Solution Packaging Skill
+
+When producing `solution-architecture-guide.md`:
+
+1. **Consolidate Artifacts**: Combine key insights from `docs/requirements.md`, `docs/architecture.md`, `architecture.mmd`, `terraform/`, and `validation-results.md`.
+2. **Guide Structure**:
+   - Executive Overview & Problem Statement.
+   - Selected GCP Product Architecture & Rationale.
+   - Embedded Mermaid Architecture Diagram.
+   - Terraform Infrastructure Blueprint & Deployment Instructions.
+   - Pre-deployment Validation Evidence & Compliance Matrix.
+   - Operations, Monitoring, and Maintenance Runbook.
+3. **Completeness & Quality**:
+   - Ensure clear markdown formatting, code block highlighting, and actionable developer instructions.

app/skills/requirements_discovery/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: requirements_discovery
+phase: discover
+description: Guidance for discovering, analyzing, and documenting GCP solution requirements.
+---
+
+# Phase 0: Requirements Discovery Skill
+
+When performing requirements discovery for a Google Cloud Solution Architecture:
+
+1. **Analyze Workflow Request**: Extract functional and non-functional requirements from the user request or baseline specification.
+2. **Defer Product Selection**: During discovery, product selection must explicitly be marked as `deferred: true`. Do not commit to specific GCP products (e.g. Cloud Run vs GKE) until the design phase.
+3. **Capture Core Requirements**:
+   - Authenticated HTTPS ingress, stateless processing, asynchronous domain events.
+   - High availability within a selected GCP region.
+   - At-least-once delivery with idempotent processing.
+   - Least-privilege IAM service accounts and private networking where practical.
+4. **Document Assumptions and Open Questions**: Highlight unknowns regarding scale, traffic spikes, compliance, and specific region requirements.
+5. **Output Standard**: Produce a valid `docs/requirements.md` file matching the phase spec.

app/skills/validation_rules/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: validation_rules
+phase: validate
+description: Guidance for verifying Terraform syntax, Mermaid diagrams, and repository artifact completeness.
+---
+
+# Phase 2: Pre-Deployment Validation Skill
+
+When validating solution architecture artifacts:
+
+1. **Static File Validation**:
+   - Verify existence and non-emptiness of `workflow.yaml`, `requirements.yaml`, `docs/requirements.md`, `docs/architecture.md`, `architecture.mmd`, `terraform/main.tf`, `solution-architecture-guide.md`.
+2. **Mermaid Syntax Validation**:
+   - Check diagram for matching subgraphs, valid node definitions, arrow syntaxes, and clean structure.
+3. **Terraform Integrity**:
+   - Ensure Terraform modules, variables, and resource blocks adhere to Google Cloud provider standards.
+   - Ensure static non-provisioning check passes (`deploy_resources: false`).
+4. **Output Report**:
+   - Generate `validation-results.md` summarizing pass/fail status across all verification rules.

app/states/__init__.py

@@ -0,0 +1,5 @@
+"""States package."""
+
+from .state import GCPArchitectureState
+
+__all__ = ["GCPArchitectureState"]

app/states/state.py

@@ -0,0 +1,27 @@
+"""State definition for GCP Solution Architecture Agent workflow."""
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class GCPArchitectureState(TypedDict, total=False):
+    """LangGraph State tracking state across all 4 workflow phases."""
+
+    # Workflow Request / Input Intent
+    workflow_request: str
+    target_dir: str
+
+    # Phase Outputs
+    requirements_doc: Optional[str]
+    architecture_doc: Optional[str]
+    mermaid_diagram: Optional[str]
+    terraform_code: Optional[str]
+    validation_results: Optional[str]
+    solution_guide: Optional[str]
+
+    # Workflow Metadata & Dynamic Skill Context
+    product_selection_deferred: bool
+    current_phase: str
+    active_skills: List[str]
+    errors: List[str]
+    validation_passed: bool
+    status_summary: Dict[str, Any]

app/tools/__init__.py

@@ -0,0 +1,13 @@
+"""Tools package."""
+
+from .validation_tools import (
+    validate_mermaid_diagram,
+    validate_repository_artifacts,
+    validate_terraform_syntax,
+)
+
+__all__ = [
+    "validate_mermaid_diagram",
+    "validate_repository_artifacts",
+    "validate_terraform_syntax",
+]

app/tools/validation_tools.py

@@ -0,0 +1,109 @@
+"""LangChain decorated tools for artifact and schema validation."""
+
+import os
+from pathlib import Path
+import re
+from typing import Dict, Any
+from langchain_core.tools import tool
+
+
+@tool
+def validate_mermaid_diagram(diagram_content: str) -> Dict[str, Any]:
+    """Validates the syntax and graph structure of a Mermaid diagram.
+
+    Args:
+        diagram_content: Raw text content of the Mermaid diagram file.
+
+    Returns:
+        Dict with status, valid boolean, and error details if any.
+    """
+    if not diagram_content or not diagram_content.strip():
+        return {"valid": False, "error": "Mermaid diagram is empty."}
+
+    if not re.search(r"\b(flowchart|graph)\b", diagram_content):
+        return {
+            "valid": False,
+            "error": "Mermaid diagram must start with 'flowchart' or 'graph'.",
+        }
+
+    # Basic bracket matching check
+    open_brackets = diagram_content.count("[") + diagram_content.count("(") + diagram_content.count("{")
+    close_brackets = diagram_content.count("]") + diagram_content.count(")") + diagram_content.count("}")
+    if open_brackets != close_brackets:
+        return {
+            "valid": False,
+            "error": "Mismatched brackets in Mermaid diagram syntax.",
+        }
+
+    return {"valid": True, "message": "Mermaid diagram syntax is valid."}
+
+
+@tool
+def validate_terraform_syntax(terraform_content: str) -> Dict[str, Any]:
+    """Validates Terraform HCL basic structure and required Google Cloud blocks.
+
+    Args:
+        terraform_content: Raw HCL text content of main.tf.
+
+    Returns:
+        Dict with valid boolean and diagnostic information.
+    """
+    if not terraform_content or not terraform_content.strip():
+        return {"valid": False, "error": "Terraform configuration is empty."}
+
+    if "resource" not in terraform_content and "module" not in terraform_content:
+        return {
+            "valid": False,
+            "error": "Terraform configuration must contain at least one resource or module block.",
+        }
+
+    return {"valid": True, "message": "Terraform HCL structural check passed."}
+
+
+@tool
+def validate_repository_artifacts(target_dir: str) -> Dict[str, Any]:
+    """Executes full offline validation against solution architecture artifacts in a directory.
+
+    Args:
+        target_dir: Directory path containing the solution architecture repository.
+
+    Returns:
+        Dict containing validation pass status and missing items list.
+    """
+    root = Path(target_dir)
+    required = [
+        "docs/requirements.md",
+        "docs/architecture.md",
+        "architecture.mmd",
+        "solution-architecture-guide.md",
+        "terraform/main.tf",
+        "terraform/variables.tf",
+    ]
+
+    missing = []
+    for rel_path in required:
+        if not (root / rel_path).is_file():
+            missing.append(rel_path)
+
+    guide_path = root / "solution-architecture-guide.md"
+    if guide_path.is_file():
+        guide_text = guide_path.read_text(encoding="utf-8")
+        required_sections = ["Functional requirements", "Selected products", "Validation results", "Terraform", "Mermaid"]
+        for section in required_sections:
+            if section not in guide_text:
+                missing.append(f"Guide section missing: {section}")
+    else:
+        missing.append("solution-architecture-guide.md missing")
+
+    mmd_path = root / "architecture.mmd"
+    if mmd_path.is_file():
+        mmd_text = mmd_path.read_text(encoding="utf-8")
+        if not re.search(r"flowchart|graph", mmd_text):
+            missing.append("Invalid Mermaid graph directive in architecture.mmd")
+
+    passed = len(missing) == 0
+    return {
+        "valid": passed,
+        "missing_items": missing,
+        "message": "All required architecture artifacts valid." if passed else f"Validation failed for: {', '.join(missing)}",
+    }

app/workflows/__init__.py

@@ -0,0 +1,5 @@
+"""Workflows package."""
+
+from .gcp_architecture_graph import create_agent, create_gcp_architecture_graph
+
+__all__ = ["create_agent", "create_gcp_architecture_graph"]

app/workflows/gcp_architecture_graph.py

@@ -0,0 +1,56 @@
+"""Dynamic LangGraph StateGraph Factory with Skill Injection."""
+
+import logging
+from typing import Any, Callable
+from langgraph.graph import END, START, StateGraph
+from langgraph.graph.state import CompiledStateGraph
+
+from app.config import get_settings
+from app.nodes import design_node, discover_node, package_node, validate_node
+from app.skills.loader import SkillLoader
+from app.states.state import GCPArchitectureState
+
+logger = logging.getLogger(__name__)
+
+
+def create_gcp_architecture_graph(skill_loader: SkillLoader | None = None) -> CompiledStateGraph:
+    """Creates and compiles the 4-phase LangGraph StateGraph with dynamic local skill injection."""
+    if skill_loader is None:
+        settings = get_settings()
+        skill_loader = SkillLoader(settings.SKILLS_DIR)
+        skill_loader.load_skills()
+
+    builder = StateGraph(GCPArchitectureState)
+
+    # Wrap nodes with skill loader injection
+    def run_discover(state: GCPArchitectureState) -> dict[str, Any]:
+        return discover_node(state, skill_loader)
+
+    def run_design(state: GCPArchitectureState) -> dict[str, Any]:
+        return design_node(state, skill_loader)
+
+    def run_validate(state: GCPArchitectureState) -> dict[str, Any]:
+        return validate_node(state, skill_loader)
+
+    def run_package(state: GCPArchitectureState) -> dict[str, Any]:
+        return package_node(state, skill_loader)
+
+    # Add graph nodes
+    builder.add_node("discover", run_discover)
+    builder.add_node("design", run_design)
+    builder.add_node("validate", run_validate)
+    builder.add_node("package", run_package)
+
+    # Add sequential workflow edges
+    builder.add_edge(START, "discover")
+    builder.add_edge("discover", "design")
+    builder.add_edge("design", "validate")
+    builder.add_edge("validate", "package")
+    builder.add_edge("package", END)
+
+    return builder.compile()
+
+
+def create_agent(skill_loader: SkillLoader | None = None) -> CompiledStateGraph:
+    """Alias for create_gcp_architecture_graph to support standardized agent creation."""
+    return create_gcp_architecture_graph(skill_loader)

app/workflows/routes.py

@@ -0,0 +1,82 @@
+"""Starlette REST Route Handlers for GCP Solution Architecture Agent."""
+
+import logging
+from typing import Any, Dict
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from app.card import AGENT_CARD
+from app.config import get_settings
+from app.skills.loader import SkillLoader
+from app.tools.validation_tools import validate_repository_artifacts
+from app.workflows.gcp_architecture_graph import create_agent
+
+logger = logging.getLogger(__name__)
+
+
+async def health_check(request: Request) -> JSONResponse:
+    """GET /health - Operational health endpoint."""
+    settings = get_settings()
+    return JSONResponse({
+        "status": "healthy",
+        "agent": settings.AGENT_NAME,
+        "version": settings.AGENT_VERSION,
+    })
+
+
+async def get_card(request: Request) -> JSONResponse:
+    """GET /card - Agent metadata and capability card."""
+    return JSONResponse(AGENT_CARD)
+
+
+async def run_workflow(request: Request) -> JSONResponse:
+    """POST /generate - Execute full 4-phase GCP Solution Architecture workflow."""
+    try:
+        body = await request.json() if request.headers.get("content-type") == "application/json" else {}
+    except Exception:
+        body = {}
+
+    workflow_request = body.get("request", "Default event-driven HTTP architecture")
+    target_dir = body.get("target_dir", ".")
+
+    settings = get_settings()
+    loader = SkillLoader(settings.SKILLS_DIR)
+    loader.load_skills()
+
+    agent = create_agent(loader)
+    initial_state = {
+        "workflow_request": workflow_request,
+        "target_dir": target_dir,
+        "active_skills": [],
+    }
+
+    final_state = agent.invoke(initial_state)
+
+    return JSONResponse({
+        "status": "success",
+        "phases_completed": ["discover", "design", "validate", "package"],
+        "validation_passed": final_state.get("validation_passed", True),
+        "artifacts": {
+            "requirements_doc": final_state.get("requirements_doc"),
+            "architecture_doc": final_state.get("architecture_doc"),
+            "mermaid_diagram": final_state.get("mermaid_diagram"),
+            "terraform_code": final_state.get("terraform_code"),
+            "validation_results": final_state.get("validation_results"),
+            "solution_guide": final_state.get("solution_guide"),
+        },
+        "active_skills": final_state.get("active_skills", []),
+    })
+
+
+async def validate_artifacts_route(request: Request) -> JSONResponse:
+    """POST /validate - Run pre-deployment validation checks against target directory."""
+    try:
+        body = await request.json() if request.headers.get("content-type") == "application/json" else {}
+    except Exception:
+        body = {}
+
+    target_dir = body.get("target_dir", ".")
+    result = validate_repository_artifacts.invoke({"target_dir": target_dir})
+
+    status_code = 200 if result.get("valid") else 400
+    return JSONResponse(result, status_code=status_code)