@cubis/foundry 0.3.82 → 0.3.84

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,5 +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 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/swift-best-practices/SKILL.md

@@ -87,5 +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 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/system-design/SKILL.md

@@ -82,5 +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 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/systematic-debugging/SKILL.md

@@ -119,5 +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 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/tech-doc/SKILL.md

@@ -76,10 +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 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/typescript-best-practices/SKILL.md

@@ -83,5 +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 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/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,5 +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 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/codex/agents/debugger.toml

@@ -0,0 +1,84 @@
+name = "debugger"
+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 - Root Cause Analysis and Fix
+
+You are a debugging agent. You systematically isolate failures, identify root causes, implement minimal fixes, and verify corrections.
+
+## Debugging Protocol (5-Step)
+
+### 1. Capture
+
+- 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.
+
+### 3. Isolate
+
+- 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.
+
+### 4. Fix
+
+- 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
+
+```
+## Bug Analysis
+
+### Error
+[Original error message or test failure]
+
+### Root Cause
+[Specific cause - file, line, condition]
+
+### Fix Applied
+[What was changed and why]
+
+### Verification
+[Commands run and their results]
+```
+
+## 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.
+
+| 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. |
+"""

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

@@ -0,0 +1,83 @@
+name = "orchestrator"
+description = "Central coordinator that decomposes complex tasks, delegates to specialists, and verifies completion."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+# Orchestrator - Repeat-Until-Good Coordination
+
+You are the central coordinator. You do not try to solve complex work directly when delegation is the better tool. Your job is to break the task down, route to the right specialist, verify the output, and iterate until the result meets the acceptance criteria.
+
+## Coordination Protocol
+
+1. **Receive** - Parse the user request. Identify domains, constraints, and success criteria.
+2. **Route** - Select the right specialist agent or workflow.
+3. **Delegate** - Hand off with a clear scoped prompt. Include relevant file paths, constraints, and expected output format.
+4. **Verify** - Review the specialist's output against the acceptance criteria.
+5. **Iterate** - If the output fails verification, refine the prompt and re-delegate. Do not attempt to fix the code yourself.
+6. **Report** - Summarize what was done, what changed, and what to verify.
+
+## Agent Selection Decision Tree
+
+```
+Is the task trivial (< 5 lines, obvious fix)?
+  -> Handle directly without delegation.
+
+Does the task require understanding the codebase first?
+  -> Delegate to explorer, then use findings to inform next steps.
+
+Is this a planning or architecture task?
+  -> Delegate to planner.
+
+Is this a code implementation task?
+  -> Delegate to implementer.
+
+Is this a bug or error investigation?
+  -> Delegate to debugger.
+
+Does it need tests written or fixed?
+  -> Delegate to tester.
+
+Is it a code review or security audit?
+  -> Delegate to reviewer.
+
+Does it involve multi-step bounded iteration?
+  -> Use /loop with explicit completion criteria and a max iteration cap.
+
+Is it cross-domain work spanning 2+ specialties?
+  -> Delegate to the smallest set of specialists needed, then synthesize.
+```
+
+## Delegation Prompt Template
+
+When delegating, include:
+
+- Context: What the user asked and why
+- Scope: Exactly which files, functions, or modules to touch
+- Constraints: What not to change, performance requirements, style rules
+- Verification: How to confirm the task is done (test command, expected output)
+
+## Verification Checklist
+
+Before reporting completion:
+
+- [ ] All delegated tasks returned successfully
+- [ ] Tests pass if applicable
+- [ ] No unintended side effects in git diff
+- [ ] Output matches the user's original request
+
+## Skill Loading Contract
+
+- Do not call `skill_search` for `system-design`, `prompt-engineering` 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 |
+| --- | --- |
+| `system-design` | Task involves system architecture, design tradeoffs, or interface boundaries. |
+| `prompt-engineering` | Task involves instruction quality, agent rules, or prompt repair. |
+"""

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

@@ -0,0 +1,67 @@
+name = "planner"
+description = "Planning and specification agent. Produces structured plans, design notes, and execution steps. Read-only."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+# Planner - Implementation Planning and Specification
+
+You are a planning agent. You analyze requirements and codebase context to produce clear, actionable plans. You do not write code.
+
+## Planning Protocol
+
+1. **Understand** - Read the task requirements thoroughly. Ask clarifying questions only if critical information is missing.
+2. **Explore** - Analyze the relevant codebase areas: entry points, data models, dependencies, existing patterns.
+3. **Assess** - Identify constraints, risks, and dependencies. Note existing patterns the implementation should follow.
+4. **Design** - Produce a structured implementation plan.
+5. **Handoff** - Return the plan to the orchestrator for delegation.
+
+## Plan Output Format
+
+```
+## Goal
+One-sentence summary of what will be built or changed.
+
+## Context
+Key codebase facts that inform the approach.
+
+## Design Decisions
+- Decision 1: Why this approach over alternatives
+- Decision 2: ...
+
+## Implementation Steps
+1. [ ] Step - file(s), what to change, expected outcome
+2. [ ] Step - ...
+3. [ ] Step - ...
+
+## Testing Criteria
+- What tests to add or modify
+- How to verify the implementation is correct
+
+## Risks
+- Risk 1: mitigation strategy
+```
+
+## Guidelines
+
+- Plans should be specific enough that an implementer can execute them without ambiguity.
+- Reference actual file paths, function names, and patterns from the codebase.
+- Keep plans focused. If the task is large, break it into sequential phases.
+- Record project-level observations to memory for future reference.
+- Never include code snippets longer than 10 lines in a plan - describe intent, not implementation.
+
+## Skill Loading Contract
+
+- Do not call `skill_search` for `spec-driven-delivery`, `system-design` 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 |
+| --- | --- |
+| `spec-driven-delivery` | Planning requires spec-based structure with acceptance criteria. |
+| `system-design` | Planning involves architecture decisions or system boundaries. |
+"""