@cubis/foundry 0.3.70 → 0.3.72

package/workflows/powers/ask-questions-if-underspecified/SKILL.md

@@ -1,17 +1,27 @@
 ---
 name: ask-questions-if-underspecified
-description: Clarify requirements before implementing. Use when serious doubts arise.
+description: Clarify requirements before implementing. Use when serious doubts arise about objective, scope, constraints, environment, or safety — or when the task is substantial enough that being wrong wastes significant effort.
 ---
 
 # Ask Questions If Underspecified
 
 ## When to Use
 
-Use this skill when a request has multiple plausible interpretations or key details (objective, scope, constraints, environment, or safety) are unclear.
+Use this skill when a request has multiple plausible interpretations or key details (objective, scope, constraints, environment, or safety) are unclear — **and** when the cost of implementing the wrong interpretation is significant.
+
+Three situations require clarification:
+
+1. **High branching** — Multiple plausible interpretations produce significantly different implementations
+2. **Substantial deliverable** — The task is large enough that wrong assumptions waste real time
+3. **Safety-critical** — The action is hard to reverse (data migrations, deployments, file deletions)
 
 ## When NOT to Use
 
-Do not use this skill when the request is already clear, or when a quick, low-risk discovery read can answer the missing details.
+Do not use this skill when:
+
+- The request is already clear and one interpretation is obviously correct
+- A quick discovery read (config files, existing patterns, repo structure) can answer the missing details faster than asking
+- The task is small enough that being slightly wrong is cheap and correctable
 
 ## Goal
 
@@ -22,6 +32,7 @@ Ask the minimum set of clarifying questions needed to avoid wrong work; do not s
 ### 1) Decide whether the request is underspecified
 
 Treat a request as underspecified if after exploring how to perform the work, some or all of the following are not clear:
+
 - Define the objective (what should change vs stay the same)
 - Define "done" (acceptance criteria, examples, edge cases)
 - Define scope (which files/components/users are in/out)
@@ -36,6 +47,7 @@ If multiple plausible interpretations exist, assume it is underspecified.
 Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.
 
 Make questions easy to answer:
+
 - Optimize for scannability (short, numbered questions; avoid paragraphs)
 - Offer multiple-choice options when possible
 - Suggest reasonable defaults when appropriate (mark them clearly as the default/recommended choice; bold the recommended choice in the list, or if you present options in a code block, put a bold "Recommended" line immediately above the block and also tag defaults inside the block)
@@ -47,10 +59,12 @@ Make questions easy to answer:
 ### 3) Pause before acting
 
 Until must-have answers arrive:
+
 - Do not run commands, edit files, or produce a detailed plan that depends on unknowns
 - Do perform a clearly labeled, low-risk discovery step only if it does not commit you to a direction (e.g., inspect repo structure, read relevant config files)
 
 If the user explicitly asks you to proceed without answers:
+
 - State your assumptions as a short numbered list
 - Ask for confirmation; proceed only after they confirm or correct them
 
@@ -83,3 +97,37 @@ Reply with: defaults (or 1a 2a)
 
 - Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
 - Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.
+- Don't ask more than 5 questions at once — rank by impact and ask the top ones.
+- Don't skip the fast-path — every clarification block needs `defaults` shortcut.
+- Don't forget to restate interpretation before proceeding — confirms you heard correctly.
+- Don't ask about reversible decisions — pick one, proceed, let them correct if wrong.
+
+## Three-Stage Pattern (for complex or substantial tasks)
+
+For tasks where wrong assumptions would waste significant effort — documents, architecture decisions, multi-file features — use a three-stage approach:
+
+### Stage 1: Meta-context questions (3-5 questions)
+
+Ask about the big picture before touching content:
+
+- What _type_ of deliverable is this? (spec, code, doc, design, plan)
+- Who's the audience/consumer?
+- What does "done" look like?
+- Existing template, format, or precedent to follow?
+- Hard constraints (framework, performance, compatibility)?
+
+### Stage 2: Info dump + targeted follow-up
+
+After Stage 1 answers: invite the user to brain-dump everything relevant.
+
+> "Dump everything you know — background, prior decisions, constraints, opinions, blockers. Don't organize it. Just get it all out."
+
+Then ask 5-10 targeted follow-up questions based on gaps. Users can answer in shorthand (`1: yes, 2: see above, 3: no`).
+
+**Exit Stage 2 when:** You understand objective, constraints, and at least one clear definition of success.
+
+### Stage 3: Confirm interpretation, then proceed
+
+Restate in 1-3 sentences before starting:
+
+> "Here's what I understand: [objective]. [Key constraint]. [What done looks like]. Starting now — correct me if anything's off."

