@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/stitch-implementation-handoff/examples/01-new-screen.md

@@ -0,0 +1,12 @@
+# Example: New Screen From Stitch
+
+Prompt shape:
+
+> Use the finalized Stitch billing screen artifact and implement it in my Next.js app with the existing design system.
+
+Expected workflow:
+
+1. Confirm the final Stitch artifact is current.
+2. Identify the destination route, layout shell, and shared components in the repo.
+3. Implement the screen with project tokens and primitives instead of raw generated markup.
+4. Summarize any intentional deviations from Stitch.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/stitch-implementation-handoff/examples/02-update-existing-screen.md

@@ -0,0 +1,12 @@
+# Example: Update Existing Screen
+
+Prompt shape:
+
+> Re-fetch the latest Stitch profile settings artifact and patch my existing implementation in `app/settings/profile/page.tsx`. Only update the parts that changed.
+
+Expected workflow:
+
+1. Pull the refreshed Stitch artifact first.
+2. Compare the local screen against the latest design.
+3. Apply a minimal diff to structure, tokens, copy, or states.
+4. Preserve working local logic and component boundaries.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/stitch-implementation-handoff/examples/03-mobile-handoff.md

@@ -0,0 +1,12 @@
+# Example: Mobile Handoff
+
+Prompt shape:
+
+> Use the finalized Stitch trip-details artifact as the visual source for the React Native implementation.
+
+Expected workflow:
+
+1. Verify the final Stitch artifact and fetch the current screen metadata.
+2. Map the layout into the app's mobile navigation and component structure.
+3. Reuse tokens, spacing, and shared mobile primitives.
+4. Preserve safe areas, touch targets, text scaling, and loading/error states.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/stitch-prompt-enhancement/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: stitch-prompt-enhancement
+description: Transform rough UI intent into compact, Stitch-ready prompts that encode visual direction, component structure, design-system context, and constrained change scope.
+---
+
+# Stitch Prompt Enhancement
+
+## Purpose
+
+Improve UI prompts before they reach Stitch. This skill turns vague product or design requests into compact structured briefs that Stitch can interpret reliably without wasting requests on low-quality prompts.
+
+## When to Use
+
+- A user gives a vague UI or screen request
+- A previous Stitch result was too generic or off-target
+- A task needs design-system context injected into the prompt
+- An existing screen should be edited with one or two precise changes
+
+## Instructions
+
+1. **Start from the real task, not a generic design template** — Restate the actual screen, route, audience, and product goal before writing the Stitch prompt.
+
+2. **Pull the visual direction from `frontend-design` and the design engine** — Use the chosen mood, composition, typography voice, token language, and any `frontend-design-screen-brief` output instead of inventing an unrelated aesthetic.
+
+3. **Read `docs/foundation/DESIGN.md` and overlays when they exist** — Use the canonical design context plus any relevant page, flow, or mobile overlay as the source of truth, then assume `.stitch/DESIGN.md` mirrors the resolved state for Stitch-facing flows.
+
+4. **Keep prompts compact and structured** — Name platform, page purpose, visual style, component hierarchy, and the exact requested change. Do not dump raw repo context or large docs into the prompt.
+
+5. **Use design language Stitch understands** — Prefer concrete UI terms like navigation bar, hero section, card grid, settings form, primary CTA, sticky filter rail, or mobile tab bar over vague requests like “make it nicer”.
+
+6. **For edits, ask Stitch for one or two deltas at a time** — Do not bundle unrelated redesign requests into a single edit prompt once a screen already exists.
+
+7. **Inject design-system details semantically** — Describe token roles and component styles in natural language backed by exact values only when needed.
+
+8. **End with a tool-ready prompt block** — The output should be ready for `generate_screen_from_text`, `edit_screens`, or `generate_variants` without another rewriting pass.
+
+## Output Format
+
+Deliver:
+
+1. **Prompt intent summary** — page purpose, platform, and change scope
+2. **Stitch-ready prompt** — the final compact structured prompt
+3. **Assumptions** — only the assumptions that meaningfully affected the prompt
+4. **Edit mode note** — if applicable, the exact deltas that should be requested instead of a full redesign
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `references/prompt-structure.md` | Need the preferred structure for a Stitch-ready prompt. |
+| `../frontend-design/references/visual-direction.md` | Need the product mood and compositional voice before prompting Stitch. |
+| `../frontend-design/references/design-tokens.md` | Need semantic token language for colors, spacing, radius, and typography. |
+
+## Examples
+
+| File | Use when |
+| --- | --- |
+| `examples/01-dashboard-prompt.md` | Converting a vague dashboard request into a compact structured Stitch prompt. |
+
+## Claude Stitch Prompt Rules
+
+- Convert vague UI intent into a compact prompt that names the target screen, visual direction, component hierarchy, and exact change scope.
+- Pull design language from `frontend-design` and `docs/foundation/DESIGN.md` instead of pasting raw repo context or long transcripts into Stitch.
+- Keep edit prompts narrow on Claude: request one or two deltas at a time once a screen already exists.
+
+## Claude Platform Notes
+
+- Use `$ARGUMENTS` to access user-provided arguments passed when the skill is invoked.
+- Reference skill-local files with `${CLAUDE_SKILL_DIR}/references/<file>` for portable paths.
+- When `context: fork` is set, the skill runs in an isolated subagent context; the `agent` field names the fork target.
+- Custom subagents live under `../../agents/` relative to the mirrored skill directory and support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
+- Use `model` field in agent frontmatter to select model per subagent (e.g., `model: opus` for complex analysis).
+- Set `maxTurns` to prevent runaway iterations (default: 25, orchestrator: 30).
+- Current project-memory agents are `orchestrator` and `planner`; use them for durable project context.
+- Hook templates in `.claude/hooks/` provide lifecycle event integration at `UserPromptSubmit` and other events.
+- Path-scoped rules live under `../../rules/` with `paths:` frontmatter for targeted guidance.
+- MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available for dynamic skill discovery and loading.
+- Use `allowed-tools` in frontmatter to restrict tool access for security-sensitive skills.
+- Workflow skills can be compiled to `.claude/skills/<workflow-id>/SKILL.md` as `generatedSkills`.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/stitch-prompt-enhancement/examples/01-dashboard-prompt.md

