@cubis/foundry 0.3.63 → 0.3.64

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/python-pro/SKILL.md

@@ -18,6 +18,12 @@ metadata:
 - Migrating legacy Python to typed and testable architecture.
 - Implementing async I/O with predictable behavior.
 
+## When not to use
+
+- Frontend-only tasks with no Python runtime involved.
+- Database-only tuning or migration work with no Python code change.
+- Tiny shell-first automation where Python adds unnecessary packaging/runtime cost.
+
 ## Core workflow
 
 1. Establish interpreter/runtime constraints.
@@ -41,6 +47,18 @@ metadata:
 - Keep I/O async and CPU work isolated where needed.
 - Treat free-threaded mode as opt-in until dependencies are validated.
 
+## Debugging and observability
+
+- Preserve exception context and structured log fields at service boundaries.
+- Reproduce async bugs with deterministic fixtures before widening scope.
+- Use profiling and trace tooling before speculative concurrency changes.
+
+## Performance and reliability
+
+- Set timeout/retry budgets explicitly for external I/O.
+- Isolate CPU-heavy work from event loops or request handlers.
+- Keep dependency and packaging state reproducible with `pyproject.toml` tooling.
+
 ## Avoid
 
 - Untyped public APIs in shared modules.
@@ -49,8 +67,10 @@ metadata:
 
 ## Reference files
 
-- `references/type-system.md`
-- `references/async-patterns.md`
-- `references/testing.md`
-- `references/packaging.md`
-- `references/standard-library.md`
+| File | Load when |
+| --- | --- |
+| `references/type-system.md` | Typing strategy, protocols, generics, or boundary models need detail. |
+| `references/async-patterns.md` | Async I/O, task groups, or cancellation semantics need detail. |
+| `references/testing.md` | Pytest strategy, fixtures, or concurrency-safe tests are needed. |
+| `references/packaging.md` | Packaging, dependency layout, or toolchain reproducibility is in scope. |
+| `references/standard-library.md` | Standard-library-first options need review before adding dependencies. |

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/react-expert/references/migration-class-to-modern.md