package/workflows/powers/auth-architect/POWER.md

@@ -0,0 +1,69 @@
+````markdown
+---
+inclusion: manual
+name: auth-architect
+description: "Use when designing or reviewing authentication and authorization for backend systems, including sessions, tokens, OAuth or OIDC, RBAC or ABAC, passkeys, service-to-service auth, and policy enforcement boundaries."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
+---
+
+# Auth Architect
+
+## Purpose
+
+Use when designing or reviewing authentication and authorization for backend systems, including sessions, tokens, OAuth or OIDC, RBAC or ABAC, passkeys, service-to-service auth, and policy enforcement boundaries.
+
+## When to Use
+
+- Designing or reviewing login, session, token, and policy architecture.
+- Choosing between session-based auth, JWTs, OAuth or OIDC, passkeys, or service credentials.
+- Defining RBAC, ABAC, tenant isolation, or field-level authorization boundaries.
+- Hardening auth flows in REST, GraphQL, NestJS, FastAPI, Node, or managed-platform backends.
+
+## Instructions
+
+1. Clarify actors, trust boundaries, clients, and the assets each flow protects.
+2. Choose the credential and session model that fits the product and operational constraints.
+3. Separate authentication, authorization, and audit responsibilities instead of blending them together.
+4. Make token, session, policy, and recovery behavior explicit at service boundaries.
+5. Verify revocation, rotation, least privilege, and failure behavior before shipping.
+
+### Baseline standards
+
+- Prefer server-owned sessions when revocation simplicity matters more than statelessness.
+- Treat OAuth or OIDC as delegated identity plumbing, not a substitute for local authorization rules.
+- Keep authorization policy close to the resource or resolver that owns the decision.
+- Design service-to-service identity and secret rotation as first-class operational concerns.
+- Make account recovery, MFA, and passkey fallback behavior explicit.
+
+### Constraints
+
+- Avoid mixing authentication and authorization into one vague middleware concept.
+- Avoid issuing long-lived bearer tokens with no rotation or revocation story.
+- Avoid duplicating policy rules across clients, gateways, and services with no clear owner.
+- Avoid treating passkeys, sessions, or JWTs as universal defaults independent of product constraints.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File                                           | Load when                                                                                                                                            |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/session-token-policy-checklist.md` | You need a deeper checklist for session vs token choice, OAuth or OIDC, passkeys, tenant isolation, service auth, and policy enforcement boundaries. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with auth architect best practices in this project"
+- "Review my auth architect implementation for issues"
+````

package/workflows/powers/auth-architect/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: auth-architect
+description: "Use when designing or reviewing authentication and authorization for backend systems, including sessions, tokens, OAuth or OIDC, RBAC or ABAC, passkeys, service-to-service auth, and policy enforcement boundaries."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
+---
+
+# Auth Architect
+
+## Purpose
+
+Use when designing or reviewing authentication and authorization for backend systems, including sessions, tokens, OAuth or OIDC, RBAC or ABAC, passkeys, service-to-service auth, and policy enforcement boundaries.
+
+## When to Use
+
+- Designing or reviewing login, session, token, and policy architecture.
+- Choosing between session-based auth, JWTs, OAuth or OIDC, passkeys, or service credentials.
+- Defining RBAC, ABAC, tenant isolation, or field-level authorization boundaries.
+- Hardening auth flows in REST, GraphQL, NestJS, FastAPI, Node, or managed-platform backends.
+
+## Instructions
+
+1. Clarify actors, trust boundaries, clients, and the assets each flow protects.
+2. Choose the credential and session model that fits the product and operational constraints.
+3. Separate authentication, authorization, and audit responsibilities instead of blending them together.
+4. Make token, session, policy, and recovery behavior explicit at service boundaries.
+5. Verify revocation, rotation, least privilege, and failure behavior before shipping.
+
+### Baseline standards
+
+- Prefer server-owned sessions when revocation simplicity matters more than statelessness.
+- Treat OAuth or OIDC as delegated identity plumbing, not a substitute for local authorization rules.
+- Keep authorization policy close to the resource or resolver that owns the decision.
+- Design service-to-service identity and secret rotation as first-class operational concerns.
+- Make account recovery, MFA, and passkey fallback behavior explicit.
+
+### Constraints
+
+- Avoid mixing authentication and authorization into one vague middleware concept.
+- Avoid issuing long-lived bearer tokens with no rotation or revocation story.
+- Avoid duplicating policy rules across clients, gateways, and services with no clear owner.
+- Avoid treating passkeys, sessions, or JWTs as universal defaults independent of product constraints.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File                                           | Load when                                                                                                                                            |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/session-token-policy-checklist.md` | You need a deeper checklist for session vs token choice, OAuth or OIDC, passkeys, tenant isolation, service auth, and policy enforcement boundaries. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with auth architect best practices in this project"
+- "Review my auth architect implementation for issues"

