npm - @cubis/foundry - Versions diffs - 0.3.82 → 0.3.84 - Mend

@cubis/foundry 0.3.82 → 0.3.84

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2976) hide show

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

@@ -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 `PRODUCT.md`, `ENGINEERING_RULES.md`, `ARCHITECTURE.md`, and `TECH.md` in that order when they exist before planning or implementing.
+> **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 CHANGED Viewed

@@ -2,18 +2,18 @@
 ## Platform Paths
-- Workflows: `.agent/workflows`
-- Agents: `.agent/agents`
-- Skills: `.agent/skills`
-- Gemini commands: `.gemini/commands/*.toml`
-- Rules file: `GEMINI.md`
+- Rules: `.agents/rules/GEMINI.md`
+- Skills: `.agents/skills/<skill-id>/SKILL.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. **Agent Manager** for multi-agent coordination — Gemini's orchestration surface.
+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
@@ -25,7 +25,7 @@ Gemini recognizes these additional entry points:
 ## Agent Manager
 - Gemini's Agent Manager handles multi-specialist coordination (equivalent to `@orchestrator`).
-- Agent Manager delegates to specialist agents defined in `.agent/agents/`.
+- In Foundry, specialist routes are exposed through generated command files rather than project-local agent markdown.
 - Use Agent Manager when work crosses 2+ domains with explicit handoff needs.
 ## Platform Notes
@@ -34,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -2,16 +2,18 @@
 ## Platform Paths
-- Workflows: `.agents/workflows`
-- Agents: `.agents/agents`
-- Skills: `.agents/skills`
+- Workflow skills: `.agents/skills/<workflow-id>/SKILL.md`
+- 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
 1. **Explicit `/workflow` or `@agent`** — highest priority route.
-2. Compatibility aliases (`$workflow-*`, `$agent-*`) may be accepted as hints but are never the primary route surface.
-3. Standard workflow/agent routing from shared steering.
+2. `/workflow` resolves to a native workflow skill in `.agents/skills/<workflow-id>/SKILL.md`.
+3. `@agent` resolves to a native Codex subagent in `.codex/agents/*.toml`.
+4. Standard workflow/agent routing from shared steering.
 ## Sandbox Constraints
@@ -25,5 +27,6 @@
 - 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 capability-based: use native delegation when available, otherwise coordinate specialist postures sequentially.
+- 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 CHANGED Viewed

@@ -2,39 +2,40 @@
 ## Platform Paths
-- Workflows: `.github/copilot/workflows`
-- 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.
-2. Copilot prompt files (`.github/prompts/*.prompt.md`) provide structured entry points.
+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 CHANGED Viewed

@@ -2,19 +2,19 @@
 ## Platform Paths
-- Workflows: `.gemini/workflows`
-- Skills: `.gemini/skills`
 - 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. **Explicit workflow or named skill** — honor it directly before route discovery.
+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 CHANGED Viewed

@@ -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>] | []
 ```