@@ -924,7 +924,7 @@ export default async function UserProfile({ params }: { params: { id: string } }
 - SEO-critical content? → Server Component
 - Large dependencies? → Server Component (smaller client bundle)
 
-See reference: `react-expert/references/server-components.md`
+See reference: [server-components.md](server-components.md)
 
 ---
 

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/riverpod-3/SKILL.md

@@ -125,19 +125,25 @@ Avoid keepAlive for:
 
 ## Steering Files
 
-- `loop-avoidance.md` - Loop diagnostics and safe patterns
-- `minimal-rebuild.md` - `select`, widget splitting, item-level providers
-- `provider-layout.md` - Generic provider organization and boundaries
-- `refresh-cache-paging.md` - Refresh/paging/cache recipes
-- `testing.md` - ProviderContainer and widget test patterns
+| File | Load when |
+| --- | --- |
+| `references/loop-avoidance.md` | Diagnosing provider loops, invalidation storms, or notifier recursion. |
+| `references/minimal-rebuild.md` | Reducing rebuilds with `select`, widget splitting, or item-level providers. |
+| `references/provider-layout.md` | Organizing provider boundaries, layers, and ownership. |
+| `references/refresh-cache-paging.md` | Designing refresh, cache TTL, paging, or stale-while-revalidate flows. |
+| `references/testing.md` | Writing `ProviderContainer` or widget tests for Riverpod behavior. |
 
 ## Examples
 
-- `attendance_paging.md` - Complete paging example
-- `profile_edit.md` - Form workflow example
+| File | Load when |
+| --- | --- |
+| `examples/attendance_paging.md` | You need a concrete paginated list example. |
+| `examples/profile_edit.md` | You need a form/editing workflow example. |
 
 ## Templates
 
-- `cache_policy.dart` - TTL helper for repository cache policy
-- `paged_controller.dart` - Cursor/page-based infinite list controller
-- `riverpod_controller_test` - Provider/controller test template
+| File | Load when |
+| --- | --- |
+| `templates/cache_policy.dart.md` | Creating a TTL helper for repository caching. |
+| `templates/paged_controller.dart.md` | Bootstrapping a cursor/page-based controller. |
+| `templates/riverpod_controller_test.md` | Starting a provider/controller test template. |

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/rust-pro/SKILL.md

@@ -18,6 +18,12 @@ metadata:
 - Solving ownership/lifetime design problems.
 - Optimizing memory safety and runtime performance together.
 
+## When not to use
+
+- Browser/frontend-only work with no Rust component.
+- Database-only tuning without Rust service or library changes.
+- Small scripts where shell or existing project tooling is the intended path.
+
 ## Core workflow
 
 1. Define ownership and error model first.
@@ -42,6 +48,24 @@ metadata:
 - Keep borrow scopes tight to improve readability and compile times.
 - Separate transport DTOs from domain types.
 
+## Debugging and observability
+
+- Prefer reproducible failing tests and `tracing` instrumentation before redesigning ownership or async structure.
+- Make task cancellation, retries, and error chains visible in logs/telemetry.
+- Use `cargo test`, `clippy`, and targeted benchmarks to isolate regressions.
+
+## Performance and reliability
+
+- Keep async flows cancellation-safe and backpressure-aware.
+- Measure allocations, lock contention, and tail latency before unsafe or low-level tuning.
+- Bound work queues and connection pools explicitly.
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `references/operational-baseline.md` | You need service-level guardrails for async, errors, tracing, and test discipline. |
+
 ## Avoid
 
 - Premature `unsafe` optimization.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/rust-pro/references/operational-baseline.md

@@ -0,0 +1,9 @@
+## Operational baseline
+
+Load when: async service safety, tracing, error handling, or release guardrails need explicit guidance.
+
+- Keep error chains actionable and visible in logs/traces.
+- Use `cargo fmt`, `clippy`, and focused tests as a release baseline.
+- Make cancellation, queue bounds, and backpressure explicit.
+- Treat `unsafe` as an exception with documented invariants.
+- Profile before low-level optimization.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/security-reviewer/SKILL.md

@@ -73,11 +73,3 @@ Provide: (1) Executive summary with risk, (2) Findings table with severity count
 ## Knowledge Reference
 
 OWASP Top 10, CWE, Semgrep, Bandit, ESLint Security, gosec, npm audit, gitleaks, trufflehog, CVSS scoring, nmap, Burp Suite, sqlmap, Trivy, Checkov, HashiCorp Vault, AWS Security Hub, CIS benchmarks, SOC2, ISO27001
-
-## Related Powers
-
-- **Secure Code Guardian** - Implementing fixes
-- **Code Reviewer** - General code review
-- **DevOps Engineer** - Security in CI/CD
-- **Cloud Architect** - Cloud security architecture
-- **Kubernetes Specialist** - Container security

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/skill-authoring/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: "skill-authoring"
+description: "Use when creating a new Foundry skill or updating an existing one: scaffolding SKILL.md, fixing metadata, wiring references and scripts, removing legacy power files, and making the package work across Codex, Antigravity, Copilot, Cursor, and Windsurf. Do not use for prompt tuning without a skill package change or for editing only one generated mirror."
+metadata:
+  provenance:
+    source: "https://github.com/anthropics/skills/tree/main/skills/skill-creator"
+    snapshot: "Adapted from the local Codex system skill on 2026-03-06"
+  maintenance: "Pinned snapshot; refresh manually when upstream changes are intentionally adopted."
+---
+
+# Skill Authoring
+
+## Overview
+
+Use this skill to create or repair Foundry skills from the canonical source layer. It is adapted from Anthropic's `skill-creator`, but rewritten for Foundry's cross-platform model and packaging rules.
+
+## When to Use
+
+- Creating a new skill under `workflows/skills/<id>`
+- Updating `name`, `description`, `metadata`, or `compatibility` in `SKILL.md`
+- Repairing broken `references/`, `steering/`, or `templates/` links
+- Replacing legacy power-file patterns with canonical skill packaging
+- Adapting a skill so its generated Codex, Antigravity, Copilot, Cursor, and Windsurf bundles stay valid
+- Adding or updating helper scripts that make a skill deterministic and reusable
+
+## When Not to Use
+
+- Pure prompt tuning with no skill package changes
+- Editing only a generated mirror when the canonical source is unchanged
+- General feature work that should route to an implementation, review, or domain skill instead
+
+## Core Workflow
+
+1. Clarify the trigger boundary and package scope with concrete examples.
+2. Edit the canonical skill only. Never hand-edit platform mirrors first.
+3. Keep `SKILL.md` concise and move variant detail into one-level-deep sidecar files.
+4. Add scripts only when they remove repetition or make execution more reliable.
+5. Validate frontmatter, links, sidecar content, and platform packaging before finishing.
+6. Regenerate mirrors and rule assets, then verify the skill is discoverable and readable at runtime.
+
+## Foundry Skill Contract
+
+- Required file: `SKILL.md`
+- Optional folders: `references/`, `steering/`, `templates/`, `scripts/`, `assets/`
+- Keep only `SKILL.md` at the skill root. Do not leave extra top-level markdown files.
+- Use relative paths from the skill root, not platform-specific absolute paths.
+- Reference files must be loaded selectively with explicit `Load when` guidance.
+- Do not ship legacy power files in canonical or platform-facing skill bundles.
+- Canonical metadata can stay richer, but platform mirrors are generated and sanitized automatically.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/foundry-platform-parity.md` | Adapting a skill for Codex, Antigravity, Copilot, Cursor, or Windsurf packaging and metadata rules. |
+| `references/foundry-skill-checklist.md` | Verifying naming, frontmatter, sidecars, routing, and validation before shipping a skill update. |
+
+## Helper Scripts
+
+Load or run only when the task needs them.
+
+| File | Load when |
+| --- | --- |
+| `scripts/init_skill.py` | Scaffolding a new canonical skill directory and starter `SKILL.md`. |
+| `scripts/quick_validate.py` | Checking frontmatter, broken markdown references, empty sidecars, and packaging safety for a skill directory. |
+
+## Rules
+
+- Prefer one canonical skill package that generates clean mirrors on every platform.
+- Keep references one level deep from `SKILL.md`.
+- Never bulk-load `references/` or `steering/`; pick only the file needed for the current step.
+- If a task is clearly about skill creation or maintenance, load this skill directly instead of starting with `skill_search`.
+- When cross-platform behavior changes, verify the generated outputs instead of assuming canonical text alone is enough.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/skill-authoring/references/foundry-platform-parity.md

@@ -0,0 +1,50 @@
+# Foundry Platform Parity
+
+Use this reference when a skill has to work cleanly across generated platform bundles.
+
+## Canonical Authoring Rule
+
+- Author the real skill only under `workflows/skills/<id>`.
+- Generated mirrors are derived artifacts, not the source of truth.
+- If a mirror looks wrong, fix the canonical skill or the generator, then regenerate.
+
+## Packaging Rules
+
+- Keep `SKILL.md` as the only top-level markdown entry file.
+- Place sidecars under `references/`, `steering/`, or `templates/`.
+- Do not keep `POWER.md` in canonical skills or mirrored bundles.
+- Keep links relative to the skill root so the same content survives mirror relocation.
+
+## Platform Notes
+
+### Codex
+
+- Full canonical skill content is mirrored into `.agents/skills`.
+- Compatibility wrappers may exist for workflows and agents, but skills remain normal packages.
+
+### Antigravity
+
+- Skills are mirrored into `.agent/skills`.
+- Route-first rule text still expects the same `SKILL.md` plus selective sidecar loading.
+
+### Copilot
+
+- Copilot-facing skills must keep only supported frontmatter keys after sanitization.
+- The canonical skill may keep richer `metadata`, but the generated mirror should rely on Foundry's sanitization rather than hand-authored Copilot-only fields.
+- Workspace MCP should stay in `.vscode/mcp.json`.
+
+### Cursor and Windsurf
+
+- These mirrors follow the same filtered bundle rules as Copilot.
+- Duplicate top-level markdown files and stale sidecars will show up here too if the canonical package is sloppy.
+
+## Metadata Guidance
+
+- Required everywhere: `name`, `description`
+- Allowed canonical extensions: `license`, `allowed-tools`, `metadata`, `compatibility`
+- Keep the trigger boundary in `description` sharp enough that route-first loading can direct-load the skill when intent is obvious.
+
+## Routing Guidance
+
+- Do not create platform-specific aliases just to shadow a built-in skill.
+- If a built-in name collides with a Foundry skill, prefer a distinct canonical ID and route authoring intent to it explicitly.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/skill-authoring/references/foundry-skill-checklist.md

@@ -0,0 +1,45 @@
+# Foundry Skill Checklist
+
+Use this checklist before finishing a skill creation or maintenance task.
+
+## Canonical Package
+
+- Skill folder name is lowercase hyphen-case and under 64 characters.
+- `SKILL.md` exists and has `name` plus `description`.
+- `description` states both when to use the skill and when not to use it.
+- No `POWER.md` exists in the skill directory.
+- No extra top-level markdown files exist besides `SKILL.md`.
+
+## Sidecars
+
+- Every referenced markdown file exists.
+- Referenced markdown files are non-empty.
+- Links are relative from the skill root.
+- `SKILL.md` tells the agent when to load each sidecar instead of listing files without context.
+
+## Scripts
+
+- Only keep scripts that actually remove repetition or improve reliability.
+- Scripts should prefer standard-library dependencies when possible.
+- Script usage is described briefly in `SKILL.md`.
+
+## Routing and Generation
+
+- If the skill changes route behavior, update shared workflow or agent guidance too.
+- Do not edit platform mirrors directly unless the task is fixing the generator itself.
+- Regenerate mirrors and rule assets after canonical changes.
+
+## Validation
+
+Run the smallest relevant validation set:
+
+- `python workflows/skills/<id>/scripts/quick_validate.py workflows/skills/<id>`
+- `npm run test:attributes`
+- `npm run generate:platform-assets`
+- `npm run sync:skill-mirrors`
+
+If the task changes MCP or runtime routing:
+
+- `npm --prefix mcp test`
+- `npm --prefix mcp run build`
+- `node scripts/mcp-http-smoke.mjs <mcp-url>` when a live endpoint is available

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/skill-authoring/scripts/init_skill.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Scaffold a new Foundry canonical skill.
+
+Usage:
+  python init_skill.py <skill-name> [--path workflows/skills] [--resources scripts,references]
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ALLOWED_RESOURCES = {"scripts", "references", "steering", "templates", "assets"}
+MAX_SKILL_NAME_LENGTH = 64
+
+
+def normalize_skill_name(raw_name: str) -> str:
+    normalized = re.sub(r"[^a-z0-9]+", "-", raw_name.strip().lower())
+    normalized = re.sub(r"-{2,}", "-", normalized).strip("-")
+    return normalized
+
+
+def title_case(skill_name: str) -> str:
+    return " ".join(part.capitalize() for part in skill_name.split("-") if part)
+
+
+def parse_resources(raw_resources: str) -> list[str]:
+    if not raw_resources:
+        return []
+    resources = []
+    seen = set()
+    for item in raw_resources.split(","):
+        value = item.strip()
+        if not value:
+            continue
+        if value not in ALLOWED_RESOURCES:
+            allowed = ", ".join(sorted(ALLOWED_RESOURCES))
+            raise SystemExit(f"Unknown resource type '{value}'. Allowed: {allowed}")
+        if value not in seen:
+            resources.append(value)
+            seen.add(value)
+    return resources
+
+
+def skill_template(skill_name: str) -> str:
+    skill_title = title_case(skill_name)
+    return f"""---
+name: "{skill_name}"
+description: "Use when [TODO: describe the task trigger, expected files or outputs, and clear non-goals]."
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: Add a short description of what this skill enables.]
+
+## When to Use
+
+- [TODO]
+
+## When Not to Use
+
+- [TODO]
+
+## Core Workflow
+
+1. [TODO]
+2. [TODO]
+3. [TODO]
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/example.md` | Replace or remove this row after creating real sidecar docs. |
+
+## Rules
+
+- Keep `SKILL.md` concise and move detailed variants to sidecar files.
+- Keep links relative to the skill root.
+- Do not add `POWER.md`.
+"""
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Scaffold a Foundry canonical skill")
+    parser.add_argument("skill_name", help="Requested skill name")
+    parser.add_argument(
+        "--path",
+        default="workflows/skills",
+        help="Root directory that will contain the new skill",
+    )
+    parser.add_argument(
+        "--resources",
+        default="references",
+        help="Comma-separated optional folders to create",
+    )
+    args = parser.parse_args()
+
+    skill_name = normalize_skill_name(args.skill_name)
+    if not skill_name:
+        raise SystemExit("Skill name normalized to an empty value")
+    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
+        raise SystemExit(
+            f"Skill name '{skill_name}' is too long ({len(skill_name)} > {MAX_SKILL_NAME_LENGTH})"
+        )
+
+    target_root = Path(args.path).resolve()
+    skill_dir = target_root / skill_name
+    if skill_dir.exists():
+        raise SystemExit(f"Target skill already exists: {skill_dir}")
+
+    resources = parse_resources(args.resources)
+    skill_dir.mkdir(parents=True, exist_ok=False)
+    (skill_dir / "SKILL.md").write_text(skill_template(skill_name), encoding="utf8")
+
+    for resource in resources:
+        resource_dir = skill_dir / resource
+        resource_dir.mkdir(parents=True, exist_ok=True)
+        if resource == "references":
+            (resource_dir / "example.md").write_text(
+                "# Example Reference\n\nReplace or remove this file once you add real sidecar documentation.\n",
+                encoding="utf8",
+            )
+
+    print(f"[OK] Created skill scaffold: {skill_dir}")
+    print("[NEXT] Replace TODO sections in SKILL.md")
+    print("[NEXT] Add real sidecar files or remove placeholder reference rows")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/skill-authoring/scripts/quick_validate.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Validate a Foundry skill package without external dependencies.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+MAX_SKILL_NAME_LENGTH = 64
+ALLOWED_KEYS = {
+    "name",
+    "description",
+    "license",
+    "allowed-tools",
+    "metadata",
+    "compatibility",
+}
+SIDECAR_DIRS = {"references", "steering", "templates"}
+
+
+def extract_frontmatter(markdown: str):
+    match = re.match(r"^---\n(.*?)\n---\n?", markdown, re.DOTALL)
+    if not match:
+        return None, markdown
+    return match.group(1), markdown[match.end():]
+
+
+def parse_top_level_keys(frontmatter: str):
+    keys = []
+    values = {}
+    for line in frontmatter.splitlines():
+        if not line or line.startswith((" ", "\t")):
+            continue
+        match = re.match(r"^([A-Za-z0-9_-]+)\s*:\s*(.*)$", line)
+        if not match:
+            continue
+        key = match.group(1)
+        raw_value = match.group(2).strip()
+        keys.append(key)
+        values[key] = raw_value.strip("\"'")
+    return keys, values
+
+
+def extract_markdown_targets(markdown: str):
+    stripped = re.sub(r"```[\s\S]*?```", "", markdown)
+    return [match.group(1).strip() for match in re.finditer(r"\[[^\]]+\]\(([^)]+)\)", stripped)]
+
+
+def validate(skill_dir: Path):
+    errors = []
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        return ["SKILL.md not found"]
+
+    content = skill_md.read_text(encoding="utf8")
+    frontmatter, _body = extract_frontmatter(content)
+    if not frontmatter:
+        return ["SKILL.md is missing YAML frontmatter"]
+
+    keys, values = parse_top_level_keys(frontmatter)
+    unexpected = sorted(set(keys) - ALLOWED_KEYS)
+    if unexpected:
+        errors.append(
+            "Unexpected frontmatter keys: " + ", ".join(unexpected)
+        )
+
+    name = values.get("name", "").strip()
+    description = values.get("description", "").strip()
+    if not name:
+        errors.append("Missing name in frontmatter")
+    elif not re.fullmatch(r"[a-z0-9-]+", name):
+        errors.append("name must be lowercase hyphen-case")
+    elif "--" in name or name.startswith("-") or name.endswith("-"):
+        errors.append("name cannot start/end with '-' or contain consecutive hyphens")
+    elif len(name) > MAX_SKILL_NAME_LENGTH:
+        errors.append(
+            f"name is too long ({len(name)} > {MAX_SKILL_NAME_LENGTH})"
+        )
+
+    if not description:
+        errors.append("Missing description in frontmatter")
+
+    if (skill_dir / "POWER.md").exists():
+        errors.append("POWER.md must not exist")
+
+    top_level_markdown = sorted(
+        item.name
+        for item in skill_dir.iterdir()
+        if item.is_file() and item.suffix == ".md"
+    )
+    extras = [name for name in top_level_markdown if name != "SKILL.md"]
+    if extras:
+        errors.append(
+            "Extra top-level markdown files found: " + ", ".join(extras)
+        )
+
+    markdown_files = [skill_md]
+    for folder_name in SIDECAR_DIRS:
+        folder = skill_dir / folder_name
+        if not folder.exists():
+            continue
+        markdown_files.extend(sorted(folder.rglob("*.md")))
+
+    for markdown_file in markdown_files:
+        text = markdown_file.read_text(encoding="utf8")
+        if markdown_file != skill_md and not text.strip():
+            errors.append(f"{markdown_file.relative_to(skill_dir)} is empty")
+        for target in extract_markdown_targets(text):
+            if target.startswith(("http://", "https://", "#", "mailto:", "/")):
+                continue
+            target_path = (markdown_file.parent / target.split("#")[0].split("?")[0]).resolve()
+            if not target_path.exists():
+                errors.append(
+                    f"{markdown_file.relative_to(skill_dir)} references missing file {target}"
+                )
+                continue
+            if target_path.suffix == ".md" and not target_path.read_text(encoding="utf8").strip():
+                errors.append(
+                    f"{markdown_file.relative_to(skill_dir)} references empty markdown file {target}"
+                )
+
+    return errors
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        return 1
+
+    skill_dir = Path(sys.argv[1]).resolve()
+    if not skill_dir.exists() or not skill_dir.is_dir():
+        print(f"Skill directory not found: {skill_dir}")
+        return 1
+
+    errors = validate(skill_dir)
+    if errors:
+        print("Skill validation failed:")
+        for item in errors:
+            print(f"- {item}")
+        return 1
+
+    print("Skill is valid.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())