package/workflows/powers/auth-architect/references/session-token-policy-checklist.md

@@ -0,0 +1,45 @@
+# Session, Token, And Policy Checklist
+
+Load this when auth work needs more depth than the root skill.
+
+## Boundary and threat framing
+
+- List actors, clients, trust boundaries, and the assets each flow protects.
+- Decide where authentication ends and authorization begins.
+- Make audit and incident-response requirements explicit for privileged flows.
+
+## Session vs token choice
+
+- Prefer server-owned sessions when revocation, rotation simplicity, or browser ergonomics matter most.
+- Prefer short-lived access tokens plus refresh controls only when stateless distribution or delegated clients justify the complexity.
+- Avoid bearer-token sprawl across browser, mobile, and service clients without separate threat assumptions.
+
+## OAuth, OIDC, and delegated identity
+
+- Use OAuth for delegated access and OIDC for identity; do not collapse them conceptually.
+- Scope tokens narrowly and document token audience, issuer, and rotation behavior.
+- Keep provider callbacks, consent, and account-linking behavior explicit.
+
+## Authorization and policy
+
+- Keep RBAC, ABAC, tenant boundaries, and field-level policy checks close to the owning service or resolver.
+- Avoid duplicating policy logic in frontend code as the only enforcement layer.
+- Make authorization failure semantics predictable and observable.
+
+## Passkeys, MFA, and recovery
+
+- Treat passkeys as a primary sign-in option where product fit exists, not just a marketing add-on.
+- Make MFA enrollment, recovery, device loss, and fallback channels explicit.
+- Keep recovery flows at least as hardened as the primary sign-in flow.
+
+## Service-to-service auth
+
+- Use dedicated service identities, narrow scopes, and explicit secret or key rotation.
+- Keep human auth, machine auth, and webhook verification separate.
+- Make internal trust assumptions visible instead of implied by network location.
+
+## Operational safety
+
+- Log auth decisions without leaking secrets or raw tokens.
+- Verify revocation, logout, secret rotation, and key rollover behavior.
+- Recheck caching, GraphQL field policy, and background-job privilege boundaries before finishing.

package/workflows/powers/behavioral-modes/POWER.md

@@ -9,6 +9,7 @@ allowed-tools: Read, Glob, Grep
 # Behavioral Modes - Adaptive AI Operating Modes
 
 ## Purpose
