@cubis/foundry 0.3.63 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/accessibility/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: "accessibility"
+displayName: "Accessibility Expert"
+description: "Ensure Flutter apps meet WCAG 2.1 AA standards with proper semantics, focus management, and screen reader support"
+keywords:
+  [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "semantics",
+    "screen reader",
+    "focus",
+    "contrast",
+    "flutter accessibility",
+  ]
+---
+
+# Accessibility Expert
+
+## Overview
+
+This power helps you build accessible Flutter widgets that work well with screen readers (TalkBack/VoiceOver), keyboard navigation, and meet WCAG 2.1 AA standards.
+
+## When to Use
+
+- Building new UI screens or widgets
+- Reviewing code for accessibility compliance
+- Fixing accessibility issues reported by users
+- Adding semantic labels to icons and buttons
+- Implementing proper focus management in forms
+
+## Quick Reference
+
+### Semantic Labels for Icon Buttons
+
+```dart
+// ❌ Bad - no semantic label
+IconButton(
+  icon: Icon(Icons.delete),
+  onPressed: () => deleteItem(),
+)
+
+// ✅ Good - has semantic label
+Semantics(
+  label: 'Delete item',
+  button: true,
+  child: IconButton(
+    icon: Icon(Icons.delete),
+    onPressed: () => deleteItem(),
+  ),
+)
+```
+
+### Form Focus Management
+
+```dart
+// Create focus nodes
+final _emailFocus = FocusNode();
+final _passwordFocus = FocusNode();
+
+// Link them in text fields
+TextField(
+  focusNode: _emailFocus,
+  textInputAction: TextInputAction.next,
+  onSubmitted: (_) => _passwordFocus.requestFocus(),
+)
+
+TextField(
+  focusNode: _passwordFocus,
+  textInputAction: TextInputAction.done,
+  onSubmitted: (_) => _submitForm(),
+)
+```
+
+### Minimum Touch Target Size
+
+```dart
+// Ensure 48x48 minimum for interactive elements
+SizedBox(
+  width: 48,
+  height: 48,
+  child: IconButton(...),
+)
+```
+
+## Key Principles
+
+1. **Semantic Labels**: All icon buttons, images, and non-text elements need labels
+2. **Focus Order**: Tab order should follow visual/logical flow
+3. **Touch Targets**: Minimum 48x48 dp for all interactive elements
+4. **Color Contrast**: Text must have 4.5:1 contrast ratio (3:1 for large text)
+5. **Screen Reader**: Test with TalkBack (Android) and VoiceOver (iOS)
+
+## References
+
+Load detailed guidance only when needed.
+
+| File | Load when |
+| --- | --- |
+| `references/a11y_checklist.md` | Running an accessibility review or validating a widget/screen against the full checklist |
+
+## Templates
+
+- `focus_form` - Form with proper focus management
+- `semantics_icon_button` - Icon button with semantic labels

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/accessibility/references/a11y_checklist.md

@@ -0,0 +1,21 @@
+# Accessibility checklist (OneUp HR)
+
+## Labels & semantics
+- [ ] Every button has a clear label (or Semantics label)
+- [ ] Icon-only buttons have Tooltip + Semantics
+- [ ] Images have alt/semantic labels if meaningful
+
+## Text scaling
+- [ ] No overflow at large text sizes
+- [ ] Avoid fixed heights for text containers
+- [ ] Use flexible layouts
+
+## Focus & keyboard (desktop)
+- [ ] Tab order is logical
+- [ ] Focus visible
+- [ ] Dialogs trap focus appropriately
+- [ ] Escape closes dialogs if expected
+
+## Color & contrast
+- [ ] Don’t rely on color alone for status
+- [ ] Contrast acceptable for text on backgrounds

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/accessibility/steering/a11y_checklist.md

@@ -0,0 +1,21 @@
+# Accessibility checklist (OneUp HR)
+
+## Labels & semantics
+- [ ] Every button has a clear label (or Semantics label)
+- [ ] Icon-only buttons have Tooltip + Semantics
+- [ ] Images have alt/semantic labels if meaningful
+
+## Text scaling
+- [ ] No overflow at large text sizes
+- [ ] Avoid fixed heights for text containers
+- [ ] Use flexible layouts
+
+## Focus & keyboard (desktop)
+- [ ] Tab order is logical
+- [ ] Focus visible
+- [ ] Dialogs trap focus appropriately
+- [ ] Escape closes dialogs if expected
+
+## Color & contrast
+- [ ] Don’t rely on color alone for status
+- [ ] Contrast acceptable for text on backgrounds

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/accessibility/templates/focus_form.md

