@cubis/foundry 0.3.77 → 0.3.78

package/workflows/workflows/agent-environment-setup/shared/workflows/implement-track.md

@@ -20,12 +20,14 @@ Use this for large-scale implementation work that spans multiple sessions or mil
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the implementation plan, milestone definitions, and acceptance criteria per milestone.
+- Reuse `docs/specs/<spec-id>/` when present instead of maintaining a separate progress source of truth.
+- Read `ENGINEERING_RULES.md` first and `TECH.md` next before starting milestone execution.
 
 ## Skill Routing
 
-- Primary skills: `architecture-designer`, `api-designer`
-- Supporting skills (optional): `database-skills`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`, `react-expert`, `nextjs-developer`
-- Start with `architecture-designer` for milestone planning. Load domain-specific skills per milestone based on implementation needs.
+- Primary skills: `system-design`, `api-design`
+- Supporting skills (optional): `database-design`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`, `react-expert`, `nextjs-developer`
+- Start with `system-design` for milestone planning. Load domain-specific skills per milestone based on implementation needs.
 
 ## Workflow steps
 
@@ -33,7 +35,7 @@ Use this for large-scale implementation work that spans multiple sessions or mil
 2. Execute current milestone with focused implementation.
 3. Run quality gate validation at milestone completion.
 4. Update progress tracking and capture status.
-5. Adjust remaining plan based on learnings.
+5. Adjust remaining plan, spec traceability, and doc refresh needs based on learnings.
 6. Proceed to next milestone or report completion.
 
 ## Verification
@@ -49,8 +51,8 @@ Use this for large-scale implementation work that spans multiple sessions or mil
 IMPLEMENT_TRACK_WORKFLOW_RESULT:
   primary_agent: orchestrator
   supporting_agents: [<milestone-agents>]
-  primary_skills: [architecture-designer, api-designer]
-  supporting_skills: [database-skills?, typescript-pro?, javascript-pro?, python-pro?, golang-pro?, react-expert?, nextjs-developer?]
+  primary_skills: [system-design, api-design]
+  supporting_skills: [database-design?, typescript-pro?, javascript-pro?, python-pro?, golang-pro?, react-expert?, nextjs-developer?]
   milestones:
     - id: <milestone-id>
       description: <string>
@@ -59,5 +61,9 @@ IMPLEMENT_TRACK_WORKFLOW_RESULT:
       validation_evidence: <string>
   overall_progress: <percentage>
   scope_changes: [<string>] | []
+  spec_id: <string> | null
+  spec_root: docs/specs/<spec-id> | null
+  traceability_status: complete | partial | blocked
+  doc_impact: none | tech | rules | both
   follow_up_items: [<string>] | []
 ```

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

@@ -28,12 +28,13 @@ Use this for technology migrations, framework upgrades, dependency updates, or m
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the migration target, current versions, breaking change lists, and impact assessment.
+- Read `ENGINEERING_RULES.md` and `TECH.md` first because migrations often change accepted patterns and current-state architecture at the same time.
 
 ## Skill Routing
 
-- Primary skills: `legacy-modernizer`, `architecture-designer`
+- Primary skills: `legacy-modernizer`, `system-design`
 - Supporting skills (optional): `static-analysis`, `testing-patterns`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`
-- Start with `legacy-modernizer` for migration methodology and `architecture-designer` for system impact. Add `static-analysis` for automated codemod or compatibility analysis.
+- Start with `legacy-modernizer` for migration methodology and `system-design` for system impact. Add `static-analysis` for automated codemod or compatibility analysis.
 
 ## Workflow steps
 
@@ -42,7 +43,8 @@ Use this for technology migrations, framework upgrades, dependency updates, or m
 3. Plan incremental migration steps with rollback points.
 4. Execute migration one step at a time with verification.
 5. Update tests and documentation for new patterns.
-6. Verify full system behavior after migration complete.
+6. Set `doc_impact` when the migration changes architecture, deployment shape, boundaries, or design-system rules.
+7. Verify full system behavior after migration complete.
 
 ## Verification
 
@@ -58,7 +60,7 @@ Use this for technology migrations, framework upgrades, dependency updates, or m
 MIGRATE_WORKFLOW_RESULT:
   primary_agent: code-archaeologist
   supporting_agents: [backend-specialist?, frontend-specialist?, test-engineer?, validator?]