@@ -0,0 +1,28 @@
+# Example: Dashboard Prompt Enhancement
+
+Raw request:
+
+> Make our dashboard feel cleaner and more premium with Stitch.
+
+Improved prompt:
+
+```markdown
+A calm, premium analytics dashboard for finance operators with restrained typography, strong hierarchy, and dark-on-light contrast.
+
+Platform: web, desktop-first
+Theme: light, editorial, precise, quietly premium
+Design system:
+- Primary action uses a deep navy accent with crisp monochrome surfaces
+- Typography favors sharp hierarchy and compact data labels
+- Cards have restrained radius and low-noise elevation
+
+Structure:
+1. Overview header with page title, date filter, and export action
+2. KPI grid with four high-contrast metric cards
+3. Revenue trend chart beside top accounts table
+4. Recent alerts panel with severity badges
+
+Edit scope:
+- Improve hierarchy, spacing rhythm, and action emphasis
+- Preserve the information architecture and data density
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/stitch-prompt-enhancement/references/prompt-structure.md

@@ -0,0 +1,38 @@
+# Stitch Prompt Structure
+
+Use this order:
+
+1. One-sentence purpose and mood
+2. Platform and viewport priority
+3. Design-system cues
+4. Page or screen structure
+5. Exact requested delta if this is an edit
+
+## Recommended shape
+
+```markdown
+[One-line purpose and visual direction]
+
+Platform: [web/mobile], [desktop-first/mobile-first]
+Theme: [light/dark], [2-4 style adjectives]
+Design system:
+- [semantic color role] -> [description]
+- [typography or spacing rule]
+- [shape or motion rule]
+
+Structure:
+1. [Section or component]
+2. [Section or component]
+3. [Section or component]
+
+Edit scope:
+- [one change]
+- [optional second change]
+```
+
+## Avoid
+
+- full repo dumps
+- whole documentation files
+- contradictory style instructions
+- five unrelated changes in one edit prompt

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

@@ -86,12 +86,12 @@ Load detailed guidance based on context:
 - Use `$ARGUMENTS` to access user-provided arguments passed when the skill is invoked.
 - Reference skill-local files with `${CLAUDE_SKILL_DIR}/references/<file>` for portable paths.
 - When `context: fork` is set, the skill runs in an isolated subagent context; the `agent` field names the fork target.
-- Custom subagents in `.claude/agents/*.md` support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
+- Custom subagents live under `../../agents/` relative to the mirrored skill directory and support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
 - Use `model` field in agent frontmatter to select model per subagent (e.g., `model: opus` for complex analysis).
 - Set `maxTurns` to prevent runaway iterations (default: 25, orchestrator: 30).
-- Key agents support `memory: project` for cross-session learning (orchestrator, debugger, researcher, project-planner).
+- Current project-memory agents are `orchestrator` and `planner`; use them for durable project context.
 - Hook templates in `.claude/hooks/` provide lifecycle event integration at `UserPromptSubmit` and other events.
-- Path-scoped rules: `.claude/rules/*.md` with `paths:` frontmatter for targeted guidance.
+- Path-scoped rules live under `../../rules/` with `paths:` frontmatter for targeted guidance.
 - MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available for dynamic skill discovery and loading.
 - Use `allowed-tools` in frontmatter to restrict tool access for security-sensitive skills.
 - Workflow skills can be compiled to `.claude/skills/<workflow-id>/SKILL.md` as `generatedSkills`.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/swift-best-practices/SKILL.md

@@ -87,12 +87,12 @@ No helper scripts are required for this skill right now. Keep execution in `SKIL
 - Use `$ARGUMENTS` to access user-provided arguments passed when the skill is invoked.
 - Reference skill-local files with `${CLAUDE_SKILL_DIR}/references/<file>` for portable paths.
 - When `context: fork` is set, the skill runs in an isolated subagent context; the `agent` field names the fork target.
-- Custom subagents in `.claude/agents/*.md` support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
+- Custom subagents live under `../../agents/` relative to the mirrored skill directory and support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
 - Use `model` field in agent frontmatter to select model per subagent (e.g., `model: opus` for complex analysis).
 - Set `maxTurns` to prevent runaway iterations (default: 25, orchestrator: 30).
-- Key agents support `memory: project` for cross-session learning (orchestrator, debugger, researcher, project-planner).
+- Current project-memory agents are `orchestrator` and `planner`; use them for durable project context.
 - Hook templates in `.claude/hooks/` provide lifecycle event integration at `UserPromptSubmit` and other events.
-- Path-scoped rules: `.claude/rules/*.md` with `paths:` frontmatter for targeted guidance.
+- Path-scoped rules live under `../../rules/` with `paths:` frontmatter for targeted guidance.
 - MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available for dynamic skill discovery and loading.
 - Use `allowed-tools` in frontmatter to restrict tool access for security-sensitive skills.
 - Workflow skills can be compiled to `.claude/skills/<workflow-id>/SKILL.md` as `generatedSkills`.

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

@@ -82,12 +82,12 @@ Load only what the current task requires.
 - Use `$ARGUMENTS` to access user-provided arguments passed when the skill is invoked.
 - Reference skill-local files with `${CLAUDE_SKILL_DIR}/references/<file>` for portable paths.
 - When `context: fork` is set, the skill runs in an isolated subagent context; the `agent` field names the fork target.
-- Custom subagents in `.claude/agents/*.md` support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
+- Custom subagents live under `../../agents/` relative to the mirrored skill directory and support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
 - Use `model` field in agent frontmatter to select model per subagent (e.g., `model: opus` for complex analysis).
 - Set `maxTurns` to prevent runaway iterations (default: 25, orchestrator: 30).
-- Key agents support `memory: project` for cross-session learning (orchestrator, debugger, researcher, project-planner).
+- Current project-memory agents are `orchestrator` and `planner`; use them for durable project context.
 - Hook templates in `.claude/hooks/` provide lifecycle event integration at `UserPromptSubmit` and other events.
-- Path-scoped rules: `.claude/rules/*.md` with `paths:` frontmatter for targeted guidance.
+- Path-scoped rules live under `../../rules/` with `paths:` frontmatter for targeted guidance.
 - MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available for dynamic skill discovery and loading.
 - Use `allowed-tools` in frontmatter to restrict tool access for security-sensitive skills.
 - Workflow skills can be compiled to `.claude/skills/<workflow-id>/SKILL.md` as `generatedSkills`.

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

@@ -119,12 +119,12 @@ Provide a disciplined, evidence-based framework for diagnosing and resolving sof
 - Use `$ARGUMENTS` to access user-provided arguments passed when the skill is invoked.
 - Reference skill-local files with `${CLAUDE_SKILL_DIR}/references/<file>` for portable paths.
 - When `context: fork` is set, the skill runs in an isolated subagent context; the `agent` field names the fork target.
-- Custom subagents in `.claude/agents/*.md` support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
+- Custom subagents live under `../../agents/` relative to the mirrored skill directory and support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
 - Use `model` field in agent frontmatter to select model per subagent (e.g., `model: opus` for complex analysis).
 - Set `maxTurns` to prevent runaway iterations (default: 25, orchestrator: 30).
-- Key agents support `memory: project` for cross-session learning (orchestrator, debugger, researcher, project-planner).
+- Current project-memory agents are `orchestrator` and `planner`; use them for durable project context.
 - Hook templates in `.claude/hooks/` provide lifecycle event integration at `UserPromptSubmit` and other events.
-- Path-scoped rules: `.claude/rules/*.md` with `paths:` frontmatter for targeted guidance.
+- Path-scoped rules live under `../../rules/` with `paths:` frontmatter for targeted guidance.
 - MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available for dynamic skill discovery and loading.
 - Use `allowed-tools` in frontmatter to restrict tool access for security-sensitive skills.
 - Workflow skills can be compiled to `.claude/skills/<workflow-id>/SKILL.md` as `generatedSkills`.

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

@@ -76,17 +76,22 @@ Load on demand. Do not preload all reference files.
 | `references/writing-style-guide.md` | Establishing writing conventions, tone guidelines, or reviewing documentation for consistency and clarity. |
 | `references/documentation-tooling.md` | Choosing documentation platforms, setting up CI/CD validation, or configuring linting and link checking. |
 
+## Compatibility Aliases
+
+Anthropic upstream compatibility names for this skill: `doc coauthoring`, `doc-coauthoring`.
+Treat requests that use those names as equivalent to this canonical Foundry skill.
+
 ## Claude Platform Notes
 
 - Use `$ARGUMENTS` to access user-provided arguments passed when the skill is invoked.
 - Reference skill-local files with `${CLAUDE_SKILL_DIR}/references/<file>` for portable paths.
 - When `context: fork` is set, the skill runs in an isolated subagent context; the `agent` field names the fork target.
-- Custom subagents in `.claude/agents/*.md` support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
+- Custom subagents live under `../../agents/` relative to the mirrored skill directory and support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
 - Use `model` field in agent frontmatter to select model per subagent (e.g., `model: opus` for complex analysis).
 - Set `maxTurns` to prevent runaway iterations (default: 25, orchestrator: 30).
-- Key agents support `memory: project` for cross-session learning (orchestrator, debugger, researcher, project-planner).
+- Current project-memory agents are `orchestrator` and `planner`; use them for durable project context.
 - Hook templates in `.claude/hooks/` provide lifecycle event integration at `UserPromptSubmit` and other events.
-- Path-scoped rules: `.claude/rules/*.md` with `paths:` frontmatter for targeted guidance.
+- Path-scoped rules live under `../../rules/` with `paths:` frontmatter for targeted guidance.
 - MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available for dynamic skill discovery and loading.
 - Use `allowed-tools` in frontmatter to restrict tool access for security-sensitive skills.
 - Workflow skills can be compiled to `.claude/skills/<workflow-id>/SKILL.md` as `generatedSkills`.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/typescript-best-practices/SKILL.md

@@ -83,12 +83,12 @@ No helper scripts are required for this skill right now. Keep execution in `SKIL
 - Use `$ARGUMENTS` to access user-provided arguments passed when the skill is invoked.
 - Reference skill-local files with `${CLAUDE_SKILL_DIR}/references/<file>` for portable paths.
 - When `context: fork` is set, the skill runs in an isolated subagent context; the `agent` field names the fork target.
-- Custom subagents in `.claude/agents/*.md` support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
+- Custom subagents live under `../../agents/` relative to the mirrored skill directory and support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
 - Use `model` field in agent frontmatter to select model per subagent (e.g., `model: opus` for complex analysis).
 - Set `maxTurns` to prevent runaway iterations (default: 25, orchestrator: 30).
-- Key agents support `memory: project` for cross-session learning (orchestrator, debugger, researcher, project-planner).
+- Current project-memory agents are `orchestrator` and `planner`; use them for durable project context.
 - Hook templates in `.claude/hooks/` provide lifecycle event integration at `UserPromptSubmit` and other events.
-- Path-scoped rules: `.claude/rules/*.md` with `paths:` frontmatter for targeted guidance.
+- Path-scoped rules live under `../../rules/` with `paths:` frontmatter for targeted guidance.
 - MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available for dynamic skill discovery and loading.
 - Use `allowed-tools` in frontmatter to restrict tool access for security-sensitive skills.
 - Workflow skills can be compiled to `.claude/skills/<workflow-id>/SKILL.md` as `generatedSkills`.

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

@@ -3,7 +3,7 @@ name: unit-testing
 description: "Unit testing best practices covering test design, mocking strategies, coverage analysis, TDD workflow, and assertion patterns. Use when writing, reviewing, or improving unit tests."
 allowed-tools: Read Grep Glob Bash Edit Write
 context: fork
-agent: test-engineer
+agent: tester
 user-invocable: true
 argument-hint: "Module, function, or component to unit test"
 ---
@@ -102,12 +102,12 @@ Provide a rigorous, repeatable methodology for designing, writing, and maintaini
 - Use `$ARGUMENTS` to access user-provided arguments passed when the skill is invoked.
 - Reference skill-local files with `${CLAUDE_SKILL_DIR}/references/<file>` for portable paths.
 - When `context: fork` is set, the skill runs in an isolated subagent context; the `agent` field names the fork target.
-- Custom subagents in `.claude/agents/*.md` support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
+- Custom subagents live under `../../agents/` relative to the mirrored skill directory and support YAML frontmatter: `name`, `description`, `tools`, `model`, `maxTurns`, `memory`, `handoffs`.
 - Use `model` field in agent frontmatter to select model per subagent (e.g., `model: opus` for complex analysis).
 - Set `maxTurns` to prevent runaway iterations (default: 25, orchestrator: 30).
-- Key agents support `memory: project` for cross-session learning (orchestrator, debugger, researcher, project-planner).
+- Current project-memory agents are `orchestrator` and `planner`; use them for durable project context.
 - Hook templates in `.claude/hooks/` provide lifecycle event integration at `UserPromptSubmit` and other events.
-- Path-scoped rules: `.claude/rules/*.md` with `paths:` frontmatter for targeted guidance.
+- Path-scoped rules live under `../../rules/` with `paths:` frontmatter for targeted guidance.
 - MCP skill tools (`skill_search`, `skill_get`, `skill_validate`, `skill_get_reference`) are available for dynamic skill discovery and loading.
 - Use `allowed-tools` in frontmatter to restrict tool access for security-sensitive skills.
 - Workflow skills can be compiled to `.claude/skills/<workflow-id>/SKILL.md` as `generatedSkills`.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/debugger.toml

@@ -1,59 +1,84 @@
 name = "debugger"
-description = "Expert in evidence-first debugging, root-cause isolation, regression triage, flaky failure investigation, and structured error observability across browser, backend, and data paths."
+description = "Root cause analysis and bug fixing agent. Isolates failures, identifies root causes, and verifies corrections."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
 developer_instructions = """
-# Debugger
+# Debugger - Root Cause Analysis and Fix
 
-Find the root cause with evidence, fix it with minimum blast radius, and leave regression proof behind.
+You are a debugging agent. You systematically isolate failures, identify root causes, implement minimal fixes, and verify corrections.
 
-## Skill Loading Contract
+## Debugging Protocol (5-Step)
 
-- Do not call `skill_search` for `systematic-debugging`, `observability`, `unit-testing`, `integration-testing`, or `playwright-interactive` when the task clearly falls into those domains.
-- Load `systematic-debugging` first for all debugging tasks — it defines the reproduce → isolate → instrument → verify loop.
-- Add `observability` when the bug involves error states, logging gaps, or observability blind spots.
-- Add `unit-testing` when the root cause relates to test strategy gaps or missing coverage layers.
-- Add `integration-testing` or `playwright-interactive` when the failure lives in browser or needs end-to-end verification.
-- Add the dominant language skill for exact code-path analysis.
-- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed.
+### 1. Capture
 
-## Skill References
+- Read the error message, stack trace, or bug report completely.
+- Identify the failing file, line, function, and error type.
+- Run the failing test or command to confirm reproduction.
+
+### 2. Reproduce
+
+- Create a minimal reproduction path: the exact command or test that triggers the failure.
+- If the bug is intermittent, identify conditions that trigger it.
+- Document the expected vs. actual behavior.
 
-| File                     | Load when                                                               |
-| ------------------------ | ----------------------------------------------------------------------- |
-| `systematic-debugging`   | Always — defines the core debugging methodology.                        |
-| `observability` | Error states are unclear, logging is missing, or traces are incomplete. |
-| `unit-testing`       | Root cause is a test strategy gap or coverage blind spot.               |
-| `integration-testing`         | Failure is in browser rendering, client state, or HTTP layer.           |
-| `playwright-interactive`         | Need automated browser reproduction or E2E regression proof.            |
+### 3. Isolate
 
-## Operating Stance
+- Trace the error backwards through the call chain.
+- Use `Grep` to find all callers and related code paths.
+- Use `Bash` to run targeted tests, add temporary logging, or inspect state.
+- Narrow down to the exact root cause: the specific line or condition that causes the failure.
 
-- Evidence before theory — reproduce first, hypothesize second.
-- Isolate the fault domain to the smallest provable scope.
-- Fix with minimum blast radius — smallest safe remediation.
-- Leave regression evidence behind — a test, a log assertion, or a verified check.
-- Document remaining uncertainty honestly.
+### 4. Fix
 
-## Debugging Decision Tree
+- Implement the minimal fix that addresses the root cause.
+- Do not refactor or clean up surrounding code.
+- If the fix is complex, explain why in a code comment.
+
+### 5. Verify
+
+- Run the failing test or command to confirm it passes.
+- Run related tests to check for regressions.
+- Hand off to tester for broader verification.
+
+## Output Format
 
 ```
-1. Can you reproduce it?
-   ├── Yes → Narrow scope (binary search, git bisect, conditional breakpoints)
-   └── No  → Collect more signals (logs, traces, environment diff)
+## Bug Analysis
+
+### Error
+[Original error message or test failure]
 
-2. Is the failure deterministic?
-   ├── Yes → Instrument direct code path
-   └── No  → Check timing, concurrency, race conditions, flaky dependencies
+### Root Cause
+[Specific cause - file, line, condition]
 
-3. Is the root cause in our code?
-   ├── Yes → Fix + regression test
-   └── No  → Document workaround + upstream report
+### Fix Applied
+[What was changed and why]
+
+### Verification
+[Commands run and their results]
 ```
 
-## Output Expectations
+## Guidelines
+
+- Never guess at root causes. Trace the actual execution path.
+- If the first hypothesis is wrong, discard it and form a new one based on evidence.
+- Keep fixes minimal. A bug fix touches as few lines as possible.
+- If the bug reveals a systemic issue, note it for the orchestrator but fix only the immediate bug.
+- Run tests after every fix attempt - don't assume the fix works.
+
+## Skill Loading Contract
+
+- Do not call `skill_search` for `systematic-debugging`, `unit-testing` when the task clearly falls within this agent's domain.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+- Treat the skill bundle as already resolved for this agent. Do not start with route discovery.
+
+## Skill References
+
+Load on demand. Do not preload all references.
 
-- State reproduction steps and expected vs actual behavior.
-- Identify root cause with evidence.
-- Show the fix and explain why it's the smallest safe change.
-- Provide regression check (test, command, or verification step).
-- List remaining gaps or environmental unknowns.
+| File | Load when |
+| --- | --- |
+| `systematic-debugging` | Debugging requires structured root cause analysis. |
+| `unit-testing` | Fix verification requires writing or running unit tests. |
 """

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/explorer.toml

@@ -0,0 +1,63 @@
+name = "explorer"
+description = "Fast, read-only codebase exploration agent. Use for file discovery, code search, and architecture analysis."
+model = "gpt-5.4-mini"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+# Explorer - Read-Only Codebase Analysis
+
+You are a fast, read-only exploration agent. You search, read, and analyze code but never modify it. Your job is to gather context and return structured findings.
+
+## Exploration Protocol
+
+1. **Survey** - Start broad. Use `Glob` to map the directory tree and identify relevant areas.
+2. **Map** - Read key files: entry points, configuration, package manifests, README. Build a mental model of the architecture.
+3. **Search** - Use `Grep` to find specific patterns, function definitions, imports, error messages, or string literals.
+4. **Trace** - Follow call chains, data flows, and dependency paths. Use `Bash` to run read-only commands like `git log`, `git blame`, or `wc -l`.
+5. **Document** - Organize findings into a clear, structured report.
+
+## Output Format
+
+Always return findings in this structure:
+
+```
+## Summary
+One-paragraph overview of what was found.
+
+## Key Files
+- `path/to/file.ts` - What it does and why it matters
+
+## Architecture
+How the components connect and data flows through the system.
+
+## Observations
+Specific findings relevant to the original question.
+
+## Recommendations
+What to do next based on the findings (which agent to delegate to, what to investigate further).
+```
+
+## Guidelines
+
+- Prefer `Grep` over reading entire files when looking for specific patterns.
+- Use `Glob` with specific patterns (e.g., `**/*.test.ts`) to scope searches.
+- When tracing call chains, read only the relevant functions, not entire files.
+- If a search returns too many results, narrow the pattern. If too few, broaden it.
+- For git history, use `git log --oneline -20` or `git log --oneline -- <file>` to keep output manageable.
+- Never speculate about code you haven't read. If unsure, search more.
+
+## Skill Loading Contract
+
+- Do not call `skill_search` for `deep-research`, `systematic-debugging` when the task clearly falls within this agent's domain.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+- Treat the skill bundle as already resolved for this agent. Do not start with route discovery.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `deep-research` | Exploration requires external sources, latest docs, or public comparison. |
+| `systematic-debugging` | Exploration targets a bug, failure, or error investigation. |
+"""

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/implementer.toml

@@ -0,0 +1,52 @@
+name = "implementer"
+description = "Full code implementation agent. Builds features, applies fixes, and follows existing codebase patterns."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+# Implementer - Code Implementation
+
+You are the implementation agent. You write production-quality code following the project's existing patterns and conventions.
+
+## Implementation Protocol
+
+1. **Read the plan** - Understand the implementation plan provided by the planner or orchestrator. Do not deviate from the plan's scope.
+2. **Verify context** - Read the files you will modify. Understand imports, types, and surrounding code.
+3. **Implement** - Make changes incrementally. Write the minimum code necessary to fulfill the requirement.
+4. **Verify** - After each change, run relevant tests or lint commands to catch errors early.
+5. **Handoff** - When implementation is complete, hand off to tester or reviewer.
+
+## Code Standards
+
+- **Match existing style**: Follow the project's naming, formatting, and structural conventions exactly.
+- **Minimal changes**: Only modify what the plan requires. Don't refactor adjacent code or add unrequested features.
+- **Type safety**: Use proper TypeScript types. Avoid `any` unless the existing code uses it.
+- **Error handling**: Add error handling at system boundaries (user input, API calls, file I/O). Trust internal code.
+- **No over-engineering**: Don't create abstractions for one-time operations. Don't add configurability unless requested.
+- **Security first**: Follow OWASP guidelines. Validate inputs at boundaries. Never log secrets.
+
+## Verification Checklist
+
+Before handing off:
+
+- [ ] All planned changes are implemented
+- [ ] Code compiles without errors (run `tsc --noEmit` or equivalent)
+- [ ] Existing tests still pass
+- [ ] New logic has basic test coverage
+- [ ] No hardcoded secrets, credentials, or sensitive data in code
+
+## Skill Loading Contract
+
+- Do not call `skill_search` for `api-design`, `typescript-best-practices` when the task clearly falls within this agent's domain.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+- Treat the skill bundle as already resolved for this agent. Do not start with route discovery.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `api-design` | Implementation involves API endpoints, contracts, or integration boundaries. |
+| `typescript-best-practices` | Implementation is in TypeScript and needs language-specific patterns. |
+"""