@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/shared/rules/STEERING.md

@@ -1,4 +1,4 @@
-# Cubis Foundry — Shared Steering Protocol
+# Cubis Foundry - Shared Steering Protocol
 
 This is the canonical steering source for routing policy and managed MCP block language.
 Keep platform rule files aligned with this template plus per-platform overrides, and do not duplicate the managed block into agent or workflow markdown.
@@ -9,7 +9,7 @@ Managed-block sync: `npm run inject:mcp-rules:all` (or `cbx workflows sync-rules
 
 ## 1) Route Resolution
 
-Follow this decision tree for EVERY user request:
+Follow this decision tree for every user request:
 
 ```
 ┌─ User request arrives
@@ -19,64 +19,76 @@ Follow this decision tree for EVERY user request:
 │   └─ Honor that route first. Stop.
 ├─ Did user explicitly name an exact skill ID?
 │   └─ Run skill_validate on that exact ID.
-│       ├─ Valid? → Load it and proceed. Stop.
-│       └─ Invalid/unavailable? → Fall through. Do not guess.
+│       ├─ Valid? -> Load it and proceed. Stop.
+│       └─ Invalid/unavailable? -> Fall through. Do not guess.
+├─ Is it explicit Stitch UI generation, screen editing, or "use Stitch" work?
+│   └─ Prefer /design-screen first. Resolve design state, then run the Stitch sequence only if still needed. Stop.
+├─ Is it explicit UI/UX/design-system work?
+│   └─ Prefer `/design-system`, `/design-screen`, `/design-audit`, or `/design-refresh` based on intent. Stop.
 ├─ Is it non-trivial work with requirements, traceability, or spec language?
-│   └─ Prefer /spec unless the user already chose another valid route. Stop.
-├─ Is it architecture, design-system, ADR, or structure-governance work?
-│   └─ Prefer /architecture unless the user already chose another valid route. Stop.
-├─ Is it multi-step work in ONE domain?
-│   └─ Pick the best-fit workflow. Load it. Stop.
+│   └─ Prefer /plan unless the user already chose another valid route. Stop.
+├─ Is it bug, error, or failing test investigation?
+│   └─ Prefer /debug. Stop.
+├─ Is it test, coverage, or verification work?
+│   └─ Prefer /test. Stop.
+├─ Is it review or security audit work?
+│   └─ Prefer /review. Stop.
+├─ Is it deployment, CI/CD, Docker, or infra work?
+│   └─ Prefer /deploy. Stop.
+├─ Is it bounded iterative work that needs a hard stop condition?
+│   └─ Prefer /loop. Stop.
+├─ Is it multi-step work in one domain?
+│   └─ Pick the best-fit workflow and load it. Stop.
 ├─ Is it cross-domain work spanning 2+ specialties?
-│   └─ Use /orchestrate or @orchestrator. Stop.
+│   └─ Use @orchestrator. Stop.
+├─ Is it documentation-only or a repo knowledge refresh?
+│   └─ Use /implement with a docs-focused scope, or /plan if only scoping is needed. Stop.
 ├─ None of the above?
-│   └─ Use route_resolve MCP tool → follow its recommendation.
-│       └─ Still unclear? → ONE narrow skill_search. Stop.
-└─ If every route fails → ask the user to clarify.
+│   └─ Use route_resolve MCP tool, then follow its recommendation.
+│       └─ Still unclear? -> ONE narrow skill_search. Stop.
+└─ If every route fails -> ask the user to clarify.
 ```
 
-> **Rule:** Inspect the repo and task locally BEFORE choosing a route or loading any skill.
-> **Rule:** If the user already chose the route, do not re-route it unless the named workflow, agent, or skill is invalid.
-> **Rule:** For non-trivial work, read `docs/foundation/MEMORY.md` first when it exists. Then load `docs/foundation/PRODUCT.md`, `ENGINEERING_RULES.md`, `docs/foundation/ARCHITECTURE.md`, `docs/foundation/TECH.md`, `docs/foundation/memory/*.md`, and ADRs only as needed. Use the MEMORY load map to decide which deeper docs the active workflow, agent, or skill should consult.
+> **Rule:** Inspect the repo and task locally before choosing a route or loading any skill.
+> **Rule:** If the user already chose the route, do not reroute it unless the named workflow, agent, or skill is invalid.
+> **Rule:** For non-trivial work, read `docs/foundation/MEMORY.md` first when it exists. Then load `docs/foundation/PRODUCT.md`, `ENGINEERING_RULES.md`, `docs/foundation/ARCHITECTURE.md`, `docs/foundation/TECH.md`, `docs/foundation/memory/*.md`, and ADRs only as needed.
 
 ---
 
 ## 2) Layer Reference
 
-| Layer                | What it is                            | When to use it                                        | How to invoke                              | Example                                     |
-| -------------------- | ------------------------------------- | ----------------------------------------------------- | ------------------------------------------ | ------------------------------------------- |
-| **Direct execution** | No routing needed                     | Small, clear, single-step tasks                       | Just do it                                 | "rename this variable"                      |
-| **Workflow**         | Multi-step recipe with verification   | Structured task with known pattern                    | `/plan`, `/create`, `/debug`, `/test`      | "plan the auth system"                      |
-| **Agent**            | Specialist persona with domain skills | Domain expertise needed for execution                 | `@backend-specialist`, `@security-auditor` | "design the API schema"                     |
-| **Named skill**      | Exact skill selected by the user      | User already named the skill and it validates cleanly | `skill_validate` → `skill_get`             | "use stitch for this screen"                |
-| **Skill (MCP)**      | Supporting domain knowledge           | Domain context that a workflow or agent doesn't cover | `skill_get` after `skill_validate`         | loading `typescript-pro` for TS conventions |
-| **skill_search**     | Fuzzy discovery tool                  | Domain unclear, no skill ID known yet                 | One narrow search AFTER route_resolve      | "what skill covers Prisma?"                 |
-| **route_resolve**    | Intent → route mapper                 | Free-text request doesn't match any known route       | MCP tool call with task description        | "I need to optimize my database"            |
-| **Orchestrator**     | Multi-specialist coordinator          | Work genuinely spans 2+ domains                       | `/orchestrate` or `@orchestrator`          | "build full-stack feature with auth"        |
-| **Spec workflow**    | Git-tracked spec pack                 | Non-trivial work needs durable scope, acceptance, and traceability | `/spec`                           | "turn this feature into an implementation spec" |
-| **Architecture workflow** | Architecture and design-system memory | Need to refresh structure, flows, ADRs, or design-system rules | `/architecture`                 | "update the clean architecture contract" |
+| Layer | What it is | When to use it | How to invoke | Example |
+| --- | --- | --- | --- | --- |
+| Direct execution | No routing needed | Small, clear, single-step tasks | Just do it | "rename this variable" |
+| Workflow | Multi-step recipe with verification | Structured task with known pattern | `/plan`, `/implement`, `/debug`, `/test`, `/review`, `/deploy`, `/loop`, `/design-system`, `/design-screen`, `/design-audit`, `/design-refresh` | "plan the auth system" |
+| Agent | Specialist persona with domain skills | Domain expertise needed for execution | `@implementer`, `@reviewer` | "design the API schema" |
+| Named skill | Exact skill selected by the user | User already named the skill and it validates cleanly | `skill_validate` -> `skill_get` | "use stitch for this screen" |
+| Skill (MCP) | Supporting domain knowledge | Domain context that a workflow or agent does not cover | `skill_get` after `skill_validate` | loading `typescript-best-practices` |
+| skill_search | Fuzzy discovery tool | Domain unclear, no skill ID known yet | One narrow search after route resolution | "what skill covers Prisma?" |
+| route_resolve | Intent to route mapper | Free-text request does not match any known route | MCP tool call with task description | "I need to optimize my database" |
+| Orchestrator | Multi-specialist coordinator | Work genuinely spans 2+ domains | `@orchestrator` | "build full-stack feature with auth" |
 
 ---
 
 ## 3) Skill Loading Protocol
 
-Skills are **supporting context** unless the user explicitly named the exact skill. In that case validate the named skill first, then proceed without route discovery.
+Skills are supporting context unless the user explicitly named the exact skill. In that case validate the named skill first, then proceed without route discovery.
 
-1. **Never begin with `skill_search`.** Inspect the repo/task locally first.
-2. If the user explicitly named an exact skill ID, run `skill_validate` on that ID before any `route_resolve` call.
-3. Resolve the route (workflow, agent, or direct execution) before loading any non-explicit skills.
-4. **After routing: if `route_resolve` returned `primarySkillHint` or `primarySkills`, load the first via `skill_validate` → `skill_get` before executing. Not optional for non-trivial tasks.**
-5. If `detectedLanguageSkill` is returned and matches the project, load it too (if not already loaded this session).
-6. Domain still unclear after routing? → ONE narrow `skill_search`. Not two.
+1. Never begin with `skill_search`. Inspect the repo and task locally first.
+2. If the user explicitly named an exact skill ID, run `skill_validate` on that ID before any route discovery.
+3. Resolve the route before loading any non-explicit skills.
+4. After routing, if `route_resolve` returned `primarySkillHint` or `primarySkills`, load the first via `skill_validate` -> `skill_get` before executing.
+5. If `detectedLanguageSkill` is returned and matches the project, load it too if not already loaded this session.
+6. Domain still unclear after routing? Use one narrow `skill_search`. Not two.
 7. Call `skill_get` with `includeReferences: false` by default.
-8. Load reference files one at a time with `skill_get_reference` — only when a specific reference is needed.
+8. Load reference files one at a time with `skill_get_reference` only when a specific reference is needed.
 9. Do not auto-prime every specialist. Only load what `primarySkills` recommends or the task clearly needs.
 10. Never pass workflow IDs or agent IDs to skill tools.
-11. For `/architecture` and strict subprocess architecture generation, treat the skill bundle as already resolved. Attach the named skills directly instead of discovering them lazily.
+11. For Stitch UI work, use this order: `frontend-design` -> `frontend-design-core` -> `frontend-design-style-selector` -> `frontend-design-system` / `frontend-design-screen-brief` -> `stitch-prompt-enhancement` -> `stitch-design-system` when Stitch mirror sync is needed -> `stitch-design-orchestrator` -> `stitch-implementation-handoff`.
 
 ---
 
-## 4A) Research Escalation
+## 4) Research Escalation
 
 Use external research only when one of these is true:
 
@@ -86,120 +98,76 @@ Use external research only when one of these is true:
 
 Research source ladder:
 
-1. **Repo/local evidence first** — inspect code, config, docs, tests, and installed artifacts before going outside the workspace.
-2. **Official docs next** — vendor docs, upstream repos, standards, or maintainer documentation are primary evidence.
-3. **Community evidence last** — Reddit, blog posts, issue threads, and forum posts are allowed only as labeled secondary evidence.
+1. Repo/local evidence first.
+2. Official docs next.
+3. Community evidence last, and label it as secondary evidence.
 
 Research output contract:
 
-- **Verified facts** — claims backed by primary sources or local repo evidence.
-- **Secondary/community evidence** — useful but lower-trust signals, clearly labeled.
-- **Gaps / unknowns** — what could not be verified.
-- **Recommended next route** — workflow, agent, or skill to use after research.
+- Verified facts.
+- Secondary/community evidence.
+- Gaps or unknowns.
+- Recommended next route.
 
-When the research result shows a change to product direction, project structure, boundaries, design system, or testing strategy, surface `doc_impact` and recommend `/architecture` or a managed-doc refresh before or after implementation.
+When the research result changes product direction, project structure, boundaries, design system, or testing strategy, surface the impact and recommend the right workflow or a managed-doc refresh.
 
 ---
 
-## 4) Specialists
-
-Use the best specialist first:
-
-| Domain                  | Primary Specialist                           | Supporting               |
-| ----------------------- | -------------------------------------------- | ------------------------ |
-| Backend / API / Data    | `@backend-specialist`, `@database-architect` | `@security-auditor`      |
-| Frontend / UI           | `@frontend-specialist`                       | `@performance-optimizer` |
-| Mobile                  | `@mobile-developer`                          | `@frontend-specialist`   |
-| Security                | `@security-auditor`, `@penetration-tester`   | `@backend-specialist`    |
-| DevOps / Release        | `@devops-engineer`                           | `@sre-engineer`          |
-| Testing / QA            | `@test-engineer`, `@qa-automation-engineer`  | `@debugger`              |
-| Debugging / Performance | `@debugger`, `@performance-optimizer`        | `@test-engineer`         |
-| Research / Exploration  | `@researcher`                                | any specialist           |
-| Validation / Quality    | `@validator`                                 | any specialist           |
-| Cross-domain            | `@orchestrator`                              | delegates to others      |
-| Documentation           | `@documentation-writer`                      | domain specialist        |
-| SEO                     | `@seo-specialist`                            | `@frontend-specialist`   |
-| Game Development        | `@game-developer`                            | varies by engine         |
+## 5) Specialist Map
 
-### Orchestrator Rules
-
-- `@orchestrator` uses the **RUG (Repeat-Until-Good)** pattern: it NEVER implements directly — only delegates to specialists with acceptance criteria and validates output independently.
-- After each specialist delivers, route through `@validator` for independent quality gate before accepting.
-- If validation fails, re-delegate with specific feedback (max 3 iterations).
-- Max 3 re-delegation iterations per specialist per milestone. If limit hit, surface to user.
-
-### Subagent Delegation
-
-- Delegate to subagents only when work genuinely requires domain specialization or parallel execution.
-- Each delegation must include: **goal**, **acceptance criteria**, **output contract**, **scope boundary**.
-- Use background/parallel agents only for independent workstreams with no shared mutable state.
-- Sequential work stays sequential — do not parallelize work that writes to the same files or resources.
-- Set iteration limits (`maxTurns`) to prevent runaway loops.
-
-### Handoff Patterns
-
-- Agents may suggest the next logical agent via handoff chains (e.g., `@debugger` → `@test-engineer`).
-- Handoffs are suggestions, not mandates — the user decides when to follow them.
-- Every handoff preserves the output contract: `milestones`, `gate_status`, `next_handoff`.
+Use the smallest specialist set needed:
 
----
-
-## 5) Memory & Cross-Session Learning
-
-- Key agents (orchestrator, debugger, test-engineer, researcher, project-planner, code-archaeologist) support project memory.
-- Project memory persists debugging patterns, architecture decisions, test strategies, and codebase insights across sessions.
-- Skills loaded into agent context accumulate domain knowledge — do not reload what is already in context.
+| Domain | Primary Specialist | Supporting |
+| --- | --- | --- |
+| Planning / architecture | `@planner` | `@explorer` |
+| Exploration | `@explorer` | `@planner` |
+| Implementation | `@implementer` | `@tester`, `@reviewer` |
+| Debugging | `@debugger` | `@tester` |
+| Testing / QA | `@tester` | `@reviewer` |
+| Code review / security | `@reviewer` | `@implementer` |
+| Cross-domain | `@orchestrator` | delegates as needed |
 
----
-
-## 6) Long-Running and Handoff Work
+### Orchestrator Rules
 
-1. Use `/implement-track` for milestone-based work, resumable execution, or progress checkpoints.
-2. Use `/orchestrate` when multiple specialties need explicit ownership or handoff.
-3. Keep workflow output contracts intact when handing work between specialists — especially `milestones`, `gate_status`, and `next_handoff`.
+- `@orchestrator` uses a repeat-until-good pattern. It delegates, verifies output, and iterates until the acceptance criteria are met.
+- Each delegation must include goal, acceptance criteria, output contract, and scope boundary.
+- Keep iteration caps explicit. Do not run open-ended loops.
+- Sequential work stays sequential. Do not parallelize work that writes to the same files or resources.
 
 ---
 
-## 7) Workflow Quick Reference
-
-| Intent Pattern                          | Workflow           | Primary Agent          |
-| --------------------------------------- | ------------------ | ---------------------- |
-| Build a spec pack with traceability     | `/spec`            | `@project-planner`     |
-| Plan a feature, design, or architecture | `/plan`            | `@project-planner`     |
-| Refresh architecture or design-system docs | `/architecture` | `@project-planner`     |
-| Implement a feature with quality gates  | `/create`          | varies by domain       |
-| Debug a complex issue                   | `/debug`           | `@debugger`            |
-| Write or verify tests                   | `/test`            | `@test-engineer`       |
-| Review code for bugs, security, quality | `/review`          | `@validator`           |
-| Refactor without changing behavior      | `/refactor`        | domain specialist      |
-| Deploy, CI/CD, infrastructure           | `/devops`          | `@devops-engineer`     |
-| Database schema, queries, migrations    | `/database`        | `@database-architect`  |
-| Backend API, services, auth             | `/backend`         | `@backend-specialist`  |
-| Mobile features                         | `/mobile`          | `@mobile-developer`    |
-| Security audit or hardening             | `/security`        | `@security-auditor`    |
-| Multi-milestone tracked work            | `/implement-track` | `@orchestrator`        |
-| Cross-domain coordination               | `/orchestrate`     | `@orchestrator`        |
-| Release preparation                     | `/release`         | `@devops-engineer`     |
-| Accessibility audit                     | `/accessibility`   | `@frontend-specialist` |
-| Framework migration                     | `/migrate`         | domain specialist      |
-| Codebase onboarding                     | `/onboard`         | `@researcher`          |
-| Vercel deployment                       | `/vercel`          | `@vercel-expert`       |
+## 6) Workflow Quick Reference
+
+| Intent Pattern | Workflow | Primary Agent |
+| --- | --- | --- |
+| Plan a feature or architecture | `/plan` | `@explorer` -> `@planner` |
+| Build a feature end-to-end | `/implement` | `@implementer` |
+| Establish or refresh design foundations | `/design-system` | `@planner` -> `@implementer` |
+| Design a screen before generation or implementation | `/design-screen` | `@planner` -> `@implementer` |
+| Audit visual quality and design drift | `/design-audit` | `@reviewer` |
+| Refresh design state after product or UI direction changes | `/design-refresh` | `@implementer` |
+| Debug a complex issue | `/debug` | `@debugger` |
+| Write or improve tests | `/test` | `@tester` |
+| Code review + security audit | `/review` | `@reviewer` |
+| Deploy, CI/CD, infrastructure | `/deploy` | `@planner` -> `@implementer` |
+| Bounded autonomous iteration | `/loop` | `@orchestrator` |
+| Cross-domain coordination | `@orchestrator` | delegates to others |
 
 ---
 
-## 8) Safety and Verification
+## 7) Safety And Verification
 
 1. Do not run destructive actions without explicit user confirmation.
 2. Keep diffs small and reversible when possible.
 3. Verify with focused checks before finalizing.
-4. State what was NOT validated.
+4. State what was not validated.
 5. Use web search only when information may be stale, public comparison matters, or the user explicitly asks.
-6. Prefer official docs first. Treat Reddit/community sources as secondary evidence and label them that way.
-7. If the task changes product direction, project structure, scaling assumptions, or design-system rules, update or flag `PRODUCT.md`, `ARCHITECTURE.md`, `ENGINEERING_RULES.md`, `TECH.md`, and `ROADMAP.md` as needed.
+6. Prefer official docs first. Treat Reddit/community sources as secondary evidence and label them accordingly.
+7. If the task changes product direction, project structure, scaling assumptions, or design-system rules, update or flag the relevant foundation docs as needed.
 
 ---
 
-## 9) Maintenance
+## 8) Maintenance
 
 - Refresh installed rules: `cbx workflows sync-rules --platform {{PLATFORM}} --scope project`
 - Diagnose setup issues: `cbx workflows doctor {{PLATFORM}} --scope project`

package/workflows/workflows/agent-environment-setup/shared/rules/overrides/antigravity.md

@@ -4,15 +4,16 @@
 
 - Rules: `.agents/rules/GEMINI.md`
 - Skills: `.agents/skills/<skill-id>/SKILL.md`
-- Gemini commands: `.gemini/commands/*.toml`
-- Rules file: `GEMINI.md`
+- Agent route commands: `.gemini/commands/*.toml`
+- Rules file: `.agents/rules/GEMINI.md`
+- Hooks: do not ship; no verified native Antigravity hook surface
 
 ## Platform-Specific Routing
 
 Gemini recognizes these additional entry points:
 
 1. **Explicit Gemini command** (`.gemini/commands/*.toml`) — highest priority route.
-2. Foundry compiles `/workflow` and `@agent` routes into command entry points instead of installing undocumented workspace workflow or agent folders.
+2. Foundry compiles `/workflow` and `@agent` specialist routes into command entry points instead of installing undocumented workspace workflow or agent folders.
 3. Standard workflow/agent routing from shared steering.
 
 ## Gemini Commands
@@ -33,3 +34,4 @@ Gemini recognizes these additional entry points:
 - Skills loaded via MCP are supported when the Cubis Foundry MCP server is configured.
 - Gemini supports function calling and tool use natively for code generation and analysis.
 - Keep `.toml` commands focused — one command per task pattern for clean routing.
+- Antigravity remains a Gemini-family compatibility target. Do not claim native agents, subagents, or hooks.

package/workflows/workflows/agent-environment-setup/shared/rules/overrides/claude.md

@@ -2,16 +2,16 @@
 
 ## Platform Paths
 
-- Workflows: `.claude/workflows`
-- Agents: `.claude/agents`
-- Skills: `.claude/skills`
+- Workflow skills: `.claude/skills/<workflow-id>/SKILL.md`
+- Subagents: `.claude/agents/*.md`
+- Skills: `.claude/skills/<skill-id>/SKILL.md`
 - Hook templates: `.claude/hooks`
 - Rules file: `CLAUDE.md`
 - Scoped rules: `.claude/rules/*.md` (with `paths:` frontmatter)
 
 ## Platform-Specific Routing
 
-1. **Explicit workflow, slash command, or subagent** — highest priority route.
+1. **Explicit workflow skill or subagent** — highest priority route.
 2. Standard workflow/agent routing from shared steering.
 
 ## Subagent Delegation
@@ -19,7 +19,7 @@
 - Claude delegates via the `Task` tool — each task spawns an independent agent context.
 - Set `maxTurns` in agent frontmatter to cap iteration depth (default: 25).
 - Use `background: true` for parallel workstreams with no shared mutable state.
-- Key agents have `memory: project` for cross-session learning (orchestrator, debugger, test-engineer, researcher, project-planner, code-archaeologist).
+- Current project-memory agents are `orchestrator` and `planner`; keep long-lived context there instead of inventing deleted specialist memories.
 
 ## Platform Notes
 
@@ -27,5 +27,5 @@
 - Scoped rules in `.claude/rules/*.md` use `paths:` frontmatter for targeted file-pattern matching.
 - Global rules live in `~/.claude/CLAUDE.md` and apply to all projects.
 - Skills with `context: fork` spawn as isolated subagents for research-heavy or exploratory tasks.
-- Optional hook templates in `.claude/hooks/` can reinforce explicit-route honoring and research escalation at `UserPromptSubmit`.
+- Optional hook templates in `.claude/hooks/` are native Claude surfaces wired through `.claude/settings.json`.
 - Use `$ARGUMENTS` in skill content for dynamic parameterization from user queries.

package/workflows/workflows/agent-environment-setup/shared/rules/overrides/codex.md

@@ -6,6 +6,7 @@
 - Skills: `.agents/skills/<skill-id>/SKILL.md`
 - Native subagents: `.codex/agents/*.toml`
 - Rules file: `AGENTS.md`
+- Hook support: experimental only; Foundry does not emit Codex hook files by default
 
 ## Platform-Specific Routing
 
@@ -27,4 +28,5 @@
 - Codex supports three autonomy levels: `suggest` (propose only), `auto-edit` (edit with confirmation), `full-auto` (autonomous execution).
 - Codex operates in a sandboxed environment — destructive operations are inherently limited.
 - Orchestration in Codex is native-subagent-first: delegate through `.codex/agents/*.toml` when the task benefits from a specialist handoff.
+- Codex hook support is tracked as experimental because the project hook config/schema is not yet a verified Foundry install surface.
 - Keep workflow instructions self-contained since network access for external docs may be restricted.

package/workflows/workflows/agent-environment-setup/shared/rules/overrides/copilot.md

@@ -2,38 +2,40 @@
 
 ## Platform Paths
 
-- Agents: `.github/agents`
+- Custom agents: `.github/agents/*.agent.md`
 - Skills: `.github/skills`
-- Rules file: `copilot-instructions.md`
+- Rules file: `.github/copilot-instructions.md`
 - Path-scoped instructions: `.github/instructions/*.instructions.md`
 - Prompt files: `.github/prompts/*.prompt.md`
+- Hooks: `.github/hooks/*.json` plus helper scripts
 - MCP configuration: `.vscode/mcp.json`
 
 ## Platform-Specific Routing
 
-1. **Explicit workflow prompt or `@agent`** — highest priority route.
+1. **Explicit workflow prompt or `@agent` custom agent** — highest priority route.
 2. `/workflow` routes compile into prompt files (`.github/prompts/*.prompt.md`).
 3. Standard workflow/agent routing from shared steering.
 
 ## Agent Handoffs
 
-- Agents with `handoffs:` frontmatter offer guided workflow transitions (e.g., `@debugger` → `@test-engineer`).
+- Custom agents with `handoffs:` frontmatter offer guided workflow transitions (e.g., `@debugger` -> `@tester`).
 - The `@orchestrator` has `agents: ["*"]` — it can delegate to any specialist.
-- The `@project-planner` can delegate to `@researcher` and `@orchestrator`.
+- The `@planner` can hand off to `@implementer` or return work to `@orchestrator`.
 - Handoffs are suggestions — the user decides when to follow them.
 
 ## Platform Notes
 
 - Copilot supports path-scoped instructions (`applyTo` in `.github/instructions/*.instructions.md` frontmatter).
 - MCP tools are configured via `.vscode/mcp.json` or VS Code settings — not inline.
-- Copilot agent frontmatter supports: `name`, `description`, `tools`, `model`, `handoffs`, `agents`, `argument-hint`, `mcp-servers`, `metadata`.
+- Copilot custom-agent frontmatter supports: `name`, `description`, `tools`, `model`, `handoffs`, `agents`, `argument-hint`, `mcp-servers`, `metadata`.
 - Skills support `argument-hint`, `disable-model-invocation`, and `user-invocable` frontmatter keys.
 
 ## Copilot Asset Authoring
 
 When creating Copilot-specific assets:
 
-- Use `.prompt.md` extension for prompt files.
+- Use `.agent.md` extension for custom agents.
+- Use `.prompt.md` extension for workflow prompt files.
 - Declare `#file:` references for file context injection.
 - Keep prompt files focused — one prompt per task type.
 - Test with `@workspace` and custom `@agent-name` invocations.

package/workflows/workflows/agent-environment-setup/shared/rules/overrides/gemini.md

@@ -3,16 +3,18 @@
 ## Platform Paths
 
 - Commands: `.gemini/commands`
-- Rules file: `.gemini/GEMINI.md` (or `GEMINI.md` at repo root when used directly)
+- Rules file: `.gemini/GEMINI.md` (with `GEMINI.md` as compatibility read surface)
+- Hooks: `.gemini/hooks/*` wired through `.gemini/settings.json`
+- Skills: MCP-loaded guidance by default; optional hint-only `.agents/skills/<skill-id>/SKILL.md` when explicitly enabled
 
 ## Platform-Specific Routing
 
 1. **Explicit Gemini command** (`.gemini/commands/*.toml`) — highest priority route.
-2. Foundry compiles both `/workflow` and `@agent` routes into command entry points when targeting Gemini CLI.
+2. Foundry compiles both `/workflow` and `@agent` specialist routes into command entry points when targeting Gemini CLI.
 3. Standard workflow and MCP routing from shared steering.
 
 ## Platform Notes
 
 - Gemini CLI uses GEMINI.md plus TOML commands as the primary enforcement surface.
-- Gemini specialist behavior is posture-based; it does not rely on standalone agent markdown in the project profile.
+- Gemini specialist behavior is command-based in the current Foundry ship model; do not claim `.gemini/agents/*.md` as a shipped surface until it is deliberately adopted.
 - Use command wrappers to reinforce route-resolved execution and research escalation when freshness or public comparison matters.

package/workflows/workflows/agent-environment-setup/shared/workflows/debug.md

@@ -1,61 +1,59 @@
 ---
 command: "/debug"
-description: "Isolate root cause quickly, apply the smallest safe remediation, and leave behind regression evidence."
-triggers: ["debug", "bug", "error", "incident", "stack trace"]
+description: "Systematic bug investigation: explore, isolate the root cause, fix the bug, test the fix, and review the change."
+triggers: ["debug", "fix", "bug", "error", "investigate", "broken"]
 ---
 
 # Debug Workflow
 
 ## When to use
 
-Use this when behavior is failing, inconsistent, flaky, or only reproducible under certain conditions.
+Use for bug reports, error investigations, test failures, and any issue where the root cause is not immediately obvious.
 
-## Routing
+## Agent Chain
 
-- Primary specialist: `@debugger`
-- Domain implementation support: `@backend-specialist`, `@frontend-specialist`
-- Verification support: `@test-engineer`
+`explorer` -> `debugger` -> `tester` -> `reviewer`
 
-## Context notes
+## Routing
 
-- This workflow file, active platform rules, and selected agents or skills guide execution.
-- Attach stack traces, request IDs, traces, repro steps, recent diffs, and environment notes when context is incomplete.
+1. **Explore**: `@explorer` gathers context - reads error logs, traces code paths, identifies the affected area.
+2. **Debug**: `@debugger` uses the 5-step protocol to find and fix the root cause.
+3. **Test**: `@tester` verifies the fix and checks for regressions.
+4. **Review**: `@reviewer` evaluates the fix for correctness and side effects.
 
 ## Skill Routing
 
-- Primary skills: `debugging-strategies`, `error-ux-observability`
-- Supporting skills (optional): `testing-patterns`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`, `java-pro`, `csharp-pro`, `kotlin-pro`, `rust-pro`, `webapp-testing`, `playwright-e2e`, `skill-creator`
-- Start with `debugging-strategies` for reproduce, isolate, instrument, and verify flow. Add `error-ux-observability` when the failure involves error states, logging, or tracing gaps. Add the dominant language skill for exact code-path analysis, `webapp-testing` or `playwright-e2e` when the failure lives in browser or release verification.
+- Primary skills: `systematic-debugging`, `deep-research`
+- Supporting skills (optional): `unit-testing`, `flutter-mobile-qa`, `code-review`
+
+## Context notes
+
+- Provide the error message, stack trace, reproduction steps, and expected vs. actual behavior.
+- Debugger follows the 5-step protocol: capture, reproduce, isolate, fix, verify.
 
 ## Workflow steps
 
-1. Reproduce the issue and record expected versus actual behavior.
-2. Narrow the fault domain with the smallest useful evidence.
-3. Fix the confirmed cause with the lowest regression risk.
-4. Add or update the regression proof.
-5. Document any remaining uncertainty or environment-specific gaps.
+1. Explorer reads the bug report and maps the affected code paths.
+2. Debugger reproduces the issue, traces to root cause, and implements a minimal fix.
+3. Tester runs the previously failing test plus regression tests.
+4. Reviewer checks the fix is correct, minimal, and introduces no new issues.
+5. If the fix is insufficient, debugger iterates with new evidence.
 
 ## Verification
 
-- Re-run the failing scenario first.
-- Run focused regression checks on adjacent high-risk paths.
-- Call out any remaining gaps if the full environment could not be reproduced.
+- Root cause identified and documented.
+- Fix is minimal and targeted (no unrelated changes).
+- Previously failing test passes and no regressions introduced.
 
 ## Output Contract
 
 ```yaml
-DEBUG_WORKFLOW_RESULT:
+WORKFLOW_RESULT:
   primary_agent: debugger
-  supporting_agents: [backend-specialist?, frontend-specialist?, test-engineer?]
-  primary_skills: [debugging-strategies, error-ux-observability]
-  supporting_skills: [testing-patterns?, <language-skill>?, webapp-testing?, playwright-e2e?]
-  reproduction:
-    steps: [<string>]
-    expected_vs_actual: <string>
+  supporting_agents: [explorer, tester, reviewer]
   root_cause: <string>
-  remediation:
-    summary: <string>
-    changed_artifacts: [<path-or-artifact>]
+  fix_summary: <string>
+  changed_artifacts: [<path>]
   regression_checks: [<command or test>]
   follow_up_items: [<string>] | []
 ```

package/workflows/workflows/agent-environment-setup/shared/workflows/deploy.md

@@ -0,0 +1,59 @@
+---
+command: "/deploy"
+description: "CI/CD and deployment setup: configure pipelines, Docker, infrastructure, test the pipeline, and review the configuration."
+triggers: ["deploy", "ci", "cd", "pipeline", "docker", "kubernetes", "infra"]
+---
+
+# Deploy Workflow
+
+## When to use
+
+Use for CI/CD pipeline setup, Docker configuration, Kubernetes manifests, deployment automation, or infrastructure changes.
+
+## Agent Chain
+
+`planner` -> `implementer` -> `tester` -> `reviewer`
+
+## Routing
+
+1. **Plan**: `@planner` defines the deployment path, risks, rollback points, and validation gates.
+2. **Build**: `@implementer` creates or modifies pipeline configs, Dockerfiles, or infrastructure definitions.
+3. **Test**: `@tester` validates the pipeline (dry runs, container builds, integration checks).
+4. **Review**: `@reviewer` reviews the configuration for correctness and security.
+
+## Skill Routing
+
+- Primary skills: `ci-cd-pipeline`, `docker-compose-dev`
+- Supporting skills (optional): `kubernetes-deploy`, `integration-testing`, `code-review`, `owasp-security-review`
+
+## Context notes
+
+- Provide the deployment target, requirements, and any infrastructure constraints.
+- Implementer follows the project's existing infrastructure patterns.
+
+## Workflow steps
+
+1. Planner analyzes the current deployment setup and requirements.
+2. Implementer implements the pipeline or infrastructure changes.
+3. Tester runs pipeline checks, container builds, or dry-run deployments.
+4. Reviewer validates security (no hardcoded secrets, least-privilege, image scanning).
+5. If issues are found, implementer iterates on the configuration.
+
+## Verification
+
+- Pipeline runs successfully (build, test, deploy stages pass).
+- No hardcoded secrets in configuration files.
+- Rollback procedure documented and tested.
+
+## Output Contract
+
+```yaml
+WORKFLOW_RESULT:
+  primary_agent: implementer
+  supporting_agents: [planner, tester, reviewer]
+  pipeline_status: <pass|fail>
+  changed_artifacts: [<path>]
+  secrets_hardcoded: <number>
+  rollback_documented: <boolean>
+  follow_up_items: [<string>] | []
+```