+
 This skill defines distinct behavioral modes that optimize AI performance for specific tasks. Modes change how the AI approaches problems, communicates, and prioritizes.
 
 ---
@@ -20,6 +21,7 @@ This skill defines distinct behavioral modes that optimize AI performance for sp
 **When to use:** Early project planning, feature ideation, architecture decisions
 
 **Behavior:**
+
 - Ask clarifying questions before assumptions
 - Offer multiple alternatives (at least 3)
 - Think divergently - explore unconventional solutions
@@ -27,6 +29,7 @@ This skill defines distinct behavioral modes that optimize AI performance for sp
 - Use visual diagrams (mermaid) to explain concepts
 
 **Output style:**
+
 ```
 "Let's explore this together. Here are some approaches:
 
@@ -48,6 +51,7 @@ What resonates with you? Or should we explore a different direction?"
 **When to use:** Writing code, building features, executing plans
 
 **Behavior:**
+
 - **CRITICAL: Use `clean-code` skill standards** - concise, direct, no verbose explanations
 - Fast execution - minimize questions
 - Use established patterns and best practices
@@ -59,6 +63,7 @@ What resonates with you? Or should we explore a different direction?"
 - **NO RUSHING** - Quality > Speed. Read ALL references before coding.
 
 **Output style:**
+
 ```
 [Code block]
 
@@ -66,6 +71,7 @@ What resonates with you? Or should we explore a different direction?"
 ```
 
 **NOT:**
+
 ```
 "Building [feature]...
 
@@ -85,6 +91,7 @@ Run `npm run dev` to test."
 **When to use:** Fixing bugs, troubleshooting errors, investigating issues
 
 **Behavior:**
+
 - Ask for error messages and reproduction steps
 - Think systematically - check logs, trace data flow
 - Form hypothesis → test → verify
@@ -92,6 +99,7 @@ Run `npm run dev` to test."
 - Prevent future occurrences
 
 **Output style:**
+
 ```
 "Investigating...
 
@@ -108,6 +116,7 @@ Run `npm run dev` to test."
 **When to use:** Code review, architecture review, security audit
 
 **Behavior:**
+
 - Be thorough but constructive
 - Categorize by severity (Critical/High/Medium/Low)
 - Explain the "why" behind suggestions
@@ -115,6 +124,7 @@ Run `npm run dev` to test."
 - Acknowledge what's done well
 
 **Output style:**
+
 ```
 ## Code Review: [file/feature]
 
@@ -135,6 +145,7 @@ Run `npm run dev` to test."
 **When to use:** Explaining concepts, documentation, onboarding
 
 **Behavior:**
+
 - Explain from fundamentals
 - Use analogies and examples
 - Progress from simple to complex
@@ -142,6 +153,7 @@ Run `npm run dev` to test."
 - Check understanding
 
 **Output style:**
+
 ```
 ## Understanding [Concept]
 
@@ -165,6 +177,7 @@ Run `npm run dev` to test."
 **When to use:** Production deployment, final polish, release preparation
 
 **Behavior:**
+
 - Focus on stability over features
 - Check for missing error handling
 - Verify environment configs
@@ -172,6 +185,7 @@ Run `npm run dev` to test."
 - Create deployment checklist
 
 **Output style:**
+
 ```
 ## Pre-Ship Checklist
 
@@ -197,35 +211,111 @@ Run `npm run dev` to test."
 
 The AI should automatically detect the appropriate mode based on:
 
