latest refactoring
Some checks failed
validation / verify (push) Failing after 10s

This commit is contained in:
2026-10-06 20:22:37 +01:00
parent e94b2493e7
commit 7ee49ab352
414 changed files with 15768 additions and 3896 deletions

View File

@@ -1,5 +1 @@
"""Skills package."""
from .loader import LocalSkill, SkillLoader
__all__ = ["LocalSkill", "SkillLoader"]
"""Agent Skills discovery and validation. The Skills themselves live in skills/ at the repository root."""

142
app/skills/agent_skills.py Normal file
View File

@@ -0,0 +1,142 @@
"""Agent Skills discovery and frontmatter validation.
A Skill is a directory holding a SKILL.md whose YAML frontmatter follows the
Agent Skills specification (https://agentskills.io/specification).
"""
from __future__ import annotations
import re
from collections.abc import Iterable
from dataclasses import dataclass
from pathlib import Path
import yaml
SKILL_FILE = "SKILL.md"
_NAME_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
_FRONTMATTER_PATTERN = re.compile(
r"\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)", re.DOTALL
)
_ALLOWED_FIELDS = {
"name",
"description",
"license",
"compatibility",
"metadata",
"allowed-tools",
}
class SkillFormatError(ValueError):
"""A SKILL.md does not conform to the Agent Skills specification."""
@dataclass(frozen=True)
class SkillMeta:
"""The level-1 metadata of a Skill, plus where it lives."""
name: str
description: str
path: Path
def split_frontmatter(text: str, source: Path) -> tuple[dict, str]:
"""Split a markdown document into its YAML frontmatter mapping and body."""
match = _FRONTMATTER_PATTERN.match(text)
if not match:
raise SkillFormatError(f"{source}: missing YAML frontmatter delimited by '---'")
try:
frontmatter = yaml.safe_load(match.group(1))
except yaml.YAMLError as exc:
raise SkillFormatError(
f"{source}: frontmatter is not valid YAML: {exc}"
) from exc
if not isinstance(frontmatter, dict):
raise SkillFormatError(f"{source}: frontmatter must be a mapping")
return frontmatter, text[match.end() :]
def read_skill(skill_dir: Path) -> SkillMeta:
"""Parse and validate the SKILL.md in `skill_dir`."""
skill_file = skill_dir / SKILL_FILE
frontmatter, _ = split_frontmatter(
skill_file.read_text(encoding="utf-8"), skill_file
)
unknown = set(frontmatter) - _ALLOWED_FIELDS
if unknown:
raise SkillFormatError(
f"{skill_file}: unsupported frontmatter fields: {', '.join(sorted(unknown))}"
)
name = frontmatter.get("name")
if not isinstance(name, str) or not name:
raise SkillFormatError(f"{skill_file}: 'name' is required")
if len(name) > 64:
raise SkillFormatError(f"{skill_file}: 'name' must be at most 64 characters")
if not _NAME_PATTERN.match(name):
raise SkillFormatError(
f"{skill_file}: 'name' must use lowercase letters, digits and single hyphens, "
"without leading or trailing hyphens"
)
if name != skill_dir.name:
raise SkillFormatError(
f"{skill_file}: 'name' {name!r} must match its directory {skill_dir.name!r}"
)
description = frontmatter.get("description")
if not isinstance(description, str) or not description.strip():
raise SkillFormatError(
f"{skill_file}: 'description' is required and must be non-empty"
)
if len(description) > 1024:
raise SkillFormatError(
f"{skill_file}: 'description' must be at most 1024 characters"
)
compatibility = frontmatter.get("compatibility")
if compatibility is not None and (
not isinstance(compatibility, str) or not 1 <= len(compatibility) <= 500
):
raise SkillFormatError(
f"{skill_file}: 'compatibility' must be 1-500 characters"
)
metadata = frontmatter.get("metadata")
if metadata is not None and (
not isinstance(metadata, dict)
or not all(
isinstance(key, str) and isinstance(value, str)
for key, value in metadata.items()
)
):
raise SkillFormatError(
f"{skill_file}: 'metadata' must map string keys to string values"
)
for field in ("license", "allowed-tools"):
if field in frontmatter and not isinstance(frontmatter[field], str):
raise SkillFormatError(f"{skill_file}: '{field}' must be a string")
return SkillMeta(name=name, description=description, path=skill_dir)
def discover_skills(directories: Iterable[Path]) -> dict[str, SkillMeta]:
"""Index every Skill that is an immediate child of one of `directories`.
Raises SkillFormatError on an invalid Skill or a name defined twice.
"""
skills: dict[str, SkillMeta] = {}
for directory in directories:
for child in sorted(directory.iterdir()):
if not (child / SKILL_FILE).is_file():
continue
skill = read_skill(child)
if skill.name in skills:
raise SkillFormatError(
f"Skill {skill.name!r} is defined in both {skills[skill.name].path} and {skill.path}"
)
skills[skill.name] = skill
return skills