-  primary_skills: [legacy-modernizer, architecture-designer]
+  primary_skills: [legacy-modernizer, system-design]
   supporting_skills: [static-analysis?, testing-patterns?]
   migration:
     from: <string>
@@ -69,5 +71,6 @@ MIGRATE_WORKFLOW_RESULT:
   verification:
     tests_passed: true | false
     performance_impact: <string>
+  doc_impact: none | tech | rules | both
   follow_up_items: [<string>] | []
 ```

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

@@ -20,6 +20,7 @@ Use this for mobile app development, Flutter architecture, Stitch-driven mobile
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach platform targets (iOS, Android, both), Flutter version, and relevant screen/feature context.
+- Read `ENGINEERING_RULES.md` and `TECH.md` before implementing non-trivial mobile work so screens and features follow the declared architecture and design-system rules.
 
 ## Skill Routing
 
@@ -35,6 +36,7 @@ Use this for mobile app development, Flutter architecture, Stitch-driven mobile
 3. Implement with consideration for iOS/Android differences.
 4. Write widget and integration tests.
 5. Review for platform-specific edge cases and UX conventions.
+6. Set `doc_impact` if the feature changes navigation, shared UI rules, or mobile architecture conventions.
 
 ## Verification
 
@@ -62,5 +64,6 @@ MOBILE_WORKFLOW_RESULT:
   platform_notes:
     ios: [<string>] | []
     android: [<string>] | []
+  doc_impact: none | tech | rules | both
   follow_up_items: [<string>] | []
 ```

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

@@ -27,12 +27,13 @@ Use this when joining a new project, exploring an unfamiliar codebase, or prepar
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Provide the repo URL, focus areas, and any specific questions to answer during onboarding.
+- Read `ENGINEERING_RULES.md` first and `TECH.md` next when present so onboarding distinguishes the intended contract from current implementation reality.
 
 ## Skill Routing
 
-- Primary skills: `deep-research`, `architecture-designer`
-- Supporting skills (optional): `legacy-modernizer`, `database-skills`, `typescript-pro`, `javascript-pro`, `python-pro`
-- Start with `deep-research` for systematic exploration and `architecture-designer` for architecture mapping. Add `legacy-modernizer` for undocumented systems. Prefer repo evidence first; use external sources only when setup or dependency behavior cannot be confirmed locally.
+- Primary skills: `deep-research`, `system-design`
+- Supporting skills (optional): `legacy-modernizer`, `database-design`, `typescript-pro`, `javascript-pro`, `python-pro`
+- Start with `deep-research` for systematic exploration and `system-design` for architecture mapping. Add `legacy-modernizer` for undocumented systems. Prefer repo evidence first; use external sources only when setup or dependency behavior cannot be confirmed locally.
 
 ## Workflow steps
 
@@ -55,8 +56,8 @@ Use this when joining a new project, exploring an unfamiliar codebase, or prepar
 ONBOARD_WORKFLOW_RESULT:
   primary_agent: researcher
   supporting_agents: [code-archaeologist?, backend-specialist?, frontend-specialist?]
-  primary_skills: [deep-research, architecture-designer]
-  supporting_skills: [legacy-modernizer?, database-skills?]
+  primary_skills: [deep-research, system-design]
+  supporting_skills: [legacy-modernizer?, database-design?]
   project_overview:
     purpose: <string>
     tech_stack: [<string>]

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