-| Trigger | Mode |
-|---------|------|
-| "what if", "ideas", "options" | BRAINSTORM |
-| "build", "create", "add" | IMPLEMENT |
-| "not working", "error", "bug" | DEBUG |
-| "review", "check", "audit" | REVIEW |
-| "explain", "how does", "learn" | TEACH |
-| "deploy", "release", "production" | SHIP |
+| Trigger                                        | Mode                |
+| ---------------------------------------------- | ------------------- |
+| "what if", "ideas", "options"                  | BRAINSTORM          |
+| "build", "create", "add"                       | IMPLEMENT           |
+| "not working", "error", "bug"                  | DEBUG               |
+| "review", "check", "audit"                     | REVIEW              |
+| "explain", "how does", "learn"                 | TEACH               |
+| "deploy", "release", "production"              | SHIP                |
+| "iterate", "refine quality", "not good enough" | EVALUATOR-OPTIMIZER |
+
+---
+
+## Workflow Patterns
+
+Three patterns govern how modes combine across multiple agents or steps. Use the simplest pattern that solves the problem — add complexity only when it measurably improves results.
+
+### 1. Sequential (default)
+
+Use when tasks have dependencies — each step needs the previous step's output.
+
+```
+[BRAINSTORM] → [IMPLEMENT] → [REVIEW] → [SHIP]
+```
+
+Best for: multi-stage features, draft-review-polish cycles, data pipelines.
+
+### 2. Parallel
+
+Use when tasks are independent and doing them one at a time is too slow.
+
+```
+[security REVIEW + performance REVIEW + quality REVIEW] → synthesize
+```
+
+Best for: code review across multiple dimensions, parallel analysis. Requires a clear aggregation strategy before starting.
+
+### 3. Evaluator-Optimizer (new)
+
+Use when first-draft quality consistently falls short and quality is measurable.
+
+```
+[IMPLEMENT] → [REVIEW with criteria] → pass? → done
+                      ↓ fail
+               feedback → [IMPLEMENT again]
+```
+
+**When to use:**
+
+- Technical docs, customer communications, SQL queries against specific standards
+- Any output where the gap between first attempt and required quality is significant
+- When you have clear, checkable criteria (not just "make it better")
+
+**When NOT to use:**
+
+- First-attempt quality is already acceptable
+- Criteria are too subjective for consistent AI evaluation
+- Real-time use cases needing immediate responses
+- Deterministic validators exist (linters, schema validators) — use those instead
+
+**Implementation:**
+
+```
+## Generator
+Task: [what to create]
+Constraints: [specific, measurable requirements — these become eval criteria]
+
+## Evaluator
+Criteria:
+1. [Criterion A] — Pass/Fail + specific failure note
+2. [Criterion B] — Pass/Fail + specific failure note
+
+Output JSON: { "pass": bool, "failures": ["..."], "revision_note": "..." }
+
+Max iterations: 3  ← always set a ceiling
+Stop when: all criteria pass OR max iterations reached
+```
 
 ---
 
-## Multi-Agent Collaboration Patterns (2025)
+## Multi-Agent Collaboration Patterns
 
 Modern architectures optimized for agent-to-agent collaboration:
 
 ### 1. 🔭 EXPLORE Mode
+
 **Role:** Discovery and Analysis (Explorer Agent)
 **Behavior:** Socratic questioning, deep-dive code reading, dependency mapping.
 **Output:** `discovery-report.json`, architectural visualization.
 
 ### 2. 🗺️ PLAN-EXECUTE-CRITIC (PEC)
+
 Cyclic mode transitions for high-complexity tasks:
+
 1. **Planner:** Decomposes the task into atomic steps (`task.md`).
 2. **Executor:** Performs the actual coding (`IMPLEMENT`).
 3. **Critic:** Reviews the code, performs security and performance checks (`REVIEW`).
 
 ### 3. 🧠 MENTAL MODEL SYNC
+
 Behavior for creating and loading "Mental Model" summaries to preserve context between sessions.
 
+### 4. 🔄 EVALUATOR-OPTIMIZER
+
+Paired agents in an iterative quality loop: Generator produces, Evaluator scores against criteria, Generator refines. Set max iteration ceiling before starting.
+
 ---
 
 ## Combining Modes
@@ -241,5 +331,6 @@ Users can explicitly request a mode:
 /implement the user profile page
 /debug why login fails
 /review this pull request
+/iterate [target quality bar]    ← triggers evaluator-optimizer
 ```
 ````