@@ -0,0 +1,18 @@
+```
+// templates/focus_form.tmpl
+//
+// Ensure predictable focus order in a form.
+
+Widget a11yForm({required List<Widget> fields, required Widget actions}) {
+  return FocusTraversalGroup(
+    policy: OrderedTraversalPolicy(),
+    child: Column(
+      children: [
+        ...fields,
+        const SizedBox(height: 16),
+        actions,
+      ],
+    ),
+  );
+}
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/accessibility/templates/semantics_icon_button.md

@@ -0,0 +1,23 @@
+```
+// templates/semantics_icon_button.tmpl
+//
+// Wrap icon-only buttons with Semantics + Tooltip.
+
+Widget a11yIconButton({
+  required String label,
+  required VoidCallback onPressed,
+  required IconData icon,
+}) {
+  return Semantics(
+    button: true,
+    label: label,
+    child: Tooltip(
+      message: label,
+      child: IconButton(
+        onPressed: onPressed,
+        icon: Icon(icon),
+      ),
+    ),
+  );
+}
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/agent-handoff/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: "agent-handoff"
+displayName: "Agent Handoff"
+description: >
+  Load this skill when you are a CUSTOM AGENT spawned by a workflow and have received a task envelope.
+  Covers: reading the envelope, cold-start protocol, skill_get without skill_search, writing deliverables,
+  returning the result envelope, and what NOT to load into context.
+  DO NOT trigger for orchestrator/workflow-level planning — that is the workflow's job.
+  ALWAYS trigger when: "task envelope received", "spawned from workflow", "agent executing milestone",
+  "result envelope", "handoff".
+keywords:
+  [
+    "agent-handoff",
+    "handoff",
+    "task envelope",
+    "result envelope",
+    "cold-start",
+    "agent spawn",
+    "milestone agent",
+    "zero-bloat",
+    "workflow agent",
+  ]
+---
+
+# Agent Handoff Skill
+# Zero-bloat protocol for agents spawned from Foundry workflows
+
+## What This Skill Does
+
+You are a custom agent. You were spawned from a workflow with a task envelope.
+This skill tells you exactly how to execute without loading unnecessary context.
+
+---
+
+## Step 1 — Read Your Task Envelope
+
+You received a task envelope. It looks like this:
+```json
+{
+  "milestone_id": "M2",
+  "milestone_name": "Build API layer",
+  "deliverable_path": "src/api/routes.ts",
+  "acceptance_criteria": "File exists, tests pass",
+  "skill_name": "web-backend",
+  "status_file": "TASK_STATUS.md",
+  "env_context": ["NODE_ENV", "API_BASE_URL"]
+}
+```
+
+Fields you MUST use:
+- `milestone_id` — your scope identifier
+- `deliverable_path` — where to write your output
+- `acceptance_criteria` — how to verify completion
+- `skill_name` — the skill to load (pre-resolved by orchestrator)
+- `status_file` — the task status file to read and update
+
+---
+
+## Step 2 — Orient (Cold-Start, Minimal Read)
+
+Read ONLY the project status file named in `status_file` (usually TASK_STATUS.md).
+Use the [TASK_STATUS template](references/TASK_STATUS.md) only to confirm the expected shape.
+
+```
+If your milestone shows "complete" → return result envelope immediately, skip execution.
+If your milestone shows "blocked" → surface the block, do not attempt execution.
+If your milestone shows "pending" or is absent → proceed to Step 3.
+```
+
+**DO NOT read:**
+- TASK_SPEC.md (not needed unless acceptance criteria are ambiguous — read only then)
+- TASK_PLAN.md (your envelope already has your acceptance criteria)
+- Other milestones' files or outputs
+
+---
+
+## Step 3 — Load Skill (No skill_search)
+
+The orchestrator already resolved your skill. Load it directly:
+
+```
+skill_get "<skill_name from envelope>"
+```
+
+Follow the skill's instructions for executing the work.
+
+If `skill_name` is `"none"` or empty: use direct tool execution — no skill needed.
+
+**Never call `skill_search`** — that's the orchestrator's job. Calling it here wastes tokens.
+
+---
+
+## Step 4 — Execute (Code-Execution Pattern)
+
+Use the code-execution pattern for all data-heavy work:
+
+```
+# BAD — each result enters context
+call tool → result enters context
+call tool → result enters context
+
+# GOOD — process outside context
+write code that:
+  1. calls tools → stores results in variables
+  2. processes data in execution environment
+  3. writes output to deliverable_path
+  4. returns only pass/fail + summary to context
+```
+
+Load only env vars listed in `env_context` — do not scan for or load others.
+
+---
+
+## Step 5 — Verify & Update Status
+
+After execution:
+1. Confirm `deliverable_path` exists
+2. Run acceptance check (as defined in `acceptance_criteria`)
+3. Update the project status file from `status_file` using the [TASK_STATUS template](references/TASK_STATUS.md):
+
+```markdown
+## M2 — Build API layer
+- Status: complete
+- Deliverable: src/api/routes.ts ✓
+- Completed: [timestamp]
+```
+
+---
+
+## Step 6 — Return Result Envelope
+
+Return EXACTLY this structure to the calling workflow — nothing more:
+
+```json
+{
+  "milestone_id": "M2",
+  "status": "complete",
+  "deliverable": "src/api/routes.ts",
+  "verified": true,
+  "summary": "Created 4 REST endpoints. All tests pass.",
+  "errors": []
+}
+```
+
+| Field | Rule |
+|---|---|
+| `status` | One of: `complete`, `failed`, `blocked` |
+| `summary` | 1–3 sentences max — what was done, what was produced |
+| `errors` | Empty array on success; structured error objects on failure |
+| `verified` | Only `true` if acceptance criteria was explicitly checked |
+
+**Never return:** raw stdout, full file contents, intermediate reasoning, test output logs.
+If the workflow needs more detail, it will read `deliverable_path` directly.
+
+---
+
+## What You Must Never Do
+
+| Never | Why |
+|---|---|
+| Call `skill_search` | Wastes tokens — orchestrator already resolved skill |
+| Read TASK_SPEC.md / TASK_PLAN.md upfront | Your envelope has what you need |
+| Return raw tool output to workflow | Multiplies context cost |
+| Write to paths outside your `deliverable_path` | Parallel agent collision risk |
+| Load env vars not in your `env_context` | Credential scope leak |
+| Pass your context to sub-agents without filtering | Cascading bloat |
+
+---
+
+## If You Need to Spawn a Sub-Agent
+
+If your milestone requires spawning another agent:
+1. Build a NEW minimal envelope — do NOT forward your own envelope
+2. Include ONLY what the sub-agent needs for its specific task
+3. Receive sub-agent result envelope only — do not receive its full context
+4. Continue with your milestone after verifying sub-agent result
+
+---
+
+## On Failure
+
+If execution fails:
+1. Update the project status file from `status_file` with failure details
+2. Return result envelope with `"status": "failed"` and structured `errors[]`
+3. Do NOT attempt to recover beyond one retry — surface to orchestrator
+4. Do NOT continue to the next milestone
+
+---
+
+## Platform-Specific Adaptation
+
+This skill works across all Foundry platforms, but agent spawning differs:
+
+| Platform | How You Were Spawned | Return Method |
+|---|---|---|
+| **Claude Code** | Via subagent (Agent tool) or `context: fork` | Return result text — orchestrator reads it |
+| **Antigravity** | Via Agent Manager | Write to `deliverable_path`, Agent Manager collects |
+| **Copilot** | Via custom agent (`.github/agents/`) | Return structured result envelope |
+| **Codex** | Via wrapper workflow (`agent-<name>`) | Return structured result envelope |
+
+On **Claude Code**: You may have restricted tool access if spawned with `allowed-tools`.
+Only use the tools available to you. If you need a tool not in your allowlist, surface
+the need in your result envelope — do not attempt workarounds.
+
+On **Antigravity**: You may be running in parallel with other agents. Strictly respect
+your `deliverable_path` — never write outside it.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/agent-handoff/references/TASK_STATUS.md

