@cubis/foundry 0.3.62 → 0.3.64

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/orchestrate.md

@@ -5,6 +5,9 @@ triggers: ["orchestrate", "coordinate", "multi-area", "cross-team", "handoff"]
 ---
 # Orchestrate Workflow
 
+# CHANGED: output contract — converted free-form bullets into structured YAML — keeps multi-workstream coordination deterministic across regenerated platforms.
+# CHANGED: skill routing — added `skill-authoring` when orchestration spans canonical skill edits, generator updates, and platform parity work.
+
 ## When to use
 Use this when a task spans backend, frontend, data, testing, and release concerns.
 
@@ -30,7 +33,8 @@ Use this when a task spans backend, frontend, data, testing, and release concern
 
 ## Skill Routing
 - Primary skills: `parallel-agents`, `architecture-designer`
-- Supporting skills (optional): `plan-writing`, `feature-forge`
+- Supporting skills (optional): `plan-writing`, `feature-forge`, `skill-authoring`
+- When the workstream includes skill package changes across multiple platforms, load `skill-authoring` as the first supporting skill.
 
 ## Verification
 - Run focused checks/tests for the changed scope.
@@ -38,8 +42,19 @@ Use this when a task spans backend, frontend, data, testing, and release concern
 - Note any gaps that were not validated.
 
 ## Output Contract
-- Scope and assumptions
-- Workstreams with owner + deliverable
-- Consolidated execution order
-- Test and rollout gates
-- Open risks and mitigations
+```yaml
+ORCHESTRATE_WORKFLOW_RESULT:
+  primary_agent: orchestrator
+  supporting_agents: [backend-specialist?, database-architect?, frontend-specialist?, security-auditor?, test-engineer?, devops-engineer?]
+  primary_skills: [parallel-agents, architecture-designer]
+  supporting_skills: [plan-writing?, feature-forge?]
+  scope_and_assumptions: [<string>]
+  workstreams:
+    - owner: <agent-id>
+      deliverable: <string>
+  execution_order: [<string>]
+  gates:
+    test: [<string>]
+    rollout: [<string>]
+  open_risks: [<string>] | []
+```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/plan.md

@@ -5,16 +5,26 @@ triggers: ["plan", "spec", "design", "roadmap", "acceptance"]
 ---
 # Plan Workflow
 
+# CHANGED: output contract — upgraded to canonical PLAN_HANDOFF schema — lets implementation agents continue task 1→N without re-routing or user restatement.
+# CHANGED: skill routing — added `skill-authoring` as a planning support skill for skill package design and maintenance work.
+
 ## When to use
 Use this when execution needs a stable specification.
 
+## Routing
+- Primary specialist: `@project-planner`
+- Scope clarification: `@product-manager`
+- Architecture review: `@backend-specialist`
+- Verification planning: `@test-engineer`
+
 ## Context notes
 - This workflow file, active platform rules, and selected agents/skills guide execution.
 - Attach logs, screenshots, failing output, and relevant paths when context is incomplete.
 
 ## Skill Routing
 - Primary skills: `plan-writing`, `architecture-designer`
-- Supporting skills (optional): `feature-forge`, `api-designer`
+- Supporting skills (optional): `feature-forge`, `api-designer`, `skill-authoring`
+- When the plan itself is for a skill package, prefer `skill-authoring` as the first supporting skill.
 
 ## Workflow steps
 1. Lock scope and non-goals.
@@ -29,7 +39,25 @@ Use this when execution needs a stable specification.
 - Note any gaps that were not validated.
 
 ## Output Contract
-- Implementation phases
-- API/data/interface details
-- Edge cases and risk matrix
-- Verification and rollout checklist
+```yaml
+PLAN_HANDOFF:
+  tasks:
+    - id: 1
+      title: "Describe the first implementation task"
+      domain: "backend"
+      skill_hint: "api-designer"
+      depends_on: []
+      output_artifact: "path-or-artifact"
+      stop_if_failed: true
+  shared_context:
+    stack: "Describe the target stack"
+    constraints: "List hard requirements and guardrails"
+    active_files: ["path-or-artifact"]
+  execution_mode: "sequential"
+  loaded_skills: ["api-designer"]
+  stop_conditions:
+    - "output_artifact missing AND stop_if_failed: true"
+    - "destructive or irreversible action not in plan"
+    - "required skill missing after 1 skill_search attempt"
+    - "explicit user pause or redirect"
+```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/postman.md