View File

@@ -1,22 +0,0 @@
---
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.

View File

@@ -1,105 +0,0 @@
"""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,
)

View File

@@ -1,37 +0,0 @@
---
name: packaging_guide
phase: package
description: Guidance for assembling the comprehensive solution-architecture-guide.md following Google's official 8-section output template.
---
# Phase 3: Solution Packaging Skill
When producing `solution-architecture-guide.md`, follow Google's official 8-section solution architecture output template:
1. **Executive summary and workload overview**
- High-level business goals, workload description, and proposed solution architecture summary.
2. **Requirements and current state**
- **2.1. Functional requirements**: Business processes, key activities, and use cases.
- **2.2. Non-functional requirements**: Security, reliability, cost, operations, performance, and sustainability requirements.
- **2.3. Current state**: Existing As-Is architecture, pain points, and migration drivers.
- **2.4. Dependencies**: Internal and external system dependencies.
3. **Technical decomposition of the workload**
- Layered breakdown of application tiers and logical components.
4. **Proposed solution architecture**
- **4.1. Google Cloud products and features mapping**: Selected products mapping table with justifications, doc citations, and alternatives considered.
- **4.2. Architecture diagram**: Embedded Mermaid diagrams for As-Is (Before) and Target Google Cloud (After) architecture.
- **4.3. Architecture description**: Data flow and task/control flow between components.
5. **Design and configuration recommendations** (Architecture Framework Pillars)
- 5.1 Security, privacy, and compliance (IAM, encryption, network security)
- 5.2 Reliability (Redundancy, disaster recovery, RTO/RPO)
- 5.3 Operational excellence (Monitoring, logging, IaC)
- 5.4 Cost optimization (Sizing, autoscaling, pricing models)
- 5.5 Performance efficiency (Caching, database & query optimization)
- 5.6 Sustainability (Resource efficiency, serverless adoption)
6. **Deployment guidance**
- **6.1. Deployment prerequisites**: Required GCP APIs, SDK tools, and permissions.
- **6.2. Step-by-step deployment instructions**: Complete Terraform IaC blueprint (`terraform/main.tf`) and CLI execution runbook.
7. **Validation plan**
- Pre-deployment validation results, dry-run checks, and Verification Checklist.
8. **References**
- Citations and documentation links grounded by Google Developer Knowledge MCP.

View File

@@ -1,19 +0,0 @@
---
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.

View File

@@ -1,22 +0,0 @@
---
name: source_discovery
phase: source_discover
description: Guidance for discovering, auditing, and documenting the existing pre-emptive source environment before target migration.
---
# Phase 0a: Existing Source Environment Discovery Skill
When auditing and discovering an existing pre-emptive source environment:
1. **Assess As-Is Architecture**: Analyze existing workloads, on-premises applications, legacy infrastructure, or existing cloud provider setups.
2. **Identify Existing Components**:
- Monolithic / legacy application services & ingress endpoints.
- Self-hosted database engines (e.g. MySQL, PostgreSQL, Oracle) or legacy file shares.
- Traditional messaging queues (e.g. RabbitMQ, ActiveMQ).
- Network topology, firewall rules, and authentication mechanisms.
3. **Capture Source Metrics & Pain Points**:
- Current scale, capacity constraints, downtime risks, and operational bottlenecks.
- Security vulnerabilities, compliance gaps, and maintenance costs.
4. **Document Source Architecture**:
- Produce a clear `docs/source-architecture.md` baseline documenting the "Before" state.
- Render a Mermaid diagram representing the existing source topology (`source-architecture.mmd`).

View File

@@ -1,19 +0,0 @@
---
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.