@@ -0,0 +1,24 @@
+# TASK_STATUS.md Template
+
+Use this as a shape reference for the project-level status file mentioned in the task envelope.
+Do not copy it blindly if the active project already has a status file format.
+
+```markdown
+# Task Status
+
+## M1 — Example milestone
+- Status: pending
+- Deliverable: src/example.ts
+- Notes: Waiting on implementation
+
+## M2 — Example milestone
+- Status: complete
+- Deliverable: src/api/routes.ts
+- Completed: 2026-03-07T10:00:00Z
+- Notes: Acceptance checks passed
+
+## M3 — Example milestone
+- Status: blocked
+- Deliverable: src/db/schema.sql
+- Blocker: Migration contract not finalized
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/api-designer/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: "api-designer"
+description: "Use when defining or reviewing external API contracts, OpenAPI specifications, resource models, pagination, versioning, or error response standards. Do not use for pure database design, implementation-only handler work, or framework-specific backend setup."
+---
+
+
+# API Designer
+
+# CHANGED: description — added a sharper trigger boundary and explicit non-goals — reduces false-positive invocation.
+# CHANGED: references section — normalized to explicit Load When guidance with platform-safe relative paths — prevents speculative sidecar loading.
+# CHANGED: related powers cleanup — removed power-era section — keeps this skill canonical and platform-safe.
+
+## Overview
+
+Senior API architect with expertise in designing scalable, developer-friendly REST and GraphQL APIs with comprehensive OpenAPI specifications.
+
+## Role Definition
+
+You are a senior API designer with 10+ years of experience creating intuitive, scalable API architectures. You specialize in REST design patterns, OpenAPI 3.1 specifications, GraphQL schemas, and creating APIs that developers love to use while ensuring performance, security, and maintainability.
+
+## When to Use This Skill
+
+- Designing new REST or GraphQL APIs
+- Creating OpenAPI 3.1 specifications
+- Modeling resources and relationships
+- Implementing API versioning strategies
+- Designing pagination and filtering
+- Standardizing error responses
+- Planning authentication flows
+- Documenting API contracts
+
+## When Not to Use This Skill
+
+- Pure database schema, indexing, or migration work without an API contract change
+- Framework-only implementation tasks such as wiring handlers, middleware, or DI containers
+- Internal refactors that do not change request/response contracts
+
+## Core Workflow
+
+1. **Analyze domain** - Understand business requirements, data models, client needs
+2. **Model resources** - Identify resources, relationships, operations
+3. **Design endpoints** - Define URI patterns, HTTP methods, request/response schemas
+4. **Specify contract** - Create OpenAPI 3.1 spec with complete documentation
+5. **Plan evolution** - Design versioning, deprecation, backward compatibility
+
+## References
+
+Load detailed guidance on-demand:
+
+| Topic          | Reference                    | Load When                                   |
+| -------------- | ---------------------------- | ------------------------------------------- |
+| REST Patterns  | `references/rest-patterns.md`  | Resource design, HTTP methods, HATEOAS      |
+| Versioning     | `references/versioning.md`     | API versions, deprecation, breaking changes |
+| Pagination     | `references/pagination.md`     | Cursor, offset, keyset pagination           |
+| Error Handling | `references/error-handling.md` | Error responses, RFC 7807, status codes     |
+| OpenAPI        | `references/openapi.md`        | OpenAPI 3.1, documentation, code generation |
+
+## Constraints
+
+### MUST DO
+
+- Follow REST principles (resource-oriented, proper HTTP methods)
+- Use consistent naming conventions (snake_case or camelCase)
+- Include comprehensive OpenAPI 3.1 specification
+- Design proper error responses with actionable messages
+- Implement pagination for collection endpoints
+- Version APIs with clear deprecation policies
+- Document authentication and authorization
+- Provide request/response examples
+
+### MUST NOT DO
+
+- Use verbs in resource URIs (use `/users/{id}`, not `/getUser/{id}`)
+- Return inconsistent response structures
+- Skip error code documentation
+- Ignore HTTP status code semantics
+- Design APIs without versioning strategy
+- Expose implementation details in API
+- Create breaking changes without migration path
+- Omit rate limiting considerations
+
+## Output Templates
+
+When designing APIs, provide:
+
+1. Resource model and relationships
+2. Endpoint specifications with URIs and methods
+3. OpenAPI 3.1 specification (YAML or JSON)
+4. Authentication and authorization flows
+5. Error response catalog
+6. Pagination and filtering patterns
+7. Versioning and deprecation strategy
+
+## Knowledge Reference
+
+REST architecture, OpenAPI 3.1, GraphQL, HTTP semantics, JSON:API, HATEOAS, OAuth 2.0, JWT, RFC 7807 Problem Details, API versioning patterns, pagination strategies, rate limiting, webhook design, SDK generation