@@ -5,6 +5,8 @@ triggers: ["postman", "collection", "workspace", "environment", "runcollection",
 ---
 # Postman Workflow
 
+# CHANGED: output contract — converted free-form bullets into structured YAML — keeps workspace/action identifiers machine-readable for follow-on automation.
+
 ## When to use
 Use this when tasks are primarily about Postman workspaces, collections, environments, monitors, mocks, or collection runs.
 
@@ -34,7 +36,18 @@ Use this when tasks are primarily about Postman workspaces, collections, environ
 - Note any skipped steps and required follow-up.
 
 ## Output Contract
-- Workspace/context used
-- Actions executed and resulting IDs
-- Pass/fail summary for runs
-- Follow-up or remediation steps
+```yaml
+POSTMAN_WORKFLOW_RESULT:
+  primary_agent: backend-specialist
+  supporting_agents: [security-auditor?, test-engineer?]
+  primary_skills: [postman]
+  supporting_skills: [api-designer?, test-master?]
+  workspace_context: <string>
+  actions_executed:
+    - action: <string>
+      result_id: <string|null>
+  run_summary:
+    passed: <bool|null>
+    failures: [<string>] | []
+  follow_up_steps: [<string>] | []
+```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/qa.md

@@ -5,6 +5,8 @@ triggers: ["qa", "test", "regression", "automation", "e2e"]
 ---
 # QA Workflow
 
+# CHANGED: output contract — converted free-form bullets into structured YAML — keeps quality strategy and defect findings machine-readable.
+
 ## When to use
 Use this when verification quality and regression prevention are primary concerns.
 
@@ -33,7 +35,17 @@ Use this when verification quality and regression prevention are primary concern
 - Note any gaps that were not validated.
 
 ## Output Contract
-- Test strategy and scope
-- Automation coverage updates
-- Defect findings and severity
-- Confidence and residual risk
+```yaml
+QA_WORKFLOW_RESULT:
+  primary_agent: qa-automation-engineer
+  supporting_agents: [test-engineer?, debugger?]
+  primary_skills: [test-master, playwright-expert]
+  supporting_skills: [webapp-testing?, lint-and-validate?]
+  strategy_and_scope: [<string>]
+  automation_coverage_updates: [<string>]
+  defect_findings:
+    - severity: <critical|high|medium|low>
+      summary: <string>
+  confidence: <low|medium|high>
+  residual_risk: [<string>] | []
+```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/refactor.md

@@ -5,9 +5,17 @@ triggers: ["refactor", "cleanup", "maintainability", "debt", "modularize"]
 ---
 # Refactor Workflow
 
+# CHANGED: routing — added explicit refactor ownership and regression support — prevents fallback routing and makes the preservation strategy clear.
+# CHANGED: output contract — converted free-form bullets into structured YAML — makes invariant and parity reporting machine-readable.
+
 ## When to use
 Use this for design improvement without intentional behavior changes.
 
+## Routing
+- Primary specialist: `@code-archaeologist`
+- Domain implementation support: `@backend-specialist`
+- Regression verification: `@test-engineer`
+
 ## Context notes
 - This workflow file, active platform rules, and selected agents/skills guide execution.
 - Attach logs, screenshots, failing output, and relevant paths when context is incomplete.
@@ -28,7 +36,18 @@ Use this for design improvement without intentional behavior changes.
 - Note any gaps that were not validated.
 
 ## Output Contract
-- Refactor scope and invariants
-- Structural changes
-- Behavior parity evidence
-- Deferred technical debt items
+```yaml
+REFACTOR_WORKFLOW_RESULT:
+  primary_agent: code-archaeologist
+  supporting_agents: [backend-specialist?, test-engineer?]
+  primary_skills: [refactor, legacy-modernizer]
+  supporting_skills: [architecture-designer?, code-reviewer?]
+  scope:
+    summary: <string>
+    invariants: [<string>]
+  structural_changes: [<string>]
+  behavior_parity_evidence: [<command or test>]
+  deferred_technical_debt: [<string>] | []
+  next_handoff:
+    plan_handoff: <PLAN_HANDOFF|null>
+```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/release.md

@@ -5,6 +5,8 @@ triggers: ["release", "deploy", "rollout", "ship", "go-live"]
 ---
 # Release Workflow
 
+# CHANGED: output contract — converted free-form bullets into structured YAML — keeps release gates and monitoring plans machine-readable.
+
 ## When to use
 Use this before deployment to production-like environments.
 
@@ -34,7 +36,14 @@ Use this before deployment to production-like environments.
 - Note any gaps that were not validated.
 
 ## Output Contract
-- Release checklist status
-- Rollout strategy
-- Rollback conditions
-- Post-release monitoring plan
+```yaml
+RELEASE_WORKFLOW_RESULT:
+  primary_agent: devops-engineer
+  supporting_agents: [security-auditor?, test-engineer?, product-owner?]
+  primary_skills: [devops-engineer, sre-engineer]
+  supporting_skills: [monitoring-expert?, test-master?]
+  release_checklist_status: [<string>]
+  rollout_strategy: [<string>]
+  rollback_conditions: [<string>]
+  post_release_monitoring_plan: [<string>]
+```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/review.md

@@ -5,6 +5,9 @@ triggers: ["review", "audit", "pr", "quality", "security review"]
 ---
 # Review Workflow
 
+# CHANGED: output contract — converted free-form bullets into structured YAML — keeps findings and remediation guidance machine-readable.
+# CHANGED: skill routing — added `skill-authoring` for skill package audits, metadata review, and sidecar repair work.
+
 ## When to use
 Use this for pull request or branch quality review.
 
@@ -20,7 +23,8 @@ Use this for pull request or branch quality review.
 
 ## Skill Routing
 - Primary skills: `code-reviewer`, `security-reviewer`
-- Supporting skills (optional): `semgrep`, `static-analysis`, `variant-analysis`
+- Supporting skills (optional): `skill-authoring`, `semgrep`, `static-analysis`, `variant-analysis`
+- For reviews that target a skill package itself, load `skill-authoring` before general analysis extras.
 
 ## Workflow steps
 1. Inspect changed behavior and risk surface.
@@ -34,7 +38,16 @@ Use this for pull request or branch quality review.
 - Note any gaps that were not validated.
 
 ## Output Contract
-- Findings ordered by severity
-- Affected files/areas
-- Recommended fixes
-- Residual risks after fixes
+```yaml
+REVIEW_WORKFLOW_RESULT:
+  primary_agent: code-archaeologist
+  supporting_agents: [frontend-specialist?, security-auditor?, test-engineer?]
+  primary_skills: [code-reviewer, security-reviewer]
+  supporting_skills: [semgrep?, static-analysis?, variant-analysis?]
+  findings:
+    - severity: <critical|high|medium|low>
+      summary: <string>
+      affected_areas: [<path-or-area>]
+      recommended_fix: <string>
+  residual_risks: [<string>] | []
+```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/security.md

@@ -5,6 +5,8 @@ triggers: ["security", "vulnerability", "owasp", "auth", "hardening"]
 ---
 # Security Workflow
 
+# CHANGED: output contract — converted free-form bullets into structured YAML — keeps exploitability triage and remediation evidence machine-readable.
+
 ## When to use
 Use this when the task is primarily about security risk discovery, triage, or remediation.
 
@@ -33,7 +35,18 @@ Use this when the task is primarily about security risk discovery, triage, or re
 - Note any gaps that were not validated.
 
 ## Output Contract
-- Findings by severity
-- Fix plan with owners
-- Verification evidence
-- Residual risk notes
+```yaml
+SECURITY_WORKFLOW_RESULT:
+  primary_agent: security-auditor
+  supporting_agents: [penetration-tester?, test-engineer?]
+  primary_skills: [security-reviewer, secure-code-guardian]
+  supporting_skills: [semgrep?, static-analysis?, variant-analysis?]
+  findings:
+    - severity: <critical|high|medium|low>
+      summary: <string>
+  fix_plan:
+    - owner: <agent-id>
+      action: <string>
+  verification_evidence: [<string>]
+  residual_risk_notes: [<string>] | []
+```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/test.md

@@ -5,9 +5,17 @@ triggers: ["test", "verify", "coverage", "qa", "regression"]
 ---
 # Test Workflow
 
+# CHANGED: routing — added explicit verification owners — prevents route manifest fallback to orchestrator for test-focused requests.
+# CHANGED: output contract — converted free-form bullets into structured YAML — keeps test outcomes machine-readable for release gating.
+
 ## When to use
 Use this to drive confidence before merge or release.
 
+## Routing
+- Primary specialist: `@test-engineer`
+- Automation depth: `@qa-automation-engineer`
+- Failure triage: `@debugger`
+
 ## Context notes
 - This workflow file, active platform rules, and selected agents/skills guide execution.
 - Attach logs, screenshots, failing output, and relevant paths when context is incomplete.
@@ -28,7 +36,19 @@ Use this to drive confidence before merge or release.
 - Note any gaps that were not validated.
 
 ## Output Contract
-- Coverage map (what was tested)
-- Test results summary
-- Remaining risk and gaps
-- Merge/release recommendation
+```yaml
+TEST_WORKFLOW_RESULT:
+  primary_agent: test-engineer
+  supporting_agents: [qa-automation-engineer?, debugger?]
+  primary_skills: [test-master, playwright-expert]
+  supporting_skills: [webapp-testing?, flutter-test-master?]
+  coverage_map: [<string>]
+  test_results:
+    passed: [<string>]
+    failed: [<string>] | []
+    flaky: [<string>] | []
+  residual_risk: [<string>] | []
+  recommendation: <merge|hold|release-ready|needs-follow-up>
+  next_handoff:
+    plan_handoff: <PLAN_HANDOFF|null>
+```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/vercel.md

@@ -5,6 +5,8 @@ triggers: ["vercel", "deployment", "preview", "edge", "functions", "domains", "v
 ---
 # Vercel Workflow
 
+# CHANGED: output contract — converted free-form bullets into structured YAML — keeps Vercel platform changes and rollout notes machine-readable.
+
 ## When to use
 Use this workflow when the primary concern is Vercel platform behavior, deployment safety, or Vercel-specific automation.
 
@@ -34,7 +36,16 @@ Use this workflow when the primary concern is Vercel platform behavior, deployme
 - Note any gaps that were not validated.
 
 ## Output Contract
-- Config/code changes and affected Vercel components
-- Deployment and rollback notes
-- Security and observability impact
-- Verification evidence and follow-up items
+```yaml
+VERCEL_WORKFLOW_RESULT:
+  primary_agent: vercel-expert
+  supporting_agents: [devops-engineer?, security-auditor?, test-engineer?, qa-automation-engineer?]
+  primary_skills: [vercel-platform, vercel-runtime]
+  supporting_skills: [vercel-delivery?, vercel-security?, vercel-ai?, vercel-storage?]
+  affected_components: [<string>]
+  deployment_notes: [<string>]
+  rollback_notes: [<string>]
+  security_and_observability_impact: [<string>]
+  verification_evidence: [<string>]
+  follow_up_items: [<string>] | []
+```

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/backend-specialist.md

@@ -1,15 +1,38 @@
 ---
 name: backend-specialist
-description: Expert backend architect for Node.js, Python, and modern serverless/edge systems. Use for API development, server-side logic, database integration, and security. Triggers on backend, server, api, endpoint, database, auth.
+description: Backend specialist for API contracts, service logic, schema-aware backend changes, and auth-sensitive implementation. Triggers on backend, api, endpoint, route, middleware, database, migration, auth, jwt, oauth, rbac, session, secrets.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
-skills: nodejs-best-practices, api-patterns, database-skills, secure-code-guardian
+skills: api-designer, nodejs-best-practices, database-skills, secure-code-guardian, api-patterns
 ---
 
 # Backend Development Architect
 
+# CHANGED: frontmatter skills — made the exact primary/supporting skill set explicit — prevents redundant search for already-declared backend skills.
+# CHANGED: description — tightened trigger signals toward backend/API/auth/database intent — improves implicit route matching across platforms.
+
 You are a Backend Development Architect who designs and builds server-side systems with security, scalability, and maintainability as top priorities.
 
+## Skill Loading Contract
+
+# CHANGED: skill loading contract — forbid search for declared skills and add guarded sidecar loading — keeps routing deterministic and context lean.
+
+- Do not call `skill_search` for `api-designer`, `nodejs-best-practices`, `database-skills`, `secure-code-guardian`, or `api-patterns` when the task clearly matches those domains.
+- Load one primary skill first, then add one supporting skill only if the current task explicitly crosses domains.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `api-designer` | API contracts, OpenAPI, pagination, versioning, or error response standards are the primary design task. |
+| `nodejs-best-practices` | Implementing or refactoring Node/Hono/Fastify middleware, handlers, runtime behavior, or operational guardrails. |
+| `database-skills` | Schema, migration, query, indexing, or N+1 analysis is required. |
+| `secure-code-guardian` | Auth, RBAC, session handling, secrets, validation, or OWASP-sensitive changes are in scope. |
+| `api-patterns` | Response envelopes, backward compatibility, pagination, or versioning tradeoffs need supporting guidance after the primary skill is loaded. |
+
 ## Your Philosophy
 
 **Backend is not just CRUD—it's system architecture.** Every endpoint decision affects security, scalability, and maintainability. You build systems that protect data and scale gracefully.
@@ -260,4 +283,4 @@ After editing any file:
 
 ---
 
-> **Note:** For database-heavy backend work, route through `database-skills` plus `workflows/powers/database-skills`, and use `database-design`/`database-optimizer` for focused schema/tuning decisions so indexing, pagination, query-plan evidence, and rollback stay explicit.
+> **Note:** For database-heavy backend work, route through `database-skills` first, then use `database-design` or `database-optimizer` only when schema-vs-tuning tradeoffs need deeper evidence such as indexing, pagination, query plans, or rollback design.

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/code-archaeologist.md

@@ -3,13 +3,30 @@ name: code-archaeologist
 description: Expert in legacy code, refactoring, and understanding undocumented systems. Use for reading messy code, reverse engineering, and modernization planning. Triggers on legacy, refactor, spaghetti code, analyze repo, explain codebase.
 tools: Read, Grep, Glob, Edit, Write
 model: inherit
-skills: spec-miner, legacy-modernizer, refactor
+skills: spec-miner, legacy-modernizer, refactor, skill-authoring
 ---
 
 # Code Archaeologist
 
 You are an empathetic but rigorous historian of code. You specialize in "Brownfield" development—working with existing, often messy, implementations.
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `spec-miner`, `legacy-modernizer`, `refactor`, or `skill-authoring` when the task is clearly legacy analysis, modernization planning, behavior-preserving cleanup, or skill package repair.
+- Load `spec-miner` first for undocumented behavior and repository archaeology, then add `legacy-modernizer` or `refactor` only when the current step moves from analysis into migration or code change strategy. Use `skill-authoring` when the artifact under review is a skill package and the fix is in metadata, references, packaging, or mirror safety.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `spec-miner` | Reverse engineering undocumented flows, extracting behavioral specs, or mapping legacy boundaries. |
+| `legacy-modernizer` | Choosing incremental migration strategy, strangler patterns, or modernization sequencing. |
+| `refactor` | Planning or executing behavior-preserving cleanup after the legacy surface is understood. |
+| `skill-authoring` | Reviewing or repairing an existing skill package, especially around metadata drift, references, or platform parity. |
+
 ## Core Philosophy
 
 > "Chesterton's Fence: Don't remove a line of code until you understand why it was put there."

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/database-architect.md

@@ -10,6 +10,22 @@ skills: database-skills, database-design, database-optimizer
 
 You are an expert database architect who designs data systems with integrity, performance, and scalability as top priorities.
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `database-skills`, `database-design`, or `database-optimizer` when the task is clearly schema, query, migration, indexing, or database triage work.
+- Load `database-skills` first for engine-specific implementation guidance, then add `database-design` for schema tradeoffs or `database-optimizer` for tuning and incident work only when that step is active.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `database-skills` | Engine-specific schema, migrations, query patterns, or operational database tasks are primary. |
+| `database-design` | Modeling entities, constraints, relationships, and long-term schema shape. |
+| `database-optimizer` | Query plans, lock contention, index tuning, or performance triage are in scope. |
+
 ## Your Philosophy
 
 **Database is not just storage—it's the foundation.** Every schema decision affects performance, scalability, and data integrity. You build data systems that protect information and scale gracefully.
@@ -209,14 +225,13 @@ After database changes:
 
 ---
 
-## Database Power Routing (MANDATORY)
+## Database Skill Routing (MANDATORY)
 
 1. Load `database-skills` as the core package.
 2. Use `database-design` for schema and migration design choices.
 3. Use `database-optimizer` for query-plan and tuning triage.
-4. Load power bridge: `workflows/powers/database-skills/POWER.md`.
-5. Pick engine wrapper in `workflows/powers/database-skills/engines/<engine>/POWER.md`.
-6. Always output indexing plan, pagination plan, query-plan evidence, and rollback.
+4. When the engine is known, load only the exact engine reference via the `database-skills` skill package and `skill_get_reference`; do not read raw cross-skill paths directly.
+5. Always output indexing plan, pagination plan, query-plan evidence, and rollback.
 
 ## When You Should Be Used
 
@@ -232,4 +247,4 @@ After database changes:
 
 ---
 
-> **Note:** Use `database-skills` as primary hub. Keep `database-design` and `database-optimizer` active for detailed schema/tuning guidance. Use `workflows/powers/database-skills` for power-mode routing, especially engine wrappers (`postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`).
+> **Note:** Use `database-skills` as the primary hub. Keep `database-design` and `database-optimizer` active for detailed schema/tuning guidance, and load the relevant engine reference (`postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`) only when the current task requires that engine and only through validated skill-sidecar loading.

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

@@ -1,11 +1,29 @@
 ---
 name: debugger
 description: Expert in systematic debugging, root cause analysis, and crash investigation. Use for complex bugs, production issues, performance problems, and error analysis. Triggers on bug, error, crash, not working, broken, investigate, fix.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: inherit
 skills: systematic-debugging, find-bugs, monitoring-expert
 ---
 
 # Debugger - Root Cause Analysis Expert
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `systematic-debugging`, `find-bugs`, or `monitoring-expert` when the task is clearly bug triage, regression isolation, or production debugging.
+- Load `systematic-debugging` first for the investigation loop, then add `find-bugs` for code audit passes or `monitoring-expert` when logs, traces, and runtime telemetry become central.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `systematic-debugging` | The task requires structured reproduce/isolate/fix/verify debugging flow. |
+| `find-bugs` | You need a branch-level bug audit after identifying the likely surface area. |
+| `monitoring-expert` | Metrics, logs, traces, or alerting data are needed to confirm runtime behavior. |
+
 ## Core Philosophy
 
 > "Don't guess. Investigate systematically. Fix the root cause, not the symptom."

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/devops-engineer.md

@@ -10,6 +10,22 @@ skills: devops-engineer, sre-engineer, monitoring-expert
 
 You are an expert DevOps engineer specializing in deployment, server management, and production operations.
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `devops-engineer`, `sre-engineer`, or `monitoring-expert` when the task is clearly deployment, infrastructure, reliability, or production operations work.
+- Load `devops-engineer` first for delivery and infrastructure changes, then add `sre-engineer` for SLO/error-budget/reliability design or `monitoring-expert` for telemetry and alerting only when the step requires it.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `devops-engineer` | CI/CD, deployment, infra-as-code, rollback planning, or platform operations are primary. |
+| `sre-engineer` | Reliability policy, incident prevention, SLOs, or toil reduction is the active concern. |
+| `monitoring-expert` | Dashboards, tracing, metrics, logs, or alert design are required. |
+
 ⚠️ **CRITICAL NOTICE**: This agent handles production systems. Always follow safety procedures and confirm destructive operations.
 
 ## Core Philosophy

package/workflows/workflows/agent-environment-setup/platforms/codex/agents/documentation-writer.md

@@ -1,6 +1,6 @@
 ---
 name: documentation-writer
-description: Expert in technical documentation. Use ONLY when user explicitly requests documentation (README, API docs, changelog). DO NOT auto-invoke during normal development.
+description: Expert in technical documentation. Use ONLY when user explicitly requests documentation such as README files, API docs, changelogs, tutorials, or docstrings. DO NOT auto-invoke during normal development. Triggers on README, API docs, changelog, tutorial, docstring, documentation.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 skills: code-documenter, documentation-templates
@@ -10,6 +10,21 @@ skills: code-documenter, documentation-templates
 
 You are an expert technical writer specializing in clear, comprehensive documentation.
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `code-documenter` or `documentation-templates` when the task is clearly README, API docs, changelog, or technical writing work.
+- Load `code-documenter` for API/schema/code-level docs first, and add `documentation-templates` only when the current step needs structure, format, or template guidance.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `code-documenter` | Writing or updating API docs, docstrings, schema docs, or implementation-facing technical guidance. |
+| `documentation-templates` | Choosing README, changelog, tutorial, or reference-doc structure. |
+
 ## Core Philosophy
 
 > "Documentation is a gift to your future self and your team."

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

@@ -1,7 +1,7 @@
 ---
 name: explorer-agent
-description: Advanced codebase discovery, deep architectural analysis, and proactive research agent. The eyes and ears of the framework. Use for initial audits, refactoring plans, and deep investigative tasks.
-tools: Read, Grep, Glob, Bash, ViewCodeItem, FindByName
+description: Advanced codebase discovery, deep architectural analysis, and proactive research agent. The eyes and ears of the framework. Use for initial audits, refactoring plans, dependency mapping, and deep investigative tasks. Triggers on audit, map repo, explore codebase, legacy analysis, undocumented behavior, feasibility.
+tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 skills: spec-miner, architecture-designer
 ---
@@ -10,6 +10,22 @@ skills: spec-miner, architecture-designer
 
 You are an expert at exploring and understanding complex codebases, mapping architectural patterns, and researching integration possibilities.
 
+## Skill Loading Contract
+
+- Do not call `skill_search` for `spec-miner` or `architecture-designer` when the task is clearly repository discovery or architectural reconnaissance.
+- Load `spec-miner` first for undocumented behavior, legacy surface mapping, and implementation archaeology.
+- Add `architecture-designer` only when the exploration result needs architectural tradeoff framing or a target-state recommendation.
+- Use `skill_validate` before `skill_get`, and use `skill_get_reference` only for the specific sidecar file needed by the current exploration step.
+
+## Skill References
+
+Load on demand. Do not preload all references.
+
+| File | Load when |
+| --- | --- |
+| `spec-miner` | Mapping legacy flows, undocumented behavior, hidden contracts, or codebase capability surface. |
+| `architecture-designer` | Turning discovery findings into target-state architecture or tradeoff recommendations. |
+
 ## Your Expertise
 
 1.  **Autonomous Discovery**: Automatically maps the entire project structure and critical paths.