@@ -20,12 +20,13 @@ Use this when a task spans multiple domains (backend + frontend, security + infr
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the full task description, constraints, acceptance criteria, and relevant context when starting.
+- Read `ENGINEERING_RULES.md` and `TECH.md` before decomposing non-trivial work, then reuse any existing `docs/specs/<spec-id>/` pack as the handoff source of truth.
 
 ## Skill Routing
 
-- Primary skills: `architecture-designer`, `api-designer`
-- Supporting skills (optional): `database-skills`, `deep-research`, `mcp-builder`, `openai-docs`, `prompt-engineer`, `skill-creator`
-- Start with `architecture-designer` for system design coordination and `api-designer` for integration contracts. Add `deep-research` before implementation when the coordination challenge depends on fresh external facts or public comparison.
+- Primary skills: `system-design`, `api-design`
+- Supporting skills (optional): `database-design`, `deep-research`, `mcp-server-builder`, `openai-docs`, `prompt-engineering`, `skill-creator`
+- Start with `system-design` for system design coordination and `api-design` for integration contracts. Add `deep-research` before implementation when the coordination challenge depends on fresh external facts or public comparison.
 
 ## Workflow steps
 
@@ -34,7 +35,8 @@ Use this when a task spans multiple domains (backend + frontend, security + infr
 3. Delegate each task to the best specialist agent with full context.
 4. Validate each deliverable against acceptance criteria via independent validation.
 5. Iterate on failed validations with specific feedback (max 3 iterations).
-6. Integrate outputs, verify cross-task consistency, and report results.
+6. Surface `doc_impact` when the coordinated work changes architecture, boundaries, scale, or the design system.
+7. Integrate outputs, verify cross-task consistency, and report results.
 
 ## Verification
 
@@ -49,8 +51,10 @@ Use this when a task spans multiple domains (backend + frontend, security + infr
 ORCHESTRATE_WORKFLOW_RESULT:
   primary_agent: orchestrator
   supporting_agents: [<specialist-agents-used>]
-  primary_skills: [architecture-designer, api-designer]
+  primary_skills: [system-design, api-design]
   supporting_skills: [<supporting-skills-used>]
+  spec_id: <string> | null
+  spec_root: docs/specs/<spec-id> | null
   task_count: <number>
   completed: <number>
   failed: <number>
@@ -61,6 +65,7 @@ ORCHESTRATE_WORKFLOW_RESULT:
       iterations: <number>
       validation_evidence: <string>
   integration_status: clean | conflicts_resolved | issues_remaining
+  doc_impact: none | tech | rules | both
   remaining_risks: [<string>] | []
   follow_up_actions: [<string>] | []
 ```

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

@@ -4,7 +4,6 @@ description: "Build a decision-complete implementation plan with interfaces, fai
 triggers:
   [
     "plan",
-    "spec",
     "design",
     "roadmap",
     "acceptance",
@@ -32,12 +31,14 @@ Use this when starting a new feature, project, or significant change that needs
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the feature request, problem statement, constraints, and any existing design documents.
+- Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist before finalizing a non-trivial plan.
+- Reuse an existing `docs/specs/<spec-id>/` pack when the change already has one instead of creating a parallel planning track.
 
 ## Skill Routing
 
-- Primary skills: `architecture-designer`, `api-designer`
-- Supporting skills (optional): `database-skills`, `deep-research`, `mcp-builder`, `openai-docs`, `prompt-engineer`, `skill-creator`
-- Start with `architecture-designer` for system design and `api-designer` for API contracts. Add `database-skills` when data modeling is central, `deep-research` when fresh external knowledge or public comparison is needed.
+- Primary skills: `system-design`, `api-design`
+- Supporting skills (optional): `database-design`, `deep-research`, `mcp-server-builder`, `openai-docs`, `prompt-engineering`, `skill-creator`
+- Start with `system-design` for system design and `api-design` for API contracts. Add `database-design` when data modeling is central, `deep-research` when fresh external knowledge or public comparison is needed.
 
 ## Workflow steps
 
@@ -46,7 +47,8 @@ Use this when starting a new feature, project, or significant change that needs
 3. Decompose into tasks with ownership and dependencies.
 4. Define interfaces, contracts, and failure modes.
 5. Produce acceptance criteria for each milestone.
-6. Identify risks, unknowns, and mitigation strategies.
+6. Record `architecture_impact`, `doc_impact`, and `traceability_status` when the work is non-trivial.
+7. Identify risks, unknowns, and mitigation strategies.
 
 ## Verification
 
@@ -61,8 +63,10 @@ Use this when starting a new feature, project, or significant change that needs
 PLAN_WORKFLOW_RESULT:
   primary_agent: project-planner
   supporting_agents: [orchestrator?, backend-specialist?, frontend-specialist?, database-architect?]
-  primary_skills: [architecture-designer, api-designer]
-  supporting_skills: [database-skills?, deep-research?, mcp-builder?]
+  primary_skills: [system-design, api-design]
+  supporting_skills: [database-design?, deep-research?, mcp-server-builder?]
+  spec_id: <string> | null
+  spec_root: docs/specs/<spec-id> | null
   plan:
     scope_summary: <string>
     tasks:
@@ -74,5 +78,11 @@ PLAN_WORKFLOW_RESULT:
     interfaces: [<string>]
     risks: [<string>]
     milestones: [<string>]
+  architecture_impact:
+    summary: <string>
+    affects_structure: true | false
+    affects_design_system: true | false
+  doc_impact: none | tech | rules | both
+  traceability_status: complete | partial | blocked
   follow_up_items: [<string>] | []
 ```

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

@@ -20,11 +20,12 @@ Use this when improving code structure, reducing tech debt, or modularizing with
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the target code, pain points, and any constraints on what can change.
+- Read `ENGINEERING_RULES.md` and `TECH.md` first so behavior-preserving structure changes do not drift from the accepted architecture contract.
 
 ## Skill Routing
 
 - Primary skills: `static-analysis`, `legacy-modernizer`
-- Supporting skills (optional): `testing-patterns`, `architecture-designer`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`
+- Supporting skills (optional): `testing-patterns`, `system-design`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`
 - Start with `static-analysis` for automated code quality assessment. Add `legacy-modernizer` for modernization patterns. Add `testing-patterns` when refactoring needs test coverage to proceed safely.
 
 ## Workflow steps
@@ -34,6 +35,7 @@ Use this when improving code structure, reducing tech debt, or modularizing with
 3. Apply one refactoring at a time with behavior preservation.
 4. Verify behavior unchanged after each step.
 5. Document the improved structure and any conventions established.
+6. Set `doc_impact` when the refactor changes project structure, module boundaries, or design-system conventions.
 
 ## Verification
 
@@ -49,7 +51,7 @@ REFACTOR_WORKFLOW_RESULT:
   primary_agent: code-archaeologist
   supporting_agents: [backend-specialist?, frontend-specialist?, test-engineer?, validator?]
   primary_skills: [static-analysis, legacy-modernizer]
-  supporting_skills: [testing-patterns?, architecture-designer?]
+  supporting_skills: [testing-patterns?, system-design?]
   refactoring_summary:
     targets: [<string>]
     changes_applied: [<string>]
@@ -57,6 +59,7 @@ REFACTOR_WORKFLOW_RESULT:
   quality_improvement:
     complexity_before: <string>
     complexity_after: <string>
+  doc_impact: none | tech | rules | both
   tests_added: [<test-file-path>] | []
   follow_up_items: [<string>] | []
 ```

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

@@ -20,6 +20,7 @@ Use this when preparing a release, deploying to production, or managing a rollou
 
 - This workflow file, active platform rules, and selected agents or skills guide execution.
 - Attach the release scope, version number, changelog draft, and deployment target.
+- Read `ENGINEERING_RULES.md` and `TECH.md` before release if the shipped changes touched architecture, scaling assumptions, or design-system rules.
 
 ## Skill Routing
 
@@ -35,6 +36,7 @@ Use this when preparing a release, deploying to production, or managing a rollou
 4. Execute staged rollout with health checks at each stage.
 5. Verify production health post-deployment.
 6. Document rollback procedure and post-release status.
+7. Set `doc_impact` if the release includes architecture-affecting work that should refresh the managed docs.
 
 ## Verification
 
@@ -61,5 +63,6 @@ RELEASE_WORKFLOW_RESULT:
     stages_completed: [<string>]
     health_checks: [<string>]
   rollback_plan: <string>
+  doc_impact: none | tech | rules | both
   follow_up_items: [<string>] | []
 ```

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

@@ -25,7 +25,7 @@ Use this for security audits, vulnerability assessments, threat modeling, or sec
 ## Skill Routing
 
 - Primary skills: `security-engineer`, `auth-architect`
-- Supporting skills (optional): `vulnerability-scanner`, `static-analysis`, `api-designer`, `graphql-architect`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`, `rust-pro`
+- Supporting skills (optional): `vulnerability-scanner`, `static-analysis`, `api-design`, `graphql-architect`, `typescript-pro`, `javascript-pro`, `python-pro`, `golang-pro`, `rust-pro`
 - Start with `security-engineer` for OWASP methodology and threat modeling. Add `auth-architect` for authentication/authorization review. Add `vulnerability-scanner` for dependency scanning and CVE triage.
 
 ## Workflow steps
@@ -51,7 +51,7 @@ SECURITY_WORKFLOW_RESULT:
   primary_agent: security-auditor
   supporting_agents: [penetration-tester?, backend-specialist?, frontend-specialist?, validator?]
   primary_skills: [security-engineer, auth-architect]
-  supporting_skills: [vulnerability-scanner?, static-analysis?, api-designer?]
+  supporting_skills: [vulnerability-scanner?, static-analysis?, api-design?]
   threat_model:
     assets: [<string>]
     threats: [<string>]

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

@@ -0,0 +1,79 @@
+---
+command: "/spec"
+description: "Create or refresh a Git-tracked spec pack for non-trivial work, including acceptance criteria, traceability, architecture impact, and next-route handoff."
+triggers:
+  [
+    "spec",
+    "sdd",
+    "source of truth",
+    "traceability",
+    "acceptance criteria",
+    "openspec",
+    "requirements",
+    "architecture impact",
+  ]
+---
+
+# Spec Workflow
+
+## When to use
+
+Use this for non-trivial work that needs durable planning in Git before implementation: medium or large features, multi-step changes, cross-session work, migrations, risky refactors, or any request that needs explicit acceptance and traceability.
+
+## Routing
+
+- Primary coordinator: `@project-planner`
+- Traceability and requirements support: `@researcher`
+- Cross-domain coordination: `@orchestrator`
+- Documentation and structure support: `@documentation-writer`
+
+## Skill Routing
+
+- Primary skills: `spec-driven-delivery`, `sadd`
+- Supporting skills (optional): `system-design`, `architecture-doc`, `deep-research`, `api-design`, `database-design`, `tech-doc`
+- Start with `spec-driven-delivery` for the pack structure and handoff contract. Add `sadd` when mining requirements into testable assertions, `system-design` or `architecture-doc` when the spec changes structure, and `deep-research` only when repo-local evidence is insufficient.
+
+## Workflow steps
+
+1. Determine whether the task is non-trivial enough to justify a spec pack.
+2. Find an existing `docs/specs/<spec-id>/` pack or create a new stable `spec_id`.
+3. Write or refresh the spec pack with brief, acceptance, tasks, traceability, and handoff files.
+4. Record `architecture_impact`, `doc_impact`, and any required updates to `ENGINEERING_RULES.md` or `TECH.md`.
+5. Identify the next execution route and hand off without replanning the same work.
+
+## Context notes
+
+- Read `ENGINEERING_RULES.md` first and `TECH.md` next when they exist because they define the accepted architecture contract and current state.
+- Prefer repo evidence first; escalate to `deep-research` only when freshness, public comparison, or explicit research requests require it.
+- Keep spec packs lean. Trivial one-step tasks should stay on the lightweight path with no new spec directory.
+
+## Verification
+
+- `spec_id` and `spec_root` are stable and explicit.
+- Acceptance criteria are testable and traceable.
+- Task dependencies form a valid execution order.
+- `architecture_impact`, `doc_impact`, and `traceability_status` are present.
+
+## Output Contract
+
+```yaml
+SPEC_WORKFLOW_RESULT:
+  primary_agent: project-planner
+  supporting_agents: [researcher?, orchestrator?, documentation-writer?]
+  primary_skills: [spec-driven-delivery, sadd]
+  supporting_skills: [system-design?, architecture-doc?, deep-research?, api-design?, database-design?, tech-doc?]
+  spec_id: <string>
+  spec_root: docs/specs/<spec-id>
+  architecture_impact:
+    summary: <string>
+    affects_structure: true | false
+    affects_design_system: true | false
+    affects_testing_strategy: true | false
+  doc_impact: none | tech | rules | both
+  traceability_status: complete | partial | blocked
+  documents:
+    created: [<path>] | []
+    updated: [<path>] | []
+  next_route: </create | /implement-track | /orchestrate | /architecture | direct>
+  gaps: [<string